j1261 90007

HP OpenView Windows Developers
Guide
HP OpenView Integration Series
Windows NT Operating System, HP-UX, and Solaris
Manufacturing Part Number: J1261-90007

January 2000
Copyright 2000 Hewlett-Packard Company
Revision 1
January 2000
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.22719 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-2000 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.
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.
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.
Oracle 7 is a U.S. trademark of Oracle Corporation, Redwood City,
California.
OSF/Motif, Motif, and Open Software Foundation are trademarks of the
Open Software Foundation, Inc. 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.
Windows NT is a U.S. registered trademark of Microsoft Corporation.
Windows and MS Windows are U.S. registered trademarks of
Microsoft Corporation.
Contents
1. Developing Applications for HP OpenView Windows

Applications and the HP OpenView Platform . . . . . . . . . . . . . . . . . . . . .25
The Basics of Developing Applications. . . . . . . . . . . . . . . . . . . . . . . . . . .26
The HP OpenView Windows Registration Files . . . . . . . . . . . . . . . . . . .27
The Help System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
Using the HP OpenView Windows Programming Interface . . . . . . . . . .29
Linking Application Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Controlling the API Revision Used To Compile . . . . . . . . . . . . . . . . . .32
Retrieving NNM Version Information. . . . . . . . . . . . . . . . . . . . . . . . . .33
Linking OVW Applications on Solaris. . . . . . . . . . . . . . . . . . . . . . . . . .33
Developing Applications for the Windows NT Operating System . . . .33
Developing Applications for the Web. . . . . . . . . . . . . . . . . . . . . . . . . . .34
OVW Generated Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Building Consistent Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
2. Creating and Using Registration Files
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
How Registration Files Are Processed . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Application Registration Files for the Windows NT Operating System
and UNIX Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
ARF Support of Multiple Platforms and Remote Consoles . . . . . . . . .45
Application Registration File Support for Internationalization and
Localization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Application Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Defining Global Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Menu Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Defining Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Contents
Drop Action Registration for HP-UX and Solaris Applications . . . . . 83

Defining Dialog Box Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Application Registration for the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Web Launcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Application Registration for Network Presenter. . . . . . . . . . . . . . . . . 97
Creating Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Symbol Registration File Support For Internationalization and
Localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining Icon Symbol Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining Symbol Subclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Symbol Alert Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
100
100
103
109
114
Field Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Defining Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Field Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Field Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Example Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Combinations of Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Field Registration File Support for Internationalized and Localized
Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
3. Integrating with NNM Online Help
An Introduction to the Help System . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
OVW Help System Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Deciding Whether to use the HP OpenView Help System. . . . . . . . . . 130
Building and Integrating Help Information with HP OpenView
Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
The HP OpenView Windows Help Directory Structure . . . . . . . . . . 131
Adding Help Information to OVW Main Menu Bar . . . . . . . . . . . . . . . 132
Contents
Customizing the Help Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133

Adding Help Information for HP OpenView Windows Dialog Boxes . .135
Register an Enroll Block for an OVW Dialog Box . . . . . . . . . . . . . . .135
Adding Help Information for Application-Specific Help Access . . . . . .136
Incorporating Help Into Your User Interface . . . . . . . . . . . . . . . . . . .136
Application-Specific Help Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
Using the OVw Libraries to Display Help Information . . . . . . . . . . .138
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
4. Using the HP OpenView Windows API
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
The OVW Programming Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144
Connecting Applications to HP OpenView Windows. . . . . . . . . . . . . . .145
Defining Callback Routines for Events . . . . . . . . . . . . . . . . . . . . . . . . .146
OVW Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Action Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
Processing Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
Event Processing on HP-UX and Solaris . . . . . . . . . . . . . . . . . . . . . .151
Event Processing on the Windows NT Operating System . . . . . . . . .151
Checking for OVW Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
Processing X Events and OVW Events (HP-UX and Solaris Only) . .153
Using Your Own select() Loop (HP-UX and Solaris Only) . . . . . . . . .153
Checking the Event Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
Advanced Event Queue Management . . . . . . . . . . . . . . . . . . . . . . . . .154
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Retrieving a Routines Result Code . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Converting a Result Code to a String . . . . . . . . . . . . . . . . . . . . . . . . .155
Checking OVW IDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
Contents
Getting your Application Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Getting the Object Selection List . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selection Rules and the Selection List. . . . . . . . . . . . . . . . . . . . . . . .
The ovwSelectionListChange Event . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the Selection List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
158
159
159
160
Highlighting Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Using the Help Routines (HP-UX and Solaris Only) . . . . . . . . . . . . . . 162
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
5. Creating and Using Objects and Fields
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
The HP OpenView Windows Object Database . . . . . . . . . . . . . . . . . . .
Database Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Base Routines and their Variants . . . . . . . . . . . . . . . . . . . . . . . . . . .
168
168
168
169
169
Creating Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the FRF versus the API to Create Fields . . . . . . . . . . . . . . . .
Creating Fields Programmatically. . . . . . . . . . . . . . . . . . . . . . . . . . .
Converting between Field Names and Field IDs . . . . . . . . . . . . . . .
Defining Enumeration Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Retrieving Field Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Predefined Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
170
170
170
171
172
173
175
Creating Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Field Value Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Selection Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generating Unique Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Objects by Hostname or Selection Name . . . . . . . . . . . . . .
176
176
178
179
181
181
Contents
Getting/Setting Object Field Values . . . . . . . . . . . . . . . . . . . . . . . . . . . .183

Basic Field Value Get/Set Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
Other Ways to Get and Set Single Field Values . . . . . . . . . . . . . . . . .184
Getting All Fields Associated with an Object . . . . . . . . . . . . . . . . . . .185
Convenience Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187
Deleting Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190
The Steps for Deleting an Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . .190
Determining when to Delete Objects. . . . . . . . . . . . . . . . . . . . . . . . . .190
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192
6. Creating and Using Submaps
Map and Submap Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195
Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195
Submaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195
Symbol Status and Submaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198
Relationship Between Maps and Submaps. . . . . . . . . . . . . . . . . . . . .198
Submap Layout Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200
Submap Planes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201
Shared vs. Exclusive Submaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201
Persistent vs. Transient Submaps. . . . . . . . . . . . . . . . . . . . . . . . . . . .202
Submap Presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .203
Creating Submaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206
Creating a Submap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206
Displaying a Submap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .208
Choosing When to Create a Submap. . . . . . . . . . . . . . . . . . . . . . . . . .209
Organizing your Submap Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . .210
Closing a Submap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .210
Loading and Unloading Submaps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212
Changing Submap Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . .214
Contents
Changing a Submap Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Setting Submap Overlay. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Setting Submap Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Deleting a Submap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Getting Map and Submap Information. . . . . . . . . . . . . . . . . . . . . . . . .
Getting Map Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Application Configuration Information . . . . . . . . . . . . . . . .
Getting Submap Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
218
218
219
220
Opening and Closing Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Processing a Map Open Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Processing a Map Close Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Using Submap Background Graphics . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting and Clearing Background Graphics . . . . . . . . . . . . . . . . . . .
Symbol Placement and Background Graphics . . . . . . . . . . . . . . . . .
Image Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
229
229
229
230
Integrating your Application with an Existing Map Application . . . . 231

Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
7. Creating and Using Symbols
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Characteristics of Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Symbols versus Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Symbol Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Creating Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Icon Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Connection Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Multiple Symbols with a Single Call . . . . . . . . . . . . . . . . .
Deleting Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10
246
246
252
254
259
Contents
Creating Symbol Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260

Changing Symbol Appearance and Behavior. . . . . . . . . . . . . . . . . . . . .269
Changing a Symbols Appearance . . . . . . . . . . . . . . . . . . . . . . . . . . . .269
Changing a Symbols Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .275
Changing a Symbols Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .276
Changing a Symbols Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .276
Changing a Symbols Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .278
Setting or Clearing Application Interest in a Symbol . . . . . . . . . . . .279
Changing Status or Status Source . . . . . . . . . . . . . . . . . . . . . . . . . . .280
Retrieving Symbol Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .282
OVwSymbolInfo Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . .282
Retrieving Symbol Information with OVwGetSymbolInfo() . . . . . . .284
Getting Connection Symbol Information . . . . . . . . . . . . . . . . . . . . . .285
Getting a List of Symbols from a Submap . . . . . . . . . . . . . . . . . . . . .286
Symbol Type Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287
Retrieving Object Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288
The OVwObjectInfo Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . .288
Retrieving Object Information with OVwGetObjectInfo() . . . . . . . . .289
Getting Symbol IDs Associated with an Object . . . . . . . . . . . . . . . . .289
Getting a List of All Objects on a Map . . . . . . . . . . . . . . . . . . . . . . . .290
Global Attributes Versus Map-Specific Attributes . . . . . . . . . . . . . . .291
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .292
8. Map Editing and Map Events
Receiving Notification of Map Changes . . . . . . . . . . . . . . . . . . . . . . . . .295
Map Editing Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .295
Hidden Symbol Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297
Manage/Unmanage Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
An Event Handling Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299
11
Contents
Participating in Map Changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Map Editing Interactions with OVW . . . . . . . . . . . . . . . . . . . . . . . . .
Query-Verify-Confirm Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Choosing Which Confirm Event to Use . . . . . . . . . . . . . . . . . . . . . . .
Deleting a Symbol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
300
300
302
306
307
Participating in Map Locates In Transient Map Applications . . . . . . 309

Returning Locate Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Locating Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Considerations for Transient Submap Applications . . . . . . . . . . . . . . 312
Managing Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Cut and Paste Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Customizing Drag and Drop Operations for HP-UX and Solaris
Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Drag and Drop Behavior. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Customization Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assigning a Drop Action To a Drop Target . . . . . . . . . . . . . . . . . . . .
Associating a Drop Action with an Application Callback . . . . . . . . .
Application Drop Callback Invocation . . . . . . . . . . . . . . . . . . . . . . . .
316
317
319
320
321
321
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
9. Supporting Management Consoles
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Server File Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
OVW Server Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Communication with Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Distributed OVw API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Connecting to a Remote GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
The Application Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
12
Contents
Remote Application Execution (HP-UX and Solaris Only) . . . . . . . . . .333

10. Developing Internationalized and Localized Applications
Internationalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .337
Localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .338
HP OpenView Windows Internationalization Support . . . . . . . . . . . . .339
String Overloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .341
Developing Internationalized and Localized HP OpenView Windows
Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .342
Application Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .342
Localizing the Registration Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . .344
OVwSymbolType Argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .345
OVw APIs for Manipulating Application and Action Registrations .346
OVw APIs for Displaying Application, Action Symbol Class and
Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .348
Trapd.conf and SNMP traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .348
Consistency and Interoperability . . . . . . . . . . . . . . . . . . . . . . . . . . . .349
Considerations for Previously Localized Applications. . . . . . . . . . . . . .350
Application Registration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .350
Symbol Registration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351
Field Registration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351
OVwSymbolType and sym_types.h . . . . . . . . . . . . . . . . . . . . . . . . . . .352
OVwGetAppName(), OVwGetFirstAction(), OVwGetNextAction(),
OVwGetSymbolInfo(), OVwListSymbolTypes() . . . . . . . . . . . . . . . . .353
Japanese Default Map Name and Storage Location . . . . . . . . . . . . .353
Location of oid_to_sym File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .354
Warnings for Non-Internationalized Applications. . . . . . . . . . . . . . . . .355
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .357
13
Contents
11. Integrating Your Application with the HP OpenView Web

Model of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Web Session Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
361
361
361
362
Application Configuration and Integration. . . . . . . . . . . . . . . . . . . . . . 365

Using Browser Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Using OVwww APIs to Access Session Information . . . . . . . . . . . . . 368
12. Integrating with Logging and Tracing
Overview of Logging and Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
HP-UX and Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Windows NT Operating System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
The OVuTL Application Programming Interface . . . . . . . . . . . . . . . . . 379
13. Integrating with Process Management
Process Management for HP OpenView Applications . . . . . . . . . . . . . 383
The OVsPMD Application Programming Interface . . . . . . . . . . . . . . . 387
The Local Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Structure of the Local Registration File . . . . . . . . . . . . . . . . . . . . . .
General Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
First Line of the LRF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Second Line of the Local Registration File . . . . . . . . . . . . . . . . . . . .
389
389
389
390
391
Integration with NNM Automated Backup . . . . . . . . . . . . . . . . . . . . .

Automated Backup and Pre-NNM 6.0 Applications . . . . . . . . . . . . .
The Backup Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Three Ways of Integrating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Evaluating An Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Writing Backup Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
395
395
396
398
399
402
14
Contents
Integration via ovwMapClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .405

Integrating via Services (Background Processes). . . . . . . . . . . . . . . .406
A. Guidelines for Documenting Map Applications
General Map Application Information . . . . . . . . . . . . . . . . . . . . . . . . . .411
Registration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .412
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .413
Symbol Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .414
Submaps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .415
Dialog Boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .416
Dependencies on other Map Applications . . . . . . . . . . . . . . . . . . . . . . .417
B. An Example Application
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .421
C. Using the OVw API Reference Pages
Introductory Reference Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .440
Printing Reference Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .441
Run-Time Routines By Category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .443
Run-Time Routines By Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .448
15
Contents
16
Figures
Figure 2-1. Menu Integration Example . . . . . . . . . . . . . . . . . . . . . . . . . .59

Figure 2-2. Application Integration into Web Launcher . . . . . . . . . . . . .91
Figure 2-3. Computer Symbol Class . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Figure 2-4. House Symbol Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Figure 5-1. Lists of Field Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
Figure 5-2. Field Binding List Data Structures. . . . . . . . . . . . . . . . . . .186
Figure 6-1. Relationship between Maps and Submaps . . . . . . . . . . . . .199
Figure 7-1. Symbol Alert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .263
Figure 8-1. Query-Verify-Confirm Transactions . . . . . . . . . . . . . . . . . .302
Figure 9-1. Distributing Applications . . . . . . . . . . . . . . . . . . . . . . . . . .328
Figure 11-1. Services and Files for the Web Components . . . . . . . . . . .362
Figure 12-1. Windows NT Event Viewer . . . . . . . . . . . . . . . . . . . . . . . .378
Figure 13-1. Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . .384
Figure 13-2. Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .397
Figure 13-3. Decision Tree for Script Integration. . . . . . . . . . . . . . . . .400
Figure 13-4. Decision Tree for ovwMapClose Event Integration . . . . .401
Figure 13-5. Decision Tree for Background Process Integration . . . . .402
Figure 13-6. Backup Scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .403
Figure 13-7. API integration with Backup . . . . . . . . . . . . . . . . . . . . . . .406
Figure 13-8. Backup via Background Services . . . . . . . . . . . . . . . . . . .407
17
Figures
18
Tables
Table 2-1. Registration File Locations . . . . . . . . . . . . . . . . . . . . . . . . . . .41

Table 2-2. Global Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Table 2-3. Types of Process Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Table 2-4. Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
Table 2-5. Pull-down Menu Item Registration Components . . . . . . . . . .62
Table 2-6. Predefined Context Identifiers . . . . . . . . . . . . . . . . . . . . . . . .66
Table 2-7. Context Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Table 2-8. Pop-up Menu Item Registration Components . . . . . . . . . . . .71
Table 2-9. Symbol Alert Pop-up Item Parameters . . . . . . . . . . . . . . . . . .74
Table 2-10. Tool Bar Item Registration Components. . . . . . . . . . . . . . . .77
Table 2-11. Action Block Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Table 2-12. DropAction Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Table 2-13. Fields and Field Options . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Table 2-14. Tab Block Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Table 2-15. List Item Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
Table 2-16. Launcher Action Block Definitions . . . . . . . . . . . . . . . . . . . .96
Table 2-17. Interface-Specific Variations for Application Registration
Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
Table 2-18. Arc Definition Components . . . . . . . . . . . . . . . . . . . . . . . . .106
Table 2-19. Icon Symbol RGV Values . . . . . . . . . . . . . . . . . . . . . . . . . . .109
Table 2-20. Symbol Alert Registration Components . . . . . . . . . . . . . . .115
Table 3-1. Integrating Help to Pulldown Help Menus. . . . . . . . . . . . . .132
Table 3-2. Integrating Help to Application-Specific Help . . . . . . . . . . .137
Table 5-1. Convenience Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188
Table 6-1. Layout Algorithms for Submaps . . . . . . . . . . . . . . . . . . . . . .200
Table 7-1. Forms for Positioning Symbols . . . . . . . . . . . . . . . . . . . . . . .239
Table 7-2. HP OpenView Status Colors . . . . . . . . . . . . . . . . . . . . . . . . .240
Table 7-3. OVW - ISO Equivalents . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241
Table 7-4. Symbol Presentation Attributes . . . . . . . . . . . . . . . . . . . . . .244
Table 8-1. OVW Events and Callback Routines. . . . . . . . . . . . . . . . . . .296
Table 8-2. Locate Query Callback Information . . . . . . . . . . . . . . . . . . .310
Table 11-1. NNM Web CGI Programs . . . . . . . . . . . . . . . . . . . . . . . . . .364
19
Tables
Table 11-2. OV Web Launcher Configuration and Integration Points

Table 12-1. Functions in the OVuTL API . . . . . . . . . . . . . . . . . . . . . . .
Table 13-1. Functions in the OVsPMD API . . . . . . . . . . . . . . . . . . . . .
Table 13-2. Purpose of Each Line in a Local Registration File . . . . . .
Table 13-3. First Line of the LRF . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Table 13-4. Second Line of the LRF& . . . . . . . . . . . . . . . . . . . . . . . . . .
Table C-1. OVw API Manpages Grouped by Category . . . . . . . . . . . . .
Table C-2. Function to Reference Page Mapping . . . . . . . . . . . . . . . . .
20
366
379
387
389
390
391
443
448
Conventions
The following typographical conventions are used in this manual.
Font
What the Font Represents
Example
For book or manual titles, and for manpage

names.
Refer to the OVW Developers Guide.
To provide emphasis.
You must follow these steps.
To specify a variable that you must supply

when entering a command.
At the prompt type: rlogin

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 screen.
The Root map window ...
Italic
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
Bold
Text that you must enter.
At the prompt, type: ovstatus.
Keycap
Keyboard keys.
Press Return.
[Button]
Buttons on the user interface.
Click [NET]. Click on the [Apply]

button.
Menu
Items
A menu name followed by a colon (:)

means that you select the menu, then the
item. When the item is followed by an
arrow (->), a cascading menu follows.
Select Locate:Objects->by
Comment
21
Contact Information
Technical Support Technical support information can be found on the HP OpenView World
Wide Web site at:
http://www.hp.com/openview/support.html
________________________________
Documentation
Feedback
Your comments on and suggestions for the documentation help us

understand your needs and better meet them.
You can provide feedback about documentation via the HP
documentation site at:
http://ovweb.external.hp.com/lpe/doc_serv
Or you can fill out the form provided in electronic form with NNM:
Windows NT: \OpenView\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.
________________________________
Training
Information
For information on current HP OpenView training available, see the HP

OpenView World Wide Web site at:
http://openview.hp.com
Follow the links for Training to obtain information about scheduled
classes, training at customer sites, and class registration.
22
Developing Applications for HP

OpenView Windows
23
Developing Applications for HP OpenView Windows
HP OpenView is a family of tools and services for managing local and

wide area multivendor networks and distributed systems. HP OpenView
provides you with the tools you need to create system and network
management applications. You provide access to your applications
functionality through HP OpenViews graphical user interface,
HP OpenView Windows. With HP OpenView Windows, you can integrate
your system and network management applications with other similar
applications under a common user interface.
This chapter discusses the following:
Applications and the HP OpenView Windows platform.
The basics of developing HP OpenView applications, including using
the help system and registration files.
24
Chapter 1

Applications and the HP OpenView Platform
Applications and the HP OpenView Platform

HP OpenView Windows (OVW) serves as a platform upon which
developers can build a wide variety of systems and network management
solutions. Objects, symbols, and submaps can be shared by multiple
applications, enhancing the integration between applications.
This high level of integration benefits both developers and end users.
Developers benefit by being able to leverage existing applications and
objects to build new applications. End users benefit by seeing a
consistent user interface in which multiple applications work together in
an integrated, cooperative way.
Chapter 1
25

The Basics of Developing Applications
The Basics of Developing Applications

Developers construct HP OpenView Windows applications using two
basic components: registration files and the OVW programming libraries
(the OVw API).
Registration files are special configuration files that OVW reads when
OVW is started. Registration files can be used to perform many of the
functions that would otherwise require programming. More complicated
applications require that you write programs using the OVw API. The
OVw API gives you much more control over the behavior of OVW
applications, at the cost of more programming complexity.
26
Chapter 1

The HP OpenView Windows Registration Files
The HP OpenView Windows Registration Files

Registration files are ASCII files whose contents follow a C-like syntax.
The registration files are read when a new OVW session is started.
HP OpenView Windows configures the system based on the contents of
these files. There are three types of registration files: application, symbol
type, and field registration files:
An application registration file is used to integrate applications
into HP OpenView Windows. The entries in this file control how the
application is invoked and how the application process is managed.
Additionally the application registration file can control how
applications are integrated into the OVW main menu bar, pop-up
menus, and tool bar.
A symbol type registration file is used to define symbol classes
(the external shapes of symbols) and symbol subclasses (pixmaps
superimposed on symbol classes). HP OpenView Windows provides
developers with a large set of predefined symbol classes and
subclasses, but developers are free to define their own as well.
A field registration file is used to define fields, which are the
attributes of objects, in the OVW object database. Field registration
files define the data type and behavior for fields.
Chapter 1
27

The Help System
The Help System

HP OpenView Windows provides users with a comprehensive hypertext
help system to assist with their tasks. Each application should provide
its own help information. This benefits users, since they see help
information in a common, consistent way regardless of which application
supplies the help information.
On the Windows NT operating system, NNM provides help via WinHelp.
Refer to your Windows NT operating system documentation for
information on creating and integrating WinHelp with standard
windows applications.
On HP-UX and Solaris, NNM provides help via the Common Desktop
Environment (CDE) help system. Chapter 3 , Integrating with NNM
Online Help, explains how to integrate CDE help with HP OpenView.
For Web interfaces, NNM provides HTML help. Chapter 3 , Integrating
with NNM Online Help, explains how to integrate HTML help with HP
OpenView.
28
Chapter 1

Using the HP OpenView Windows Programming Interface
Using the HP OpenView Windows

Programming Interface
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 C++ compiler or the HP ANSI C++ compiler
may be used for development on HP-UX 10.X operating systems.
For HP-UX 11.0, the HP ANSI C++ compiler must be used for C++
source code. Additionally, 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++, version
5.0.
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 4.0.1, 4.1, or 4.2 compiler suite.
For Java development HP recommends JDK 1.1
NOTE
The OVw API functions are not thread safe.
While developers can implement much of an applications functionality

using OVW registration files, developers ultimately need to use the
HP OpenView Windows programming library to develop sophisticated
applications. The HP OpenView Windows programming interface is
called the OVw API.
The OVw API lets developers access the full breadth of HP OpenView
Windows functionality. The OVw API might appear intimidating at first,
since it contains over 200 API routines. As youll soon see, though, the
API routines are organized into groups which make them more
manageable. Subsequent chapters will present the OVw API routines in
groups, according to the functionality they provide. Also, the OVw API
lets you perform the same programming task in different ways. Though
you can use the full breadth of the OVw API if you want, a basic
understanding of a few key routines in each group will allow you to
implement fairly sophisticated applications.
Chapter 1
29

There are essentially seven groups of OVw API routines, organized as
follows:
Application integration
There are a small number of routines that integrate
your application with the HP OpenView Windows.
Every application that uses the OVw API needs to use
at least some portion of these calls. These routines
allow your application to connect to HP OpenView
Windows, to determine when users select particular
menu items, and to handle errors.
Object database access
There are over 40 OVw API routines that operate on
objects and fields. These routines are used to create
objects, to create the fields that comprise objects, to get
or set field values in objects, and to relate fields to
objects and vice versa.
Map and submap routines
The OVw API contains many routines that are used to
operate on maps and submaps. These routines let you
create and modify submaps, as well as retrieve
information about maps and submaps. A few OVw API
routines let you change the background images of
submaps.
Symbol routines
These routines create symbols, alter symbol behavior
and appearance, and get information about an object as
it exists on a map.
User verification
There are several OVw API routines that allow a
program to verify changes that a user attempts to
make to maps and objects via the user interface.
Dynamic registration
There are over 60 OVw API routines that dynamically
configure the OVW menu structure. These routines are
rarely used by most application developers.
30
Chapter 1

Callback routines
HP OpenView Windows uses callback routines to
communicate with applications when various events
occur. HP OpenView Windows provides many
definitions for callback routines to be provided by the
developer.
The following reference pages provide a good overview of the OVw
programming library. The OVw API reference pages are available online.
All of the OVw reference pages are listed in Appendix C , Using the
OVw API Reference Pages.
OVwApiIntro(5)
This reference page provides an

overview of the OVw API. It describes
important HP OpenView Windows
programming concepts, and should be
read by all developers.
OVwwwIntro

introduction to the HP OpenView
session API for CGI programs.
OVwEventIntro(5)
This reference page describes each

OVW event, as well as when and why
it is generated.
OVwRegIntro(5)
This reference page provides

complete specifications for the HP
OpenView Windows registration files
(application, symbol type, and field
registration files). The reference page
also contains the registration file
grammar.
LauncherRegIntro

OpenView Web Launcher registration
file including the registration file
grammar.
NetworkPresenterRegIntro

OpenView Network Presenter
Registration File.
Chapter 1
31

Linking Application Programs

Applications that use the HP OpenView Windows programming libraries
need to link to three different shared libraries: libovw, libov, and
libntl. You can access these libraries by providing the -lovw -lov
-lntl arguments to cc, CC, aCC, or ld. Applications must link with all
three libraries in the order specified here. For development on the
HP-UX 11.0 platform, applications must link with the aCC command.
This is the compile/link program that is part of the HP ANSI C++
compiler product.
Components of the OVw API which depend on X11R5 routines are part of
the library libXovw. Access these using the -lXovw option to cc, CC, or
ld.
The libovw.a library contains the HP OpenView Windows library
routines. The libov.a library contains general purpose utility routines
that are used internally by the HP OpenView Windows library routines.
The libntl.a library contains network tracing and logging library
routines that are also used by the HP OpenView Windows library
routines. See the OVwApiIntro(5) online reference page if you need more
information about linking applications.
Because libraries are no longer linked into the /usr/lib directory, you
need to specify -L$OV_LIB to cc, CC, or ld when linking your application.
The OVwww API functions are part of the library libovwww.a. Access
them using the -lovwww option to cc, CC, or ld. When linking with the
OVW library, you also need to link with the library libov. The libraries
should be linked in the following order:
cc ... -I$OV_HEADER -L$OV_LIB -lovwww -lov
Controlling the API Revision Used To Compile

OVwAPILevel is a C preprocessor macro that controls which version of
the OVw API your application uses. This overrideable macro is provided
to ease migration to new OVw API features.
By default, OVwAPILevel is defined in ovw.h as an integer matching the
current major revision of the OVw API. If, when you compile your C or
C++ source code, you define OVwAPILevel equal to a previous major
revision number, your application will compile without your having to
give attention to changes in OVw API data structures or call signatures.
The valid values for OVwAPILevel macro are 3, 4, 5, and 6.
32
Chapter 1

As an example, if you do not want to ensure that your application
properly handles the new fields added to the OVwSubmapInfo and
OVwSymbolInfo structures in the release 5 API, but you do want to
rebuild your application with the new release 5 shared libraries, you can
recompile your code as follows:
cc -DOVwAPILevel=4 -o myapp myapp.c -lovw -lov -lntl
Retrieving NNM Version Information

You can use the OVNNMVersion() function to retrieve information about
the currently installed version of Network Node Manager (NNM) to
determine whether the installed version of NNM is supported by your
product. OVNNMVersion() lets you check that the major version (and
optionally minor version) of NNM is greater than or equal to the minimal
version you support. For more information refer to the online reference
page for OVNNMVersion and to \OpenView\header\OV\OVVersion.h
(Windows NT operating system) $OV_HEADER/OV/OVVersion.h
(UNIX systems).
In addition, the ovversion command can be used in scripts to print to
standard output on a UNIX system (the console window on Windows NT
operating system). The default output is ovversion -nnm to print the
product version for Network Node Manager.
Linking OVW Applications on Solaris

You must use the Solaris compiler with the -xcg92 option to link OVW
applications developed for Solaris. The makefiles in the sample
applications found in \OpenView\prog_samples\ovw_examples
(Windows NT operating system) and $OV_PROG_SAMPLES/ovw_examples
(UNIX systems) provide examples for using this option.
If you do not use the Solaris compiler with the -xcg92 option, the linker
will fail, reporting an unsatisfied external reference to __cg92_used.
Refer to the Sun reference page for cc for additional information.
Developing Applications for the Windows NT

Operating System
The NNM Developers Toolkit dynamic load libraries are shipped in this
release as non-debug libraries. They depend upon the Microsoft Release
Chapter 1
33

versions of the C runtime and MFC libraries (MSVCRT.DLL,
MSVCIRT.DLL, MFC42.DLL). Therefore, applications compiled with
-D_DEBUG and linked with the Microsoft Debug DLLs may experience
application exceptions under the following conditions:
Application allocates memory that is deallocated by an HP OpenView
library
Application deallocates memory that is allocated by an HP OpenView
library
Application references a global variable that is defined by an
HP OpenView library
Developing Applications for the Web

Developers and administrators can integrate their web-based
applications with NNM through integration points in the HP OV Web
Launcher and the Network Presenter by editing registration and
configuration files. These integration points are described in Chapter 2 ,
Creating and Using Registration Files, and Chapter 11 , Integrating
Your Application with the HP OpenView Web,.
In addition, Java classes that provide Java bindings to libovw APIs are
available in
/opt/OV/contrib/NNM/java_libovw/www/htdocs/classes/libovw.j
ar on UNIX systems or
\OpenView\contrib\NNM\java_libovw\www\htdocs\classes\libovw
.jar on the Windows NT operating system. These unsupported classes
are provided as a convenience to developers.
34
Chapter 1

OVW Generated Dialog Boxes
OVW Generated Dialog Boxes

One last programming concept deserves mention here OVW-generated
dialog boxes. Before describing OVW-generated dialog boxes, though, we
need to supply some background.
An end user can perform a wide variety of operations through the user
interface. In many cases, OVW can handle the user operation without
requiring any help from the application. For example, an end user can
request help information from the Help menu item on the main menu
bar. OVW receives the request for help information and displays it
without requiring application assistance.
In other cases, though, HP OpenView Windows might require assistance
from the application before it can proceed. Specifically, there are four
operations that might require your applications involvement:
adding a symbol to a submap
connecting two symbols on a submap
modifying an objects attributes
changing how an application is configured to operate on a map.
These four operations are treated specially in HP OpenView Windows.
HP OpenView Windows acts as a mediator between the user and the
application, letting the application control whether the operations are
allowed. If the operations are allowed, OVW makes the changes on
behalf of the user and then informs the application.
HP OpenView Windows provides special assistance to developers who
support these operations in their applications. HP OpenView Windows
does not require that you implement dialog boxes yourself for these
operations. Rather, HP OpenView Windows lets you define the structure
of these dialog boxes using entries in the applications application
registration file. Using entries called enroll blocks, developers can define
the structure and behavior of these special OVW-generated dialog boxes
without writing code. These can ease the programming task for a certain
class of HP OpenView Windows applications.
Chapter 1
35

Building Consistent Applications
Building Consistent Applications

Application developers must make many choices when implementing
HP OpenView Windows applications. Some of those decisions affect the
physical appearance or behavior of the application. In order to provide
consistency between different applications, HP recommends that you
consult the HP OpenView Application Style Guide as you develop your
application. The style guide provides recommendations for developers to
ensure application consistency. For example, the style guide describes
how applications should construct dialog boxes and how applications
should use buttons and other user interface controls.
36
Chapter 1

Summary
Summary
Developers need to make use of two major components to implement HP
OpenView Windows applications: registration files and the OVw API.
Registration files are used to statically configure HP OpenView Windows
behavior. Developers can control application process behavior and menus
with the application registration file. The symbol type registration file is
used to define new symbol classes and subclasses, while the field
registration file is used to define new fields in the OVW object database.
Many applications can be integrated into HP OpenView Windows using
only the registration files.
The OVw API is required to implement more sophisticated
HP OpenView Windows applications. The OVw API contains over 200
routines and callback definitions, which allow you to control all aspects
of an applications behavior. The OVw API is the subject of much of the
rest of this manual.
Last, the HP OpenView Application Style Guide provides
recommendations for application consistency. Developers are expected to
consult the style guide as they are developing HP OpenView Windows
applications.
Chapter 1
37

Summary
38
Chapter 1
Creating and Using

Registration Files
39
Creating and Using Registration Files
This chapter describes the registration files used to configure

applications within HP OpenView (NNM). Registration files
communicate a wide variety of information to NNM, such as how
applications are integrated into NNM and how graphical symbols are
defined.
40
Chapter 2

Overview
Overview
This chapter explains how to:
support internationalized and localized user interface components
integrate applications into the HP OpenView user interface using
application registration files
define graphical symbols using symbol type registration files
define fields for objects using field registration files.
This chapter introduces the registration files, complete with some simple
examples. If you need more information, refer to the OVwRegIntro(5),
LauncherRegIntro(5), and NetworkPresenterRegIntro(5) reference pages.
Table 2-1 lists the locations for registration files.
Table 2-1
Registration File Locations
Platform
Registration
File
Pathname
UNIX systems
Application
/etc/opt/OV/share/registration/$LANG
Symbol
/etc/opt/OV/share/symbols/$LANG
Bitmap
/etc/opt/OV/share/bitmaps/$LANG
Field
/etc/opt/OV/share/fields/$LANG
Launcher
/etc/opt/OV/share/www/registration/launcher/
$LANG
Network
Presenter
/etc/opt/OV/share/www/registration/jovw/
$LANG
Application
\OpenView\registration\$LANG
Windows NT
operating system
Chapter 2
41

Overview
Table 2-1
Platform
Registration File Locations

Registration
File
Pathname
Symbol
\OpenView\symbols\$LANG
Bitmap
\OpenView\bitmaps\$LANG
Field
\OpenView\fields\$LANG
Launcher
\OpenView\www\registration\jovw\$LANG
Network
Presenter
\OpenView\www\registration/launcher\$LANG
The $LANG environment1 variable provides support for native language

localizability. If not otherwise defined, $LANG is assumed to be C, which
means no native language support is provided. For additional
information about internationalizing and localizing applications refer to
See Application Registration File Support for Internationalization and
Localization on page 46
Ensure that $OV_MAIN_PATH is set to the proper path for your operating
system. You can set this variable by sourcing ov.envvars.csh or
ov.envvars.sh for UNIX systems or by running ov.envvars.bat for
the Windows NT operating system.
1. $LANG represents the language preference of the user. $LANG can be set as
an environment variable on UNIX systems. On Windows NT operating
system the end user sets the language preference via the Control Panel. In
this book $LANG is represented as an environment variable.
42
Chapter 2

How Registration Files Are Processed

The application, symbol type, and field registration files are processed in
different ways. The application and symbol type registration files are
read once each time HP OpenView is started. When NNM begins
initialization, it searches the various pre-defined directories for
registration files. These predefined directories can be overwritten using
environment variables, such as OVwRegDir, OVwFieldDir, and
OVwSymbolDir. If any files are found in those directories, the files are
assumed to be registration files. For every application or symbol type
registration file found, NNM executes the following steps:
Opens the file.
Parses it for correctness.
If an entry is found to be in error, NNM prints error information to
stderr on UNIX systems or the console window on the Windows NT
operating system, indicating the file and line where the error
occurred. Possible errors include:
duplicate entries
ill-formed entries
If a valid entry is found, NNM performs the appropriate operation
(e.g., adding a menu item to the NNM menu structure or adding a
symbol to the NNM symbol palette).
The registration file parser looks for registration files in the paths set in
$OVwRegDir. If an application is registered in two files, the second
occurrence of the registration is ignored. If NNM is running in a localized
environment, registration files in the native language path are parsed
first. For example, if NNM is running in German language mode,
registration files in registrations/german.iso88591 would be parsed
before those in registration/C (note that this is not the only possible
directory for a German language application). You can parse a UNIX
system or Windows NT operating system application or symbol
registration file without actually displaying the NNM user interface by
executing the ovw -verify command. The parser will verify the
registration files, but actual registration is not carried out. To parse a
registration file for one of the web interfaces such as the launcher or the
Network Presenter use the command regverify.
Chapter 2
43

Field registration files are processed differently than the other
registration files. Field registration files are not processed when NNM is
started. Rather, administrators manually add the field entries to the
NNM object database using a special command. System administrators
execute the special ovw -fields command to add fields to the object
database. The field registration files are parsed for correctness and
checked for errors just as the other registration files, and errors are
reported to stderr on UNIX systems or the console window on the
Windows NT operating system. See the reference pages for ovw and
OVwRegIntro if you need more information about processing of field
registration files.
44
Chapter 2

and UNIX Systems
Application Registration Files for the

Windows NT Operating System and UNIX
Systems
Application registration files are used to integrate network and systems
management applications with the HP OpenView user interface. Many
aspects of an applications interaction with NNM are defined using an
application registration file (ARF). Application registration files provide
NNM with important information, such as
how to integrate the application into the NNM menu and tool bar
structure
how to invoke the application based on the users run-time selection
of menu items or executable symbols
how to manage an application process
where application-specific help information is located.
ARF Support of Multiple Platforms and Remote

Consoles
Application, symbol, and field registration files allow selective processing
of registration files based on platform and whether a session is running
on a remote console. The mechanism that the registration files use is
similar to the #ifdef of C++ for preprocessing registration files. This
mechanism has the following characteristics:
Recognizes #ifdef, #ifndef, #else, #endif. These keywords should
be used by developers to surround regions of registration file to be
processed in specialized circumstances. For example:
#ifdef WINNT
...
#else
<100>"HP-UX or Solaris Item"
....
#endif
Chapter 2
45

and UNIX Systems
For a more complete example, examine the registration file for OVW
in \OpenView\registration\C\ovw on the Windows NT operating
system or /etc/opt/OV/share/registration/C/ovw on UNIX
systems.
Defines the following flags:
HPUX (when running on HP-UX)
HPUX_9 (when running on HP-UX 9.X)
HPUX_10 (when running on HP-UX 10.X)
HPUX_11(when running on HP-UX 11.X)
SOLARIS (when running on Solaris)
SUN (when running on SunOS 4.X)
WINNT (when running on Windows NT operating system 4.X,
5.X)
NT (when running on Windows NT operating system 4.X, 5.X)
REMOTE_CONSOLE (when running on a remote console)
Does not support nesting of #ifdef.
Does not support defined, &&, ||, or !.
Application Registration File Support for

Internationalization and Localization
HP OpenView supports internationalization and localization. The
complete process of internationalization and localization for Network
Node Manager applications is described in Chapter 10 , Developing
Internationalized and Localized Applications. Also refer to the HP
OpenView Application Style Guide for design guidelines for designing
applications for internationalization and localization.
Application registration files support internationalization by allowing
the following components (within the registration files) to be localized:
application name (the DisplayString)
copyright strings
version strings
description strings
46
Chapter 2

and UNIX Systems
action name (the DisplayString)
menu labels, tool bar labels, and tool tips
comment strings
drop action help text.
All other application registration file components are nonlocalizable and
must be identical in each different language version of the application
registration file.
For example, if an application is to be localized into German, and you
want to use a German application name, German description, and
German menu labels, the application registration file might look like
this:
Application "New App" {
DisplayString "Engenes Programm"; /*Name of application*/
/*Displayed to user*/
Description "{Mein eigenes Programm."
}
...
MenuBar "Map" {
"Starten des Programmes" _S
}
}
Here, the DisplayString statement specifies the localized string of the

application name. New App is an internally-used string that must consist
only of ASCII characters and must be identical in all language versions
of this applications application registration files. Whenever NNM is
started in German language mode the DisplayString is displayed as
the name of the application. If DisplayString is not specified, the string
specified for Application is displayed instead.
When creating application registration files, apply the following
guidelines:
To internationalize applications:
Specify ASCII strings for application and action names.
Install your application registration file in
\OpenView\registration\$LANG on Windows NT operating
system or $OV_REGISTRATION/C on UNIX systems.
To localize applications:
Chapter 2
47

and UNIX Systems
Do not modify the ASCII specifications for Application and
Action.
Use DisplayString statements to specify localized strings for
application and action names.
Specify localized strings for description, version, copyright, and
the HelpString for DropActions.
Install your application registration file in
\OpenView\registration\$LANG on Windows NT operating
system or $OV_Registration/$LANG on UNIX systems where
$LANG is the locale name of the native language for the
application.
For additional information about internationalizing and localizing
applications refer to:
Localization
Applications
The OVwRegIntro(5) reference page.
Application Block
Applications integrate into HP OpenView using a structure in an ARF
called an application block. Each ARF contains a single application block
that represents a single application. An application can be defined only
once, and its name must be unique.
Registration file entries use a C-like syntax. The application block has
the syntax:
Application "application_name"{
/*
**APPLICATION DESCRIPTION
*/
DisplayString "localizable string for application name";
Version "localizable string";
Description {
"localizable string for application information",
"localizable string for application Information"
48
Chapter 2

and UNIX Systems
}
Copyright {
"localizable copyright information",
"localizable copyright information"
}
/*
**COMMAND BLOCK
*/
Command -process_flags "command_name" environment_variables;
/*
**ONLINE HELP LOCATION BLOCK
*/
HelpDirectory "help_directory_path";
/*
**NAME FIELD STATEMENT
*/
NameField "name", "name";
/*
** MENU BLOCK
*/
MenuBar <precedence> "localizable menu_name" _mnemonic
{
<precedence> "localizable menuItem"
Context (context_expression)
f.action "actionId";
f.menu "menuId";
}
Menu "menuId"
{
<precedence> "localizable menuItem" _mnemonic
}
/*
** ACTION BLOCK
*/
Chapter 2
49

and UNIX Systems
Action "actionId" {
DisplayString "localizable string";
MinSelected n;
MaxSelected n;
SelectionRule(rule) ;
NameField "field", "field";
Command "command";
}
/*
** POPUP MENU BLOCK
*/
PopupItem <precedence> "localizable menu_item"
Context Context_Expression
TargetSymbolType type
f.action "actionId" ;
/*
** SYMBOL ALERT MENU BLOCK
*/
PopupItem <precedence> " localizable menu_item"
TargetSymbolType SymbolAlert:"type"
/*
** TOOL BAR BLOCK -- UNIX systems Applications
*/
ToolbarButton <precedence> @"active_button:inactive_button"
/*
** TOOL BAR BLOCK -- Windows NT operating system Applications
*/
ToolbarButton <precedence> @"button,localizable tool tips
text"
/*
** DROP ACTION BLOCK
*/
DropAction "action_name"{
Operations [OpMove | OpCopy]+ ;
SelectionRule(rule_expression) ;
HelpString "localizable help_text";
}
50
Chapter 2

and UNIX Systems
/*
** ENROLL BLOCK
*/
Enroll <Dialog_Type> {
if <Rule> {
InitialVerify <On/Off> ;
Scale <n>;
Help <Browser/Quick> "HelpVolume:Keyword" ;
Field <Field specifications>{
DisplayString "localizable field name";
NoDisplay <On/Off> ;
ImmediateVerify <On/Off> ;
Label "Label :";
EditPolicy <Edit/NoEdit/EditOnCreation> ;
Geometry <X,Y,W,H> ;
SelectionListPolicy <None/Single/Multiple> ;
IntegerDisplayPolicy
<Integer/Unsigned/Hex/Octal/IPAddr>;
}
}
}
}
where application_name is the nonlocalizable ASCII string by which

NNM will refer to your application and "localizable string for
application name" is the localized string of the application name that is
used when the name of the application must be displayed by NNM. If the
DisplayString is not specified, NNM displays the ASCII string specified
for application_name when the applications name is displayed.
Application blocks define many aspects of the interface between NNM
and applications. The application block specifies, for a single application,
the following behavior :
the name, version, description, and copyright strings displayed for
the application
instructions for invoking the application command
where application help information is located
how the application is incorporated into the NNM menu structure (if
the application appears in the NNM menu bar, symbol pop-up menus,
or tool bar)
Chapter 2
51

and UNIX Systems
drag and drop customization for applications on HP-UX and Solaris
the format of dialog boxes that NNM can display on behalf of the
application.
The remainder of this section describes application specifications in more
detail.
Defining Global Statements

Table 2-2 lists the statements that are applied globally to the application
registration.
Table 2-2
Global Statements
Field
If Not Registered
Overrides
Description
Displays message in About Application

No description registered
None
Version

No version registered
None
Copyright

No copyright registered
None
DisplayString
Uses string specified for Application field
None
Command
Optional
Action Statements
HelpDirectory
Help topics cannot be displayed
None
NameField
Optional
Namefield in Action
Statements
Application Description
At run-time, end users can view an applications version string,
description, and copyright by selecting the Help -> About OpenView and
clicking on the [Applications] button. For this information to be
displayed properly, it must be preconfigured in the ARF.
The version is specified as a string in a Version section. The
applications purpose is specified in a Description block. The copyright
is defined in a Copyright block. The following example demonstrates:
/*
52
Chapter 2

and UNIX Systems
**APPLICATION DESCRIPTION
*/
Version "Mail Box Version 1.0";
Description {
"This is a mail box",
"registration file example",
"for the OVW Developers Guide."
}
Copyright {
"Copyright 1997:,
"Hewlett-Packard Company",
"All rights reserved"
}
The version string text must be a single line. The Description and
Copyright blocks are composed of one or more text strings separated by
commas. All of these strings may be localized. For example, if your
application will be run in German language mode, these strings would be
specified as German text.
Command
The Command section lists the complete command line used to invoke an
application. By being defined at the application block level, the command
is considered global. In other words, the application command will be
invoked the same way every time, even if the user selects the application
in different ways. Regardless of whether the user selects the application
through a menu item or through an executable map symbol, this
command will be used to invoke the program.
As you will see later, commands can also be defined on an individual, per
action basis. This allows applications to be invoked in slightly different
ways (for example, with different arguments) depending on the
particular user selection. Per-action commands will be discussed later in
Defining Actions on page 78.
Commands are delimited by quotes as shown in the following format
statement. Programs that are non-GUI applications, such as console
applications (Windows NT operating system) or tty-based applications
(UNIX systems), must be run in a console window on the Windows NT
operating system or an X terminal on UNIX systems.
The form for a command statement is:
Chapter 2
53

and UNIX Systems
Command -[process_flags] "command_name" $environment_variable;
You should use the full path to the command although part of the path
may be an environment variable such as $OV_MAIN/bin/mailmgr. The
following example illustrates a command declaration for UNIX systems:
Application "editor" {
Command "xterm -e /usr/bin/vi";
..
}
And on the Windows NT operating system a command declaration might

be:
Application "editor" {
Command "notepad";
...
}
Process Flags NNM can manage your application in a number of ways.

By default, NNM invokes your application at run-time when the user
selects the appropriate menu item or executable symbol. Each selection
by the user causes another instance of the application to be loaded and
executed. You can change this behavior by adding special flags to your
command entry in the application block.
If you want to use more than one process management option, they
should be combined in the same Command entry as shown in this example:
Application "Mail Manager" {
...
Command -Initial -Shared -Restart "mailmgr";
...
}
Three flags are defined: Initial, Shared, and Restart. Table 2-3
describes their use.
Table 2-3
Types of Process Flags
Process Flag
Purpose
Initial
Tells ovw to start the application when ovw is started. The application will be
invoked by the command specified in the <command string>.
Shared
Tells ovw that only a single instance of this application command should be
running at any time. Further, this application instance will be shared, servicing
multiple action requests.
54
Chapter 2

and UNIX Systems
Table 2-3
Types of Process Flags
Process Flag
Restart
Purpose
Tells ovw to restart the application if it should ever exit. This flag is intended for
applications that are required for normal NNM operation, such as those managing
the semantics of NNM maps.
Environment Variables HP OpenView provides a run-time
environment for applications. This run-time environment allows
applications to access values set for NNM environment variables.
Applications have access to a number of key items, including the menu
items used to invoke the application and the object selection list.
These environment variables can appear on the command line that
invokes the application. This example demonstrates a command that is
invoked with the first element in the selection list:
Application "Telnet" {
...
Command "/usr/bin/telnet $OVwSelection1";
...
}
Table 2-4 shows the environment variables that are available for your
use.
Table 2-4
Environment Variables
OVw Environment Variable
Purpose
OVwSelections
A string containing the selection names of the objects in the selection

list when the application is invoked. The names are separated by
blank characters.
OVwNumSelections
The number of selection names in the selection list when the

application is invoked.
OVwSelectionn (n=1...10)
OVwSelection1 is set to the selection name of the first object in the

selection list, OVwSelection2 is set to the second name, etc. These
strings are returned in the order in which their associated objects
were selected. The selection list is limited to 10 elements.
OVwActionID
The name of the action by which the application is invoked. Actions

are defined in the ARF and are described later.
Chapter 2
55

and UNIX Systems
Table 2-4
Environment Variables
OVw Environment Variable
Purpose
OVwMenuItem
If the application is invoked via a menu item, this environment

variable will contain the label of the menu item that caused the
action. Menu items are described later.
OVwAppName
This is the name of the application that has started and is connecting
to a GUI server.
OVServer
This is the name of the object database server host that stores the
map database and runs the object database daemon.
OVwSessionID
This is the name of the GUI session identifier.

Help Directory
All applications integrated under NNM can provide online help
information. The HelpDirectory entry in the application block defines
where the help information is located.
NNM assumes the string \OpenView\help\$LANG on the Windows NT
operating system or $OV_HELP/$LANG/ on UNIX systems is prefixed to
the directory name specified in the HelpDirectory entry.
Assume that the default language is English (LANG=C), and consider this
example:
...
/*
** ONLINE HELP LOCATION BLOCK
*/
HelpDirectory "MailBoxHelp";
...
}
In this case, the help files are found in $OV_HELP/C/MailBoxHelp on the

UNIX operating system and in \OpenView\help\C\MailBoxHelp on the
Windows NT operating system.
Help files may be called from a menu such as the Help menu, or from a
dialog box button. Items are added to the Help menu as pull-down menu
items (see Adding Items to the Help Menu on page 69). Help for dialog
boxes is defined in an enroll block (see See Enroll Block on page 85).
For example, an NNM help topic entry in an enroll block might be Help
56
Chapter 2

and UNIX Systems
Browser "nnm:IDescIpNetwrkAttsDbx". "nnm" is the name of the CDE
or WinHelp file containing the help topic and IDescIpNetwrkAttsDbx is
the ID name of the topic as it is defined in the CDE Help or WinHelp file.
Refer to the ipmap registration file for more examples.
Name Fields
The NameField statement lets you choose the name forms that are used
to construct the object selection list. A single NNM object can have
multiple names, such as
a selection name (NNMs unique name for the object)
an IP Hostname (for IP networks)
a user-defined or application-defined name
When a user selects an object on a map, the NNM selection list is built
using the objects selection name. The NameField section lets you choose
other name forms to construct the selection list. You can, for example,
request that only IP hostnames are used in the selection list.
The NameField is a convenient way to filter selections from the selection
list. Using a NameField section guarantees that actions or commands are
allowed only if all objects in the selection list have that name field. If one
or more objects do not have the appropriate name field, the command
will not be allowed (for example, the menu item would be greyed out). As
youll see later, you can construct more sophisticated filters using
selection rules, which are described in Table 2-11.
You can use any of the preregistered NNM name fields in the NameField
section, or you can create your own. The preregistered NNM fields are in
\OpenView\field\$LANG on the Windows NT operating system or
$OV_FIELDS/$LANG/ on UNIX systems. (Field definitions are described
in Field Registration File.)
You can supply multiple names, separated by commas, in the NameField
statement. NNM will check the objects names against each name
specified in the NameField statement. If multiple names are specified in
the NameField statement, NNM will use the first name that is valid for
the object. The NameField statement has the following form:
NameField "string", "string";
A previous example demonstrated how to invoke telnet with an NNM

shell environment variable. This would work well if the selection item
was the same as the hostname and the host was capable of supporting
Chapter 2
57

and UNIX Systems
telnet. It would be inappropriate, however, for a modem. By
supplementing the Command section of the registration file with a
NameField section, you can guarantee that the command is invoked with
a list of selected items appropriately filtered. You can extend the telnet
example by filtering out all selected items that do not have hostnames, as
in the following example.
Application "Telnet" {
...
Command "telnet $OVwSelection1";
NameField "IP Hostname";
...
}
In this example, the command would be enabled only if all objects in the
selection list have an IP Hostname name field. The command would be
invoked using the first object in the selection list as an argument.
Menu Registration
A key feature of HP OpenView is its ability to integrate network and
systems management applications with common menu and tool bar
interfaces. This is accomplished through the application registration file.
This section shows you how to integrate applications into Network Node
Manager menus by adding pull-down menu items, symbol pop-up menu
items, and tool bar buttons. Their specifications in the ARF are similar.
All text labels for menu and tool bar items can be localized. For example,
if your application will be run in German language mode, labels would be
specified as German text. Refer to Application Registration File Support
for Internationalization and Localization on page 46 for general
information about localizing your application registration file.
Refer to Defining Symbol Pop-up Menus for instructions for creating
pop-up menus for symbols.
Defining the Pull-Down Menu Structure
Two sections of the application registration file provide specification for
menu registration: MenuBar and Menu.
MenuBar
Declares menu selections for top-level menus on the

menu bar.
Menu
Declares selections for menu cascades included within
58
Chapter 2

and UNIX Systems
the top-level menus (the first cascade beneath a menu
bar item).
Figure 2-1
Menu Integration Example
MenuBar <90> "Mail Manager" _a
<100> "Receive Mail" _R

Context (WantMailMenus)
f.menu "GetMail";
Menu "GetMail"
{
<100> "Open Mail"
_O
f.action "OpenMail";
<100> "Forward Mail"
_F
f.action "ForwardMail";
<100> "Delete Unopened Mail" _D
f.action "DeleteMail";
}
Figure 2-1 relates statements from the menu block of a registration file
to a completed menu. The following sections describe the syntax for these
statements and explain how to attach executable commands to both
pull-down and pop-up menu items.
Menu Bar Registration Application integration begins in the main
menu bar. A MenuBar block is defined that specifies the menu label on the
main menu bar under which the application will eventually appear. If
the menu bar item does not exist, NNM creates it for you. If it already
exists, NNM makes the association to the pre-existing menu item. The
menu bar declaration has the following format:
Chapter 2
59

and UNIX Systems
Application "ApplicationName" {
MenuBar <Precedence> "localizable MenuName" _Mnemonic{
...
}
...
}
You can define where your menu name will appear on the menu bar by
assigning a precedence to it. Menu bar precedence is from left (<100>) to
right (<0>). The default precedence value is <50>. When menu items
have the same precedence, NNM will place any of its registered menu
items first followed by the remaining menu items in alphabetical order
by application name.
You can specify an optional mnemonic character that allows users to
make a menu bar selection by typing a single character. The character
should correspond to one of the letters in the menu name. In the Mail
Manager example, we cannot use M as the mnemonic, because we know
that it is the mnemonic character for the Map menu provided by NNM.
Instead, well use an _a. The case of the mnemonic character
specification in the registration file should match the case of the
corresponding character in the menu name. For that reason, the
mnemonic character in our example will be a lower case a. For example:
Application "Mail Manager" _a {
...
MenuBar <100> "Receive Mail" _R
...
}
...
}
In this example, application integration begins under the Mail Manager

menu bar entry. The user can select this menu item by either using the
mouse or by typing a after the menu bar is activated for keyboard input.
As you can see in the example shown in Figure 2-1, the mnemonic
character is underlined so that the user can easily identify it.
Menu Block A menu block lets an application specify a group of
pull-down menu items. Each menu item on a pull-down menu can
be associated with another menu item (it cascades to another menu
item)
be associated with an action that invokes a command
results in a separator
60
Chapter 2

and UNIX Systems
The format for a menu block declaration is
MenuBar <precedence> Menu_Name _mnemonic {
/*Pulldown menu items displayed as when user clicks on menu
**bar item defined above
*/
f.menu "menuId";
}
/*Menu item that cascades from second item in
**the main pulldown menu
*/
Menu "menuId" {
}
Menu Item Registration A pull-down menu item is composed of the

following components:
<Precedence> "localizable MenuItem" _mnemonic accelerator
context_expression
function;
Table 2-5 explains each component of a pulldown menu declaration.

Precedence and mnemonic are used here just as they were used in the
MenuBar declaration (Menu Bar Registration on page 59). An
accelerator (a keystroke sequence that invokes the menu selection)
should be provided for menu items that you believe a user will want to
access frequently.
The last two items in the menu declaration, function and context
expression, require more discussion. First, we will examine how to use
the function item to build cascading menus (Building Cascading
Pull-down Menus on page 63). Next, we will see how to use the function
item to associate an action with a menu item (Defining Actions on page
78). Finally, we will look at how to use context expressions to place
Chapter 2
61

and UNIX Systems
pull-down and pop-up menu items and tool bar buttons on submaps
(Associating Menu Items and Tool Bar Buttons to a Target Submap on
page 66).
Table 2-5
Pull-down Menu Item Registration Components
Menu Item
Components
Precedence
Purpose
A precedence value indicating how the menu item should be ordered.
Menu items are displayed according to the ordered precedence, and, within items
of equal precedence, in alphabetical order by application name. Precedence of
items on a pull-down menu is top <100> to bottom <0>. The default value is 50.
MenuItem
This string is the label for the menu item as it should appear in a menu. This string
can be localized. For example, if your application will be run in German language
mode, labels would be specified as German text. Refer to Application
Registration File Support for Internationalization and Localization on page 46
for more information on localization and internationalization.
Mnemonic
A single character mnemonic for keyboard selection, as in the example.You can

specify an optional mnemonic character to allow keyboard selection by typing a
single character. The character should correspond to one of the letters in the menu
name. The case of the mnemonic character specification in the registration file
should match the case of the character that it corresponds to in the menu name.
Accelerator
A keystroke sequence that invokes the menu selection without displaying the
menu. This is also called a keyboard accelerator. The syntax for these options are
specified in the OVwRegIntro reference page.
Context
Expression
The context expression is a placement rule that defines which submap contexts
should include the pull-down menu item. This is optional for pull-down menu
items. If it is omitted, the menu item is implicitly generic and will appear on all
submaps that havent blocked it by including NoGeneric or NoDefault in their
contexts.
Otherwise, the rule is specified with the keyword Context followed by a context
expression. The context expression is made up of context identifiers, parenthesis,
logical ANDs (&&), and logical ORs (||). The reserved context identifier
AllContexts may be used in the expression to indicate that the item should be
placed generically on all submaps that dont include NoGeneric in their context.
62
Chapter 2

and UNIX Systems
Table 2-5
Pull-down Menu Item Registration Components
Menu Item
Components
Function
Purpose
Describes the behavior of each menu selection:
f.separator
Indicates that this should be a menu item separator.
f.menu
Provides the declaration of a menu cascade within a menu.

Menus in the NNM menu structure will be extended to include
the new entry, or, if one doesnt exist, a new cascading menu
will be created. Building Cascading Pull-down Menus on
page 63 illustrates how to use this declaration.
f.action
Associates an application invocation, or action, with the menu

item. When the user selects the menu item, the application is
invoked appropriately. The application is notified of the
selected action. Associating Actions with Menu Items on
page 64 explains how to use this declaration, and Defining
Actions on page 78 explains how to define an action to be
associated with the menu item.
Specifies a shell command to allow quick integration of shell

commands into menu selections. Note that if attributes of the
menu item should be specified, such as the number of
selections or a selection rule, then you should declare an
action with this information and list the desired shell
command in the menu item arguments.
Building Cascading Pull-down Menus In the following menu block,

notice how the function statement (f.menu "menuId") for the first menu
item in the menu bar menuId links menuItem1 to a new group of menu
items.
MenuBar <precedence> "localizable menu_Name" _mnemonic
{
<precedence> "localizable menuItem1"
f.menu "menuId"};
}
Menu "menuId"{
}
Chapter 2
63

and UNIX Systems
The following example shows how this is implemented. GetMail is an
identifier for a group of menu items that will cascade off of the
Receive Mail item in the Mail Manager menu. Figure 2-1 shows the
resulting menu:
/*
** MENU BLOCK
*/
{
<100>
"Receive Mail" _R
f.menu "GetMail";
}
Menu "GetMail"
{
<100> "Open Mail" _O
f.action "OpenMail";
<100> "Forward Mail" _F
<100> "Delete Unopened Mail" _D
f.action "DeleteMail";
}
Associating Actions with Menu Items Actions can be associated

with menu items in the same way that cascading menus are associated.
In the following menu block, notice the function statement, f.action
"actionId", for the first menu item in the menu bar actionId links
menuItem to an action definition.
MenuBar <precedence> "localizable Menu_Name _mnemonic
{
}
Action "actionId"
{
...
}
64
Chapter 2

and UNIX Systems
The following example shows how this is done. SendMail is an action
that will occur when the Send Mail menu item is selected:
/*
** MENU BLOCK
*/
{
<100>
"Send Mail" _S Context (WantMailMenus)
f.action "SendMail";
}
/*
** ACTION BLOCK
*/
Action "SendMail"
{
MinSelected 1;
MaxSelected 1;
Command 'mgrsend';
}
Defining Actions on page 78 explains how to complete the definition of

the action block.
Targeting Menu Items and Toolbar Buttons to Submap Context
Menu items and tool bar buttons can be targeted for display on submaps
based on the purpose or context of the submap. For example, the
purpose or context of a submap may be printer management. The context
of another submap might be plotter management. Using context to place
menu and tool bar items is a two part process. First, the context of a
submap must be defined. It can be defined by end users via the Submap
Description dialog box or by applications dynamically. Second, in an
ARF, each menu item or tool bar button can be associated with one or
more submap contexts to target the particular submaps in which the
menu item should be placed.
When a submap is opened the full list of possible associations defined in
the application registration file is checked against the submaps defined
context. If the context association defined for the menu item or tool bar
button evaluates as true for the submap, that menu item or tool bar
button will be visible.
Defining the Target Submap context is a list of context identifiers.
An end user or developer can define new context identifiers that are
application specific or may select one from the predefined context
Chapter 2
65

and UNIX Systems
identifiers provided by NNM. For example, a particular submap intended
for printer management might have an application-specific context of
wantPrinterMenus and a predefined context of NoGeneric. This submap
context would limit menu items and tool bar buttons to those that were
targeted to submaps using the wantPrinterMenus context identifier.
When possible, use context identifiers created by another application.
Reuse of context identifiers provides a higher level of integration among
applications and minimizes the number of context identifiers other
developers must consider.
Table 2-6 shows the predefined context identifiers. It is necessary to
surround the context identifier with quotation marks only when required
for delimiting. When changing context through the NNM graphical user
interface, use unquoted context identifiers only.
ovwAllContexts and ovwAnySymbol are C constants for use with the
OVw API. The advantage of using one of these constants is that it allows
the compiler to catch spelling errors. The OVw API calls also accept
quoted identifier strings for reserved and non-reserved context
identifiers. You must have the HP OV NNM Developers Kit to use the
OVw APIs.
Table 2-6
Predefined Context Identifiers

Reserved Word
Definition
NoDefault
A context identifier that blocks menu items that have

empty context expressions or no context expression.
NoGeneric
A context identifier that blocks all menu items that have a

Context specified as AllContexts as well as any that
have an empty context expression or no context
expression.
For additional information, refer to Managing Your Networks for a

description of setting submap context via the user interface and to
Setting Submap Context on page 208to the HP OpenView Windows
Developers Guide for a description of using the OVw APIs to set submap
context.
Associating Menu Items and Tool Bar Buttons to a Target
Submap In an application registration file, each menu item and tool
bar button includes an association in the form of a context expression
that targets the submap context in which the menu item or button
66
Chapter 2

and UNIX Systems
should be displayed. This expression acts as a placement rule
describing the submap context in which the menu item or button can be
placed. You use the same methods to create context expressions for
placement of pull-down menus and tool bar. Pop-up Menu Items on
page 67 explains the additional step needed to use context for placement
of pop-up menu items.
Targeting menu items to particular submaps requires knowing the
submaps contexts. If the menu-creating application also created the
given submap, then the submap context is known. Otherwise a context
identifier must be added to the submap or the submaps context must be
discovered. The context may be discovered by examining the Submap
Context dialog box.
The context expression in the definition of a menu item, pop-up item, or
tool bar item may be empty or may be a limited Boolean expression
whose terms are context identifiers:
Empty or unset: the menu item or tool bar button is implicitly generic
and appears on any submap that does not include NoDefault in its
context.
Limited Boolean expression: the menu item or tool bar button appears
only on submaps for which the Boolean expression evaluates to true. The
Boolean expression may contain one or more context identifiers,
parenthesis, logical ANDs (&&), and logical ORs (||).
A specialized menu item definition for a printer management submap
might look like this:
"StopPrinter" Context (WantPrinterMenus)
f.action "Stop_printer";
Generic menu items and tool bar buttons can be excluded from a
special-use submap if the submap context includes the reserved context
identifier, NoGeneric.
A reserved context expression, AllContexts, is also available to specify a
generic menu item or tool bar button that should be placed in all
submaps that do not include NoGeneric in their contexts.
A generic menu item might have a definition such as:
"Add Object to Keylist" Context(AllContexts)
f.action "Add_keylist";
Pop-up Menu Items Symbol pop-up menu items are placed in a given
symbols pop-up menu based on target context and the symbols type.
Chapter 2
67

and UNIX Systems
Unlike a submap, a symbol does not have a context. Therefore, the
context of the submap that contains the symbol determines the target
context. This context changes if the context of the containing submap is
modified or if the symbol is moved to another submap.
This means that there are two parts to placing a pop-up menu item on a
particular submap: a context expression and a target symbol type. Both
must be specified. The context expression is evaluated based on the
context of the symbols containing submap and is specified with the
keyword Context followed by a context expression.
The symbols type is specified with a class and subclass which takes on
the form <class>:<subclass>. The format for a pop-up symbol context
expression is:
Context (context_expression) TargetSymbolType
SymbolClass:SymbolSubclass;
The keyword ANY can be used to generalize the TargetSymbolType.

Example The following example demonstrates how context expressions
are used as placement rules to define when menu items should be placed
in a submaps menus. For the example, four submaps are created with
the following contexts defined:
Submap A, Context is empty
Submap B, Context={SysAdmin}
Submap C, Context={IsIP, WantPrintMenus, NoGeneric}
Submap D, Context={IsIPX, SysAdmin, WantPrintMenus,
WantPlotMenus, NoDefault}
Table 2-7 explains the display of menu items based on the interaction
between the following menu registration and the contexts of each

submap:
Application "My_App" {
...
MenuBar <100> "MISC"
_i {
<60> "Create Box"
_C f.action "create_box";
<60> "Event Mgr"
_E
Context AllContexts
f.action "E_Mgr";
<60> "Sep"
Context AllContexts
f.separator;
68
Chapter 2

and UNIX Systems
<60>
<60>
<60>
"Diagnose Printer"
Context (WantPrintMenus)
f.action "diag_pr";
"Diagnose Plotter"
Context (WantPlotMenus && (IsIP || IsIPX))
f.action diag_plot";
"Query Node"
_Q
Context (IsIP) f.action "query_node";
}
...
}
Table 2-7
Context Example
Submap Context
Menu Items Displayed
Submap A, Context is empty
Because there is no context list, this submap defaults to allowing

only generic menu items. Create Box, the separator, and Event
Mgr are the only items that qualify.
Submap B,
Context={SysAdmin}
This submap will accept generic menu items and any menu item
targeted to the context identifier, SysAdmin. Of the items above,
only the generic menu items qualify: Create Box, the separator,
and Event Mgr.
Submap C, Context={IsIP,
WantPrintMenus,
NoGeneric}
This submap will allow only items specifically targeted with IsIP
and/or WantPrintMenus. Diagnose Printer and Query
Node are both satisfied by this context. The generic menu items
are explicitly blocked from this submap.
Submap D, Context={IsIPX,
SysAdmin, WantPrintMenus,
WantPlotMenus, NoDefault}
This submap allows items targeted with one or more of the

specified context identifiers and explicitly generic menu items
(whose context is AllContexts). Implicitly generic menu items
like Create Box are not displayed because of the NoDefault
context identifier. The menu separator, Event Mgr, Diagnose
Printer, and Diagnose Plotter all will be displayed.
Adding Items to the Help Menu You can add links to online help to
the Help menu or to a dialog box button. For example, an NNM help topic
entry on the Help Menu might be f.help_browser "nnm:goto". In this
example, "nnm" is the name of the CDE or WinHelp file containing the
help topic and "goto" is the ID name of the topic as it is defined in the
CDE Help or WinHelp file. Refer to the ovw, nnm, and ovwnavigator
registration files for more examples.
Chapter 2
69

and UNIX Systems
The HelpDirectory entry in the application block defines where the
help files are located (see Help Directory on page 56).
Help for dialog boxes is defined in an enroll block (see See Enroll Block
on page 85).
Defining Symbol Pop-up Menus
Creating a pop-up menu is similar to creating a pull-down menu.
Application developers can create symbol pop-up menu items, both
through the ARF and with the OVw API. You must have the HP
OpenView NNM Developers Kit if you want to use the OVw APIs.
Symbol pop-up cascade menus are defined with a PopupMenu block
which, like a MenuBlock, contains a list of menu items. A pop-up menu
item is composed of the following components which are explained in
Table 2-8:
70
Chapter 2

and UNIX Systems
PopupItem <Precedence> "localizable Label"
TargetSymbolType type
Function;
Table 2-8
Pop-up Menu Item Registration Components
Menu Item
Components
Precedence
Purpose
A precedence value indicating how the menu item should be ordered.
Menu items are displayed according to the ordered precedence, and, within items of
equal precedence, in the application name order. Precedence is specified as an
unsigned integer value; 100 is the highest precedence, 0 is the lowest.
Menu Label
This is the label for the menu item as it should appear in a menu. This string can be
localized. For example, if your application will be run in German language mode,
labels would be specified as German text. Refer to Application Registration File
Support for Internationalization and Localization on page 46 for more information
on localization and internationalization.
Context
Expression
The context expression is a placement rule defining which symbols should have the
menu item. Refer to Targeting Menu Items and Toolbar Buttons to Submap Context
on page 65 for a general discussion about setting and using submap context and to
Pop-up Menu Items on page 67 for additional information about using context in
pop-up menus.
The target symbol type is specified with the keyword TargetSymbolType, followed
by a symbol type. The symbol type may be set to Any, <symbol name>:Any, or a
fully specified <class name>:<subclass>. The keyword Any is used to
generalize the target symbol type.
Chapter 2
71

and UNIX Systems
Table 2-8
Pop-up Menu Item Registration Components
Menu Item
Components
function
Purpose
Describes the behavior of each menu selection:
f.separator
Indicates that this should be a menu item separator.
f.menu
Provides the declaration of a menu cascade within a menu.

Menus in the NNM menu structure will be extended to include
the new entry, or, if one doesnt exist, a new cascading menu will
be created. Building Cascading Pull-down Menus on page 63
explains how to use this function.
f.action
Associates an application invocation, or action, with the menu

item. When the user selects the menu item, the application is
invoked appropriately. The application is notified of the selected
action. Associating Actions with Menu Items on page 64
explains how to use this function and Defining Actions on
page 78 explains how to complete an action definition.

menu item should be specified, such as the number of selections
or a selection rule, then you should declare an action with this
information and list the desired shell command in the menu item
arguments.
Pop-up Menu Registration Example The following example shows
how these fields are used in the registration file.
Application "Mail Manager" _a
...
/*
** POPUP MENU BLOCK
*/
PopupItem <60> "PopupSeparator2"
Context (AllContexts || WantPopupMenus ||
WantMailMenus)
TargetSymbolType ANY f.separator;
PopupItem <50> "Configure Mailbox"
72
Chapter 2

and UNIX Systems
Context WantMailMenus
TargetSymbolType Mailbox:Rural
f.menu "ConfigureMailBox";
PopupItem <50> "Empty Mailbox"
f.action "EmptyMailBox";
PopupMenu "ConfigureMailBox"
{
"Add User"
f.action "AddUser";
"Change Address"
f.action "ChangeAddress";
}
...
}
The pop-up menu contents depend on the symbol in question as well as

the contexts of its parent submap. Refer to Targeting Menu Items and
Toolbar Buttons to Submap Context on page 65 for an explanation of
how to use submap context.
Symbol Alert Pop-up Menu Registration
A symbol alert provides a way to get a users attention. It is a visual cue
to facilitate monitoring at a glance and is intended for use when there
are urgent conditions which are of immediate importance. For additional
information, refer to Symbol Alert Type on page 114 and Chapter 7 ,
Creating and Using Symbols,. Chapter 7 of the HP OpenView Windows
Developers Guide.
NOTE
Symbol alert pop-up menu registration is used along with the application
programming interfaces to provide menus for symbol alerts.
Administrators should have no need to create or modify pop-up menus
for symbol alerts.
The symbol alert pop-up menu differs from a symbol pop-up menu in two
ways:
Chapter 2
73

and UNIX Systems
The menu items that are located in the symbol alert menu are those
that have been registered by a single application (in contrast to the
symbol pop-up items that are a collection of items from multiple
applications).
While the target object for each action is the base symbol (the symbol
to which the symbol alert is attached), the application is expected to
carry out the action in any way that is appropriate with any object or
objects that the application considers appropriate as targets of the
action.
Registration is similar to that used for symbol pop-up registration:
PopupItem <Precedence> "localizable label"
Context Context
TargetSymbolType SymbolAlert:type
f.action actionId
Cascade menus are also supported for symbol alert pop-up menus.
Registration is similar to that used for symbol pop-up cascade menus.
Table 2-9
Symbol Alert Pop-up Item Parameters
Parameter
Description
Label
This is the text for the label. This string can be localized. For example, if your
application will be run in German language mode, labels would be specified as
German text. Refer to Application Registration File Support for
Internationalization and Localization on page 46 for more information on
localization and internationalization.
Context
Expression
The context expression is a placement rule defining which symbols should have
the menu item. Refer to Targeting Menu Items and Toolbar Buttons to Submap
Context on page 65 for a general discussion about setting and using submap
context and to Pop-up Menu Items on page 67 for additional information about
using context in pop-up menus.
The target symbol type is specified with the keyword TargetSymbolType,
followed by a symbol type. The symbol type may be set to Any, <symbol class
name>:Any, or a fully specified <class name>:<subclass>. The keyword
Any is used to generalize the target symbol type.
Type
For symbol alerts the type is specified as SymbolAlert:symbol_alert_name.

This is the TargetSymbolType and is the key to the special handling of these
menus and items. Note that the TargetSymbolType refers to the type of the
symbol alert, not the base symbol type.
74
Chapter 2

and UNIX Systems
Table 2-9
Symbol Alert Pop-up Item Parameters
Parameter
actionId
Description
A popupItem for a symbol alert must be an action (f.action). For symbol alert
actions (both default action and menu item actions) the registration is limited to an
action name. Symbol alert actions do not need or use a command, a selection rule,
or minimums and maximums for selected items since the selection list is ignored.
Example:
Application "FireFighter" {
PopupItem <100> "Ack Fire Alert"
Context (AllContexts)
TargetSymbolType SymbolAlert:MajorAlert
f.action "Extinguish";
}
Action "Extinguish"{
}
Defining Tool Bar Buttons

The tool bar between the menu bar and the viewing area provides a
location for icon buttons representing frequent actions. Buttons may be
defined using the ARF or the OVw API. Bitmaps for tool bar icons on
UNIX systems are usually stored in $OV_BITMAPS/$LANG/toolbar and
must be .pm format 24 pixels in size. For applications on Windows NT
operating system, bitmaps are stored in \OpenView\bitmaps\$LANG and
must be .bmp format 16 pixels in size. These buttons are placed on a
submap according to the submaps context.
NOTE
Because end users can disable the display of the tool bar, application
developers must make their tool bar functionality accessible from the
pull-down menus as well.
A tool bar button is defined using a ToolbarButton statement, which

has the following components:
ToolbarButton <Precedence> "localizable Label"
Context
"Context_Expression"
Function;
Chapter 2
75

and UNIX Systems
The label may be a text string or an image.
For applications running on UNIX systems, if a tool bar image is active
only when an object is selected, you need to provide a pair of images: one
for the active state and one for the inactive state. On the Windows NT
operating system only one image is required; graying is done
automatically on disabled state.
In the following example for a tool bar on a UNIX systems application,
mailbox.24.pm is the image that is displayed when the icon is active on
a tool bar and nmailbox.24.pm is the image that is displayed when the
icon is grayed out.
Application "Mail Manager"
{
...
/*
** TOOL BAR BLOCK
*/
ToolbarButton
<100>
@"toolbar/mailbox.24.pm:toolbar/nmailbox.24.pm"
Context "AllContexts"
...
}
If you are registering a tool bar image for an application on the Windows
NT operating system, you can include tool tips text by using the syntax:
@ "toolbar\icon,tool tips text" as shown in the following
example:
/*
** TOOL BAR BLOCK
*/
ToolbarButton <100> @"toolbar/mailbox.bmp,Forward Mail"
Context "AllContexts"
Here the tool tip text is Forward Mail. It appears over the mailbox
bitmap when the cursor is left over it for more than a few milliseconds.
76
Chapter 2

and UNIX Systems
Table 2-10
Tool Bar Item Registration Components
Menu Item
Components
Purpose
Precedence
Value
Buttons are ordered from left to right according to the precedence value and, within
items of equal precedence, according to application name order. 100 is the highest
precedence, 0 is the lowest.
Label
This string is required for all buttons. A text label string specifies the words on the
button (ignored for separators). A label starting with "@" specifies the image file to be
displayed on the button. This string can be localized. For example, if your application
will be run in German language mode, labels would be specified as German text.
Refer to Application Registration File Support for Internationalization and
Localization on page 46 for more information on localization and
internationalization. On the Windows NT operating system applications, you can
include a tool tip for the button by appending a comma and text for the tool tip to the
path name for the bitmap.
Context
Expression
The context expression is a placement rule defining which submap contexts should
include the tool bar button. This required field is specified with the keyword
Context followed by a context expression. The context expression is explained in
the pull-down menu item registration components. Refer to Targeting Menu Items
and Toolbar Buttons to Submap Context on page 65 for a general discussion of
setting and using submap context.
Chapter 2
77

and UNIX Systems
Table 2-10
Tool Bar Item Registration Components
Menu Item
Components
function
Purpose
Describes the behavior of each button selection:
f.separator
Indicates that this should be a tool bar separator.
f.action
Associates an application invocation, or action, with the tool bar

button item. When the user selects the button, the application is
invoked appropriately. The application is notified of the selected
action. Associating Actions with Menu Items on page 64
explains how to associate an action with a button bar item and
Defining Actions on page 78 explains how to define an action
block.

menu item should be specified, such as the number of selections
or a selection rule, then you should declare an action with this
information and list the desired shell command in the menu item
arguments.
Defining Actions
The Action block is used to define actions that an application can
perform. Actions can then be associated with menu items via the
registration file, to symbol alerts via the OVw API, or to executable
symbols via the user interface. An action block declaration has the
following form (Table 2-11 explains each action block entry):
Action "actionId"
{
DisplayString "localizable string"
MinSelected n;
MaxSelected n;
SelectionRule (rule);
NameField "field", "field";
CallbackArgs "arg"
Command "-process_flags command $environment_variables";
}
Through the OVw API, an application can be notified that an action has
been requested by registering a callback for the action. This is
78
Chapter 2

and UNIX Systems
accomplished using the OVwAddActionCallback() registration
mechanism.
By default, all functions specified for a pull-down or pop-up menu item in
a particular context are executed when that menu item is selected in
that context. If an action specified for a menu item in a particular context
has Exclusive defined, only that action will be executed when the menu
item is selected in that context. Obviously, it is an error to define more
than one Exclusive action for the same menu item in the same context. It
is also an error, even if only one Exclusive action is defined for each
context, if a submap has more than one context with which an exclusive
action is associated. Although this is a registration error, because of its
dependence on the configuration of particular submaps, it can only be
detected at runtime.
For symbol alert actions, the registration is limited to an action name.
Symbol alert actions do not need or use a command, a selection rule, or
minimums and maximums for selected items since the selection list is
ignored.
Table 2-11
Action Block Definitions
Action Block
Entries
Purpose
DisplayString
This is a localizable string that is used to display the action name if the
application is running in a localized environment. For example, if your
application will be run in German language mode, the string would be specified
as German text. Refer to Application Registration File Support for
Internationalization and Localization on page 46 for more information on
localization and internationalization.
MaxSelected
Specifies the maximum number of objects that can be selected on the map for
the action to be enabled. If not specified, any number of objects may be selected
for the action. If set to 0, no objects may be selected.
MinSelected
Specifies the minimum number of objects that must be selected on the map for
the action to be enabled. If MinSelected is set to some value, then the
selection list must contain at least that number of objects. If MinSelected is
not set, then any number of objects can be selected. (If MinSelected is not set
and a SelectionRule is set, the selection list must contain at least one object.
If MinSelected is set to 0 and a SelectionRule is set, the selection list can
contain 0 or more objects.)
Chapter 2
79

and UNIX Systems
Table 2-11
Action Block Definitions
Action Block
Entries
SelectionRule
Purpose
Provides a mechanism to guarantee that the application is invoked only if the
selected objects meet predefined criteria.
The selection rule is a logical expression involving capability fields. The logical
expression can use logical AND (&&), logical OR (||), or logical NOT (!)
operators.
Command
Specifies the command line used to invoke the application on a per-action basis.
Commands specified in an Action block override commands specified globally
in the Application block. If no command is specified globally, a command must
be specified for each action defined.
Process Flags
You may define specific process management instructions on a per-action basis.

The Initial, Shared, and Restart flags may be used on a per-action basis
and override any global process flags.
NameField
The NameField entry provides the same object name field validation as
described in the Application section, but on a per-action basis.
CallbackArgs
This is a string that is broken into an argument vector and passed to the
applications action callback in the argc and argv parameters from the
registration file to specific application action callbacks. The CallbackArgs
are not available to applications that do not use the OVw API.
The following example demonstrates an action block specification:
..
MenuBar "Mail Manager" _a {
"Receive Mail" _R Context (WantMailMenus)
f.menu "GetMail";
}
Menu "GetMail"
{
"Open Mail" _O f.action MailQueueAction;
}
Action MailQueueAction {
SelectionRule isNode;
MinSelected 1;
MaxSelected 1;
80
Chapter 2

and UNIX Systems
Command "mgropen $OVSelection1";
}
..
}
In this example, the user can select the Open Mail menu item from the
menu cascades to request that the application be invoked. NNM executes
the application only if there is a single object selected on the map, and
that object has the isNode capabilities. If these qualifications are met,
the application is invoked with the name of the selected item.
Invoking Remote Applications (HP-UX and Solaris)
When an application is launched on a host other than the host running
the GUI, NNM uses a remote launcher. The grammar for the Command
statement for invocation of a remote application is:
Command ::= "Command" ProcessFlags String RemoteSpec ";"
| "Command" String RemoteSpec ";"RemoteSpec ::= "On"
HostSpec
RemoteSpecs ::= "On" HostSpec
| "On" HostSpec "StartedBy" LaunchSpec ";"
| Empty
HostSpec ::= StringOrIdentifier
LaunchSpec ::= String
ProcessFlags ::=ProcFlag | ProcessFlags ProcFlag
ProcFlag ::= "-Initial" | "-Shared" | "-Restart"
The HostSpec contains either an explicit hostname such as "unicorn", or

an environment variable such as "$OVServer" or "$OVwSelection1"
which will be expanded when the command is invoked.
The Launcher specification is the string specifying the command used to
launch the application command on the remote host. It must contain two
printf-style %s parameters to work correctly. %1$s refers to the host on
which the command shall be launched, %2$s refers to the application
command string that must be passed to the launcher.
The On and StartedBy keywords are extensions to the Command
statement syntax. They specify to the host where the command should
run and the application launcher to use to start the remote command.
On defines the system on which the application will run. It may be either
an explicit hostname or an environment variable such as $OVServer. If
the value of the On argument matches the system on which the OVW
GUI is running, NNM ignores the launch command specified with
StartedBy.
Chapter 2
81

and UNIX Systems
StartedBy specifies an alternative launcher. If StartedBy is not
included, the default NNM launcher is used for distributed applications.
The default launcher is:
ovexec -ovwlaunch -nodelist %1$s -noTerm -cmd %2$s
Commands must support a session ID argument and must use

OVwSessionInit() in order to be properly supported by remote
command registration. The application command must accept on its
command line arguments the session ID of the ovw session that started
it.
Example For example, you might have an application that must always
be run on the management server. The application command can be
registered as follows:
Application "Server App"
{
....
Command "/usr/bin/xserverapp -s $OVwSessionID -display
$DISPLAY"
on "$OVServer";
Action "Server Action"
{
...
}
...
}
This starts the command on the server system using the default remote
application launcher when the application action is requested.
Note that, as in the previous example, if the application is an X-based
program, your registration should also specify the current X display on
the command line.
If you wanted to start the application via some other mechanism, such as
remsh (rsh on Solaris):
Application "Server App"
{
...
Command "/usr/bin/xserverapp -s $OVwSessionID -display
$DISPLAY"
On "$OVServer" StartedBy "remsh %1$s %2$s";
Action "Server Action"
{
82
Chapter 2

and UNIX Systems
...
}
...
}
Drop Action Registration for HP-UX and Solaris

Applications
NOTE
Drop action registration is used along with the application programming

interfaces to customize drag and drop capabilities for applications. NNM
administrators and operators should have no need to create or modify
drop action registration.
Applications register to control a drop site through a combination of

registration file data and API manipulation. When an end user drops a
symbol onto an application-controlled dropsite, the applications drop
callback (if there is one) is invoked. This callback performs the
customized drop action that is defined in the application registration file
described here. Refer to the HP OpenView Windows Developers Guide
Applications on page 316 for a description of the APIs you need to use
to complete customization of drag and drop for your application.
The DropAction must be defined in an application registration file in a
DropAction block. This block has the following format:
DropAction "Action Name"
{
Operations [OpMove | OpCopy]+;
SelectionRule (rule_expression);
HelpString "localizable help text";
}
Chapter 2
83

and UNIX Systems
The following table explains the DropAction fields:
Table 2-12
DropAction Registration
DropAction Components
Purpose
Operations
The Operations field identifies (in order of preference) the drop

operations that the application will support for this DropAction.
The two possible operations are OpMove and OpCopy. A
DropAction may support one or both, but this field is required
and at least one operation must be supported.
SelectionRule
The SelectionRule field allows the application to

automatically limit what types of dragged symbols may be
dropped on sites that have this DropAction. This field is
optional. If it is not present, any type of symbol may be dropped
and will be handled by the drop action. If it is specified, NNM will
verify the capabilities of dragged symbols before allowing them to
be dropped.
HelpString
HelpString provides access to help text for the drop.This string

is displayed to the end user when a symbol is held over a drop site
and the F1 button is pressed. This field is required. This help text is
associated only with the drag and drop operation and is not linked
to the online help.
This help text can be localized. For example, if your application
will be run in German language mode, the string would be
specified as German text. Refer to Application Registration File
Support for Internationalization and Localization on page 46 for
more information on localization and internationalization.
Defining Dialog Box Fields

End users can use NNM menus to perform a variety of map operations
that might affect your application. These map operations can result in
user interaction through an NNM dialog box. If your application
supports any of the four basic map operations: Add, Describe
(Properties for Windows NT operating system), Connect, or
Configuration), you can let NNM construct dialog boxes for you. This
section explains how to use this automatic dialog box generation.
A block in an ARF defines the characteristics of dialog boxes displayed
when the user performs one of the four basic map object operations.
84
Chapter 2

and UNIX Systems
You can think of enrollment as a simple but limited dialog box building
tool. You can define the basic characteristics of dialog boxes and leave the
details of dialog box construction to Network Node Manager. It is not,
however, a dialog box builder for general use. These dialog boxes are
used only when the end user selects the Add, Describe (Properties, for
the Windows NT operating system), Connect, or Configuration
operations. Further, only limited control over dialog box layout is
provided.
NOTE
If you have particular dialog box needs that are not met by NNMs
enrollment capability, you will need to implement your own dialog box
directly using Motif or Win32.
Enroll Block
Dialog boxes are defined using enroll blocks. A separate enroll block is
used for each dialog box type that you define. The format for enroll block
declarations is:
Enroll <Dialog_Type> {
if <Rule> {
InitialVerify <On/Off> ;
Scale <n>
Help <Browser/Quick> "HelpVolume:Keyword" ;
Field <Field specifications>{
NoDisplay <On/Off> ;
ImmediateVerify <On/Off> ;
Label "Label :";
EditPolicy <Edit/NoEdit/EditOnCreation> ;
Geometry <X,Y,W,H> ;
SelectionListPolicy <None/Single/Multiple> ;
IntegerDisplayPolicy <Integer/Unsigned/Hex/Octal/IPAddr> ;
}
...
}
}
Each enroll block is composed of three sections: the rule that specifies
what objects are accessible via the dialog box, any global rule options,
and the enrollment section. Rules are defined within enroll blocks, and
specifications are defined within rules.
Chapter 2
85

and UNIX Systems
The general steps for specifying a map operation dialog are:
1. Specify the dialog type. If you are enrolling for an Add dialog, consider
whether you need to also enroll to a Describe (Properties on the
Windows NT operating system) dialog.
2. Define the logical expression that expresses the rule to be used to
select the fields to be displayed.
3. Define the global options that govern all of the fields in the dialog box.
4. Define specifications for each field within a rule.
The following sections explain the parameters in each of these sections of
the enroll block.
Dialog Box Type
An enroll block defines any of four map operation dialog boxes:
Add
Presented when an NNM user adds an object to the

map.
Describe
Presented when an NNM user invokes the Describe

Object (Properties, for the Windows NT operating
system) action on an object.
Connect
Presented when an NNM user attempts to connect two

objects on the map.
Configuration Presented when an NNM user requests to change

per-map configuration parameters for an application.
This dialog box is application-specific and is not related
to an object.
Rules
Rules are logical expressions that use object capabilities to control when
fields are displayed.
In its simplest form, the rule is simply an object capability such as isIP
or isInterface. (Capability fields havent been described yet; they are
introduced in the field registration files section at the end of this
chapter.) You can also use logical AND (&&), logical OR (||), or logical
NOT (!) operators to construct expressions based on one or more object
capabilities.
For example, consider a Describe (Properties, for the Windows NT
86
Chapter 2

and UNIX Systems
operating system) dialog box. You may want to display one set of fields if
the user selects an object with network interface capabilities, while
another set of fields should be displayed if the user selects an object with
either node or router capabilities.
The following ARF segment demonstrates:
Application "My app" {
...
Enroll Describe {
if isNetworkInterface {
Field "IP Address" {
...
}
}
if isNode || isRouter {
Field "IP Hostname" {
...
}
}
}
...
}
In the previous example, the IP Address field will be displayed if the

selected symbol has the isNetworkInterface capability, while the IP
Hostname field will be displayed if the selected symbol has isNode or
isRouter capabilities. Field specifications are the subject of the next
section.
Note that rules are based on object capabilities. Rules in the Add and
Describe (Properties, for the Windows NT operating system) dialog
box types operate on a single object. You might note, however, that the
Connect dialog box type involves two end points, or objects, to be
connected. In this case, two logical expressions are required, separated
by a comma. For example,
Enroll Connect {
if (isNode || isRouter), isRouter {
<Field specifications>
}
}
In this case, the first end-point must be an object that has either isNode
or isRouter capabilities, while the other end-point must have the
isRouter capability. Selection order is not important.
Chapter 2
87

and UNIX Systems
Also note that the Configuration dialog box type is not related to an
object, and therefore does not require rules.
Global Rule Options
Three global rule options are defined:
InitialVerify
Indicates that the application should be immediately

contacted when the dialog box is displayed to provide
default field values. By default this option is disabled,
or Off.
Scale
Provides a scale for parameters to Geometry in the

field enrollment section. If no scale is provided, the
scale is assumed to be 1.
Help
Provides a link from the help button on the dialog box

to a file containing help text or to a help index. The
grammar for this option is:
Help Browser|Index "help_file:keyword"
For example, an NNM help topic entry in an enroll
block might be Help Browser
"nnm:IDescIpNetwrkAttsDbx". "nnm" is the name of
the CDE or WinHelp file containing the help topic and
IDescIpNetwrkAttsDbx is the ID name of the topic as
it is defined in the CDE Help or WinHelp file. Refer to
the ovw and ipmap registration files for more examples.
See also See Help Directory on page 56.
Fields and Field Options

Field definitions within an enroll block define which object database
fields are presented to the user. Field options specify their display
format.
88
Chapter 2

and UNIX Systems
Field is the name of a field in the object database. The following options
may be set per field enrolled. If an option setting is absent, it is by
default set to Off.
Table 2-13
Fields and Field Options
Option
Description
Label
A string used as a field label in the dialog box. By default, the label is
the same as the field name. This is a localizable string. For example, if
your application will be run in German language mode, the string would
be specified as German text. Refer to Application Registration File
Support for Internationalization and Localization on page 46 for more
information on localization and internationalization.
EditPolicy
An editing policy for the field. By default, fields are always writable.
You may specify that the field is read-only (NoEdit) or that the field may
only be edited upon use in a new map (EditOnCreation).
IntegerDisplayPolicy
A display policy for integer fields. By default, integers are displayed as

32-bit signed decimal values. They may also be displayed in Unsigned,
Hex, Octal, or in conventional IP Address dot notation format (IPAddr).
NoDisplay
If on, allows the application to be sent the field value but it is not
displayed in the dialog box.
ImmediateVerify
If on, initiates the process of sending all enrolled fields and their values
to the application immediately after a value has been entered in this
field.
Geometry
Specifies the geometry of the field with four integers. They are, in order
specified: X Position, Y Position, Width, Height. If setting is specified,
the grammar requires all parameters, but only width is applied.
FieldListSelectionPolicy
Specifies the behavior of the list of fields displayed in the attributes box.
Valid parameters are: None (the default) no specific items may be
selected. Single--only one item in the list can be selected.
Multiple-more than one item in the list can be selected.
FieldDefaultValue
Lets you specify a default value for the field. This default value is
supported only for application configuration fields.
The following example demonstrates how to define fields
...
Chapter 2
89

and UNIX Systems
Enroll Describe {
if isNode {
Help Browser "mailmgr:10054";
Field "IP Address" {
Label "IP Address:";
IntegerDisplayPolicy IPAddr;
EditPolicy NoEdit;
}
}
...
}
...
}
In the previous example, the dialog box contains a single field that
displays the IP address. The IP Address field in the object database is
stored internally as a 32-bit integer, but is displayed using the IP
address format. The field cannot be edited by the user.
In general, most enroll blocks contain multiple field definitions. You can
examine the application registration files provided with NNM for more
examples. See the OVwRegIntro(5) reference page for a complete
description of entries within enroll blocks.
90
Chapter 2

Application Registration for the Web

Web Launcher
The format of the Launcher ARF follows closely the syntax and
constructs of the ARF for UNIX systems and Windows NT operating
system applications, but fewer blocks are supported, some blocks are
varied, and several blocks are added.
Figure 2-2
Application Integration into Web Launcher
Action NNMalarms {
URL "/OvDocs/nnm/NNMcat.html";
Access NTAdmin NetworkAdmin
WebWindow "OvWWWAlarm" {
Type full;
Toolbar off;
Status off
}
}
Action
Block
List
Block
List FaultsAndAlarms
{
NNM Alarms
Icon launcher/msgbr16.gif
ActiveHelp { FaultsAndAlarms }
f.action FaultsAndAlarms;
}
Tab
Block
Tab <70> Information and Reports Icon launcher/info.20.gif
Active Help { Information and Reports}
Chapter 2
91

Example
/*Launcher registration file for the NNM Alarm Browser
Application "NNM Alarm Browser"
{
DisplayString "NNM Alarm Browser";
Version "NNM .06.00";
Copyright {
"Copyright (c) 1990-1998 Hewlett-Packard
Company",
}
Description {
"The NNM Alarm Browser."
}
Tab <70> "Information and Reports" Icon "launcher"
ActiveHelp { "Information and Reports" }
{
<70> "Faults and Alarms"
Icon "launcher/folder.16.gif"
ActiveHelp { "Faults and Alarms" }
f.list "FaultsAndAlarms";
}
List "FaultsAndAlarms"
{
"NNM Alarms"
Icon "launcher/msgbr.16.gif"
ActiveHelp { "NNM Alarms Browser" }
f.action "NNMalarms";
}
Action NNMalarms {
URL "/OvDocs/nnm/NNMcat.html";
Access NTAdmin NetworkAdmin
WebWindow "OvWWWAlarm" {
Type full;
Toolbar off;
Status off;
}
}}
Application Block
The basic statements of the application block are supported. The values
for the Application Name, Version, Copyright, and Description are
not displayed by the Launcher, but they provide useful comment
92
Chapter 2

information in the registration file. For a description of the syntax refer
to Application Block on page 48. The syntax for the application block
is:
Application "Application Name" {
DisplayString "Application Name";
Version "Version_ID";
Description {
"Description text."
}
Copyright {
"(c)Copyright Date Company Name."
}
Tab Block
The Tab block corresponds to the MenuBar block in the application
registration files.
Instead of an optional mnemonic as in the MenuBar, the Tab block allows
an icon to display on the tab.
The Tab block also contains optional active help text. This active help is
presented in a help text box when the user selects the tab.
The syntax for a tab block is:
Tab <precedence>"Title Icon "image_name" ActiveHelp
{"help_text"}
Table 2-14
Tab Block Syntax
Tab Block Components
Purpose
precedence
The precedence is an integer value which weights the importance of a

tabbed property page. Tabbed property pages are listed in the property
sheet in order of precedence. When two Tab blocks have the same
precedence, the Launcher will place any of its registered property pages
first followed by the remaining property pages in random order. (0 is
the lowest precedence and 100 is the highest.
tab_id
The tab_id distinguishes the Tab declaration. tab_id is global in

scope.
Chapter 2
93

Table 2-14
Tab Block Syntax
Tab Block Components
Purpose
image_name
This is a locale-dependent icon that is displayed for the tab. The form for
icons is 16x16 GIF files. The file name is relative to
/opt/OV/www/htdocs/$LANG/images/ on UNIX systems or
\OpenView\www\htdocs\$LANG\images on the Windows NT
operating system. If one is not specified, a default is used. Optional.
help text
The help statement is optional. It specifies the text that is displayed when
the list item is active. You can provide multiple help statements within
the braces {}. Optional.
List Block
List blocks declare a set of contained list items that are displayed
together when the list is activated.
<list_item_precedence> "list_item_label" Icon
"icon_statement.gif"
ActiveHelp { "help_statement"}
f.list "list_function";
List Item statements can appear as part of either tab or list blocks. When
part of a tab block, list item statements declare items that appear in the
tabbed property page.
Table 2-15
List Item Syntax
List Item Components
Purpose
List_Item_Precedence
The precedence value is optional. It may range from 0 to 100 and

it defaults to 50. This is an integer value which weights the
importance of a list item. (0 is the lowest precedence and 100 is
the highest.) List items are listed within property pages according to
precedence. When list items have the same precedence, the Launcher
will place any of its registered list items followed by the remaining
list items in random order.
List_Item_Label
This is the label for the list item as it should appear in a list. It is a
required field.
Icon_Statement
The icon statement is optional. It specifies the icon to use to represent

the list item.
94
Chapter 2

Table 2-15
List Item Syntax
List Item Components
Purpose
Help_Statement
The help statement is optional. It specifies the text that is displayed

when the list item is active. You can provide multiple help statements
within the braces {}.
List_Function
A function determines the behavior of each list selection. Functions

begin with the two characters f. followed by a name.
f.action - the f.action function takes an ActionID which is
associated with some Action declaration elsewhere in the file. It ties
the action to the list item so that when the item is selected, the
application is, if necessary, invoked and notified of the selected
action.
f.list - this function provides for the declaration of a list that,
when activated, gets expanded in the property page. The list is
declared in a List Block (discussed below).
List Blocks
List Blocks declare a set of contained list items that are displayed
together when the list is activated
Action Block
An Action block is used to define an action that an application can
perform. Actions can then be hooked to list items via the f.action
List_Function specification. It lists the URL that should be used to
perform the action.
The generic form of an action block is:
Action <Action_ID> {
URL "url";
WebWindow "name"{
Type full | intermediate | limited;
Status on | off;
Scrollbars on | off;
Toolbar on | off;
Location on | off;
Resizable on | off;
Width pixels;
Height pixels;
}
Chapter 2
95

}
Table 2-16
Launcher Action Block Definitions
Action Block Component
Purpose
Action_ID
A name assigned to identify the action block.
URL
The URL to launch for the action. The URL may contain the special
variable $OVwWebServer. This variable will be substituted with
the name of the system from which the Launcher was loaded.
Access
A list of the user roles that have access to this action. If the Access
statement is not present, all users have access.
WebWindow
The WebWindow statement allows specification of attributes of the

browser window. The name parameter is optional and can be used to
reduce the number of browser windows on a users desktop. For
example, all help URLs can use a browser window named help
window so that when the user selects a list entry to invoke help and
there is already a help browser window available, it will be reused to
display the help URL requested. If the WebWindow statement is not
present, the URL will be loaded into an unnamed full Web browser
window. If an empty string is specified, a new window will be created
for every browsed instance of the URL.
Type
Type specifies the type of the window and determines which features
it supports. These are the values: full, intermediate, limited.
Status
Specifies whether the status line is displayed. Default is ON unless

the window type is limited, in which case the default is OFF.
Scrollbars
Specifies whether the scrollbars are enabled or disabled. Valid values

are on and off. Default is ON unless the window type is limited, in
which case the default is OFF.
Toolbar
Specifies whether a browser toolbar is visible. Valid values are ON

and OFF. Default is on unless the window type is limited, in which
case the default is off.
Location
Specifies whether the URL location is displayed. Default is ON

unless the window type is limited, in which case the default is OFF
Resizable
Specifies whether the window is resizable. Valid values are ON and

OFF. Default is ON.
96
Chapter 2

Table 2-16
Launcher Action Block Definitions
Action Block Component
Purpose
Width
Specifies the width in pixels of the window. If height is not also

specified, this value is ignored.
Height
Specifies the height in pixels of the window. If width is not also

specified, this value is ignored.
Application Registration for Network Presenter

The different capabilities of the three interfaces supported by Network
Node Manager require variations to the application registration file. The
following table highlights these variations.
Table 2-17
Interface-Specific Variations for Application Registration Files
ARF
Windows NT
operating
system and
UNIX systems
Network
Presenter
Documented
Description
Application Description on page 52
Copyright
Version
HelpDirectory
N/A
Command
N/A
MenuBar
Menu Bar Registration on page 59
Menu Item
Menu Item Registration on page 61
PopupMenu
Pop-up Menu Registration Example on

page 72
Popup Menu Item
Pop-up Menu Items on page 67
Chapter 2
97

Table 2-17
Interface-Specific Variations for Application Registration Files
ARF
Windows NT
operating
system and
UNIX systems
Network
Presenter
Documented
SymbolAlert Popup
N/A
Tool Bar Buttons
Defining Tool Bar Buttons on page 75
Action Block
Must be URLs
Action Blocks for Network Presenter on

page 98
DropAction Block
UNIX systems
Only
N/A
Remote Application
Invocation
UNIX systems
Only
N/A
Dialog Box Fields
N/A
Enroll Block on page 85
WebWindow
N/A
Action Blocks for Network Presenter on

page 98
Action Blocks for Network Presenter

The Action block for a Network Presenter ARF extends the definition for
an NNM ARF action block (described in Action Block on page 95) by
adding two declarations: URL and WebWindow.
URL
The URL declaration specifies the URL to be launched. Other
information can be encoded in the URL and substituted at run time.
Most of the variables are equivalent to environment variables in the
native product.
The following variables are supported:
$OVwSelections
A plus sign (+) separated list of the

current selection list.
$OVwNumSelections
The number of items in the current

selection list.
98
Chapter 2

$OVwSelection[n]
A single value from the selection list

where n=0-9.
$OVwMenuItem
The value of the menu item selected.
$OVwAppName
The name of the application that

registered the action.
$OVwActionID
The name of the action being

invoked.
WebWindow
The WebWindow declaration allows specification of attributes of
application window. If the WebWindow statement is not present, the
URL will be loaded into an unnamed full Web browser window. The
definition for WebWindow is described in Table 2-16.
Chapter 2
99

Creating Symbols
Creating Symbols
Symbols are graphical representations of objects in HP OpenView.
Symbols can either be icon symbols or connection symbols. Icon symbols
represent network or system management elements, while connection
symbols represent connections between elements.
Each symbol is identified by its symbol type. The symbol type is defined
by a symbol class/subclass pair. The symbol class defines the symbol
category, while the symbol subclass defines a particular element within
that class. Network Node Manager provides you with a rich set of
predefined symbol classes and subclasses.
Symbol type registration files are used to define symbol classes and
subclasses in HP OpenView. The predefined NNM symbol classes and
subclasses are themselves defined using various symbol type registration
files in \OpenView\symbols\$LANG on the Windows NT operating
system or $OV_SYMBOLS/$LANG/ on UNIX systems. You are encouraged
to use these predefined symbol classes and subclasses in your
applications.
You may find, however, that existing classes and subclasses are not
adequate for your needs. You can add new symbol subclasses to existing
symbol classes or you can define your own symbol classes. This portion of
the chapter shows how to define symbol classes and subclasses. Only icon
symbol classes and subclasses are described here, as they are the most
commonly used symbol variety. If you need to define connection symbols,
see the OVwRegIntro(5) reference page. (All references to the terms
symbol classes and symbol subclasses throughout the remainder of
this section refer to icon symbol classes and subclasses.)
Symbol Registration File Support For

Internationalization and Localization
HP OpenView symbol registration files support internationalization by
allowing the following components within the symbol registration file to
be localizable:
display string of the symbol class name.
display string of the symbol type name.
filebase string.
100
Chapter 2

Creating Symbols
All other symbol registration file components must be restricted to ASCII
characters and must be identical in each different language version of
the symbol registration file.
When creating symbol registration files, apply the following guidelines:
Specify ASCII strings for the SymbolClass and SymbolType
names.
Install your symbol registration files in
\OpenView\symbols\$LANG on the Windows NT operating system
or $OV_SYMBOLS/C on UNIX systems.
Do not modify the ASCII specifications for SymbolClass and
SymbolType.
Use DisplayString statements to specify localized strings for the
symbol class and type names.
Install your localized symbol registration files in
\OpenView\symbols\$LANG on the Windows NT operating system
or $OV_SYMBOLS/$LANG on UNIX systems, where $LANG is the
locale name of the native language of your application.
Create a localized version of the bitmaps or pixmap file if
necessary. Refer to Required Subclass Specifications on page
110 for more information.
Install your localized bitmaps file in \OpenView\bitmaps\$LANG
on the Windows NT operating system or $OV_BITMAPS/$LANG on
UNIX systems, where $LANG is the locale name of the native
language of your application.
For example, if an application is localized to German, and you need to
create a new symbol class and type, the applications symbol registration
file might look like this:
SymbolClass "New Symbol Class"
{
Scale 7;
Segment (-8, -8) to (8, -8) to 8, 8) to (-8,8);
DefaultStatusSource Sompound;
DefaultLayout RowColumn;
Variety Icon;
Chapter 2
101

Creating Symbols
Filebase "eigenesSymbolType";
Capabilities
{
isComputer = 1;
isNode = 1;
}
DisplayString "eigenes Symbol Class"; /*class name displayed
*/
/*to user */
}
SymbolType "New Symbol Class" : "New Symbol Type";
{
Filebase "eigenesSymbolType";
CursorSize 38;
Capabilities
{
isMainFrame = 1;
}
DisplayString "eigenes Symbol Type"; /*Symbol class name */
/*Displayed to user */
}
Here the DisplayString statement specifies the localized string of the

symbol class and type names. The strings that appear next to the word
SymbolClass and SymbolType are internally used strings that must
consist of ASCII characters and must be identical in all language
versions of this applications symbol registration files. Whenever HP
OpenView is started in German language mode, the DisplayString
specifications are displayed as the SymbolClass and SymbolType names.
If no DisplayString is specified in the symbol registration file, the
ASCII strings specified for SymbolClass and SymbolType names are
displayed.
Localization on page 46.
Applications on page 123.
HP OpenView Application Style Guide for design guidelines.
HP OpenView Windows Developers Guide, Chapter 10 , Developing
Internationalized and Localized Applications, for implementation
guidelines.
102
Chapter 2

Creating Symbols
the OVwRegIntro(5) reference page
Defining Icon Symbol Classes

An icon symbol class is represented graphically by its external shape.
Symbol classes are defined using files in \OpenView\symbols\$LANG on
the Windows NT operating system or $OV_SYMBOLS/$LANG/ on UNIX
systems. Each file in the symbols directory contains one or more symbol
class definitions, where each definition is composed of three elements:
the class name (a string)
the description of the external shape (a series of line segments or
arcs)
an optional integer scale factor
Complete examples of symbol class definitions are provided in the
following sections. Symbol class definitions based on line segments are
treated first, followed by class definitions based on arcs.
Defining Classes Using Line Segments
Line segments are often used to define most icon symbol classes in NNM.
The majority of icon symbol classes provided with NNM are defined
using line segments.
Shapes are defined using a series of points that lie within a conceptual
square. Points are specified using integer values which, by default, may
range from -1 to 1 on both the X and Y axes. The conceptual square has
center coordinates of (0,0).
The following example shows the NNM Computer symbol class and the
symbol class definition that produced it.
Chapter 2
103

Creating Symbols
Figure 2-3
Computer Symbol Class
(-1,1)
(1,1)
(0,0)
(-1,-1)
(1,-1)
SymbolClass "Computer" {
Segment (-1,-1) to (1,-1) to (1,1) to (-1,1) to (-1,-1);
}
By default, the scale is 1. In other words, the integer point values may
range from -1 to 1 on both the X and Y axes. A scale of 1 limits you,
though, to simple, uninteresting shapes.
You can create more complex shapes by increasing the scale and,
therefore, using more points. NNM will interpret your points relative to
your scale and will display your shape in a standard size. The following
example demonstrates how to use the scale entry.
104
Chapter 2

Creating Symbols
Figure 2-4
House Symbol Class
SymbolClass "House" {
Scale 5;
Segment (-4,0) to (-5,0) to (0,5) to (3,2) to (3,3) to (4,3)
to (4,1) to (5,0) to (4,0) to (4,-5) to (-4,-5);
}
Note that the example segment definition is not closed explicitly. NNM
completes the definition by drawing a line from the last point to the
starting point.
You have much freedom in defining symbol class shapes. There are,
however, some aspects of shape definition you should be aware of:
Chapter 2
105

Creating Symbols
Specifying points wholly within the square may not produce a symbol
class shape as large as desired. You can change the actual symbol
class icon size by specifying coordinate values that exceed your scale.
This has the effect of making your symbol class icon larger. Your point
values should not exceed 150% of scale, though, or symbols may
overlap when NNM places them on the map.
The point (0,0) should be contained within your shape definition. If it
is not, NNM cannot correctly connect symbol classes on the submap.
Defining Classes Using Arcs
As an alternative to using line segments, you may also define icon
symbol classes using arcs. Arcs allow you to easily define such class
shapes as circles, ellipses, and wedges that would be tedious to define
using line segments.
The definition of an arc is composed of three components
Table 2-18
Arc Definition Components
Keyword
Purpose
Size
This is the width and height of a conceptual rectangle in which the line will rotate. If
the width and height are equal, the arc will have a constant radius. Elliptical arcs may
be achieved using height and width values that are unequal.
Origin
Specifies an origin for rotation within the conceptual rectangle. The center of the
conceptual rectangle is assumed to have the coordinates (0,0).
Rotation
This specifies the starting angle and number of degrees of rotation. A starting angle of
0 degrees is equated to a three-oclock position, and rotation occurs in a clockwise
direction.
The following example demonstrates how to define a symbol class with a
circular shape.
SymbolClass "Network" {
Scale 2;
Arc Origin(0,0) Size(2,2) Rotation 0, 360;
}
If you need further information about defining symbol classes using arcs,
consult the OVwRegIntro(5) reference page.
106
Chapter 2

Creating Symbols
NOTE
Arcs and Segments cannot be combined in a single shape definition.
Optional Class Specifications for Symbol Classes

There are a few optional class specifications you can use when you define
symbol classes.
Default Layout
When end users double-click on a symbol on a map, the symbol may
explode into a submap. The DefaultLayout entry specifies the
default layout algorithm for the child submap of an object represented
by a symbol with this symbol class. (This default can be overridden by
an end user or application when the submap is created.) The choices
are: Ring, Bus, Star, PointToPoint, and RowColumn (the default).
Default Status Source
A symbol can get status from a variety of sources:
underlying object (object status)
parent object of a child submap (compound status)
symbol itself (symbol status)
The DefaultStatusSource entry sets the default status source for
symbols of this class. If not set, symbol classes have object status.You
can assign default status source to symbol classes by defining a
DefaultStatusSource structure in the class definition. You need to
supply one of three status source values: Object, Symbol, or
Compound. The following example shows how to set the default layout
and the default status source for a symbol class.
SymbolClass "Computer" {
Segment (-1,-1) to (1,-1) to (1,1) to (-1,1);
DefaultLayout RowColumn;
DefaultStatusSource Compound;
}
Default Capabilities
An object can be added to the map by selecting a symbol type on the
symbol palette and dragging it to a submap. NNM automatically
creates an object that is associated with the symbol. By default, the
Chapter 2
107

Creating Symbols
new object has no capabilities. Capabilities are described in Field
Registration File on page 118.
You can assign default capabilities to objects by defining a
Capabilities statement in your class definition. Whenever a symbol
is added to a map, NNM will use the symbols default capabilities to
initialize the capabilities of the associated object being added. For
example,
SymbolClass "Computer"
{
Segment (-1,-1) to (1,-1) to (1,1) to (-1, 1) to (-1,-1);
Capabilities {
isNode = 1;
}
}
Variety
There are actually two forms of symbol classes: icons and connections.
To this point, only icons have been shown. It is possible, though, to
create symbol classes that connect other symbols. These are called
connection classes. You can specify that a class is a connection by
using the Variety definition and specifying that the class has the
value Connection. (The default is Icon). The following example
demonstrates:
SymbolClass "Connection" {
Variety Connection;
}
DisplayString
The DisplayString is a localizable string that is used when NNM
must display the name of a symbol class from within its user
interface. For example, if your application will be run in German
language mode, the string would be specified as German text. If no
DisplayString is specified, the ASCII SymbolClass string is
displayed.
For further information about connection symbol classes, see the
OVwRegIntro (5) reference page.
108
Chapter 2

Creating Symbols
Defining Symbol Subclasses

A symbol subclass definition allows you to define a new symbol subclass
within a class of symbols. Subclasses are represented using bitmaps that
are superimposed on symbol class shapes.
Symbol subclasses are defined using a symbol type block. The symbol
type block specifies the name of the subclass and the class to which it
belongs. Symbol types are stored in\OpenView\symbols\$LANG on the
Windows NT operating system or $OV_SYMBOLS/$LANG on UNIX
systems. The symbol type can be considered the combination of the
symbol class and the symbol subclass. It has the following syntax:
SymbolType "class name": "subclass name" {
Filebase "symbol_class_icon_base_name";
CursorSize n;
Capabilities {
capability=n;
}
}
The class name is the name of an existing symbol class. The subclass
name is a unique name for the new subclass. The subclass specifications
define the bitmaps that are used for the subclass as well as other
characteristics of symbol subclass behavior.
The symbols provided by NNM use the RGB values listed in Table 2-19.
Using other colors may overload the color map and can create problems
for the user.
Table 2-19
Chapter 2
Icon Symbol RGV Values

Color
Red
Green
Blue
Grays
200
200
200
175
175
175
150
150
150
125
125
125
100
100
100
75
75
75
50
50
50
109

Creating Symbols
Table 2-19
Icon Symbol RGV Values

Color
Red
Green
Blue
White
255
255
255
Black
Red
255
Green
255
Blue
255
Yellow
255
255
Magenta
255
255
Cyan
255
255
Required Subclass Specifications

Subclass Specifications for UNIX Systems Two subclass
specifications must be present in every icon symbol subclass definition:
Cursor Size
Whenever the end user selects a symbol type from the symbol palette
and moves the symbol type to a map, the cursor shape changes from a
pointer to a bitmap. The CursorSize entry defines the size of the X
bitmap to be used as the cursor. CursorSize is also used during the
drag and drop operation. We recommend a cursor size of 38x38 pixels.
The bitmap definition for a cursor is composed of two parts:
filebase.size.p (the bitmap) and filebase.size.m (the bitmap
mask). You need to provide a pair of bitmap/bitmap mask files for the
cursor size you support. You must provide at least one bitmap pair.
Filebase
This entry defines the basename for a symbol subclass icon. It is
provided in a file with the format filebase.size.extension.
Bitmaps are stored in $OV_BITMAPS/$LANG on UNIX systems. The
symbol subclass icon can be an X bitmap or an X pixmap. Pixmap is a
supported graphic format for UNIX systems and the Windows NT
operating system user interface. All predefined class bitmaps (for
example, computer, software) are shipped in pixmap format. X
110
Chapter 2

Creating Symbols
bitmap format is supported only for backward compatibility. If you
develop a new symbol, you should use a pixmap format.
The filebase name is a localizable string. For additional information
on internationalization and localization refer to Application
Registration File Support for Internationalization and Localization
on page 46 and Chapter 10 , Developing Internationalized and
Localized Applications..
A bitmap definition is composed of two parts: filebase.size.p (the
bitmap) and filebase.size.m (the bitmap mask). You should
provide a pair of bitmap/bitmap mask files for each bitmap size you
support. (You must provide at least one bitmap pair.) A pixmap
definition consists of simply filebase.size.pm because the mask is
defined in the pixmap.
HP OpenView uses different icon sizes whenever the dimensions of
an Network Node Manager window changes. Network Node Manager
attempts to scale the window contents appropriately, which may
mean choosing a different symbol icon to optimally fit the window
scale. If the appropriate icon file does not exist, Network Node
Manager will choose the closest possible match.
We recommend that you provide symbol subclass icons in the
following sizes (in pixels): 20x20, 26x26, 32x32, 38x38, 44x44, and
50x50. All icons for a subclass must be of the same format. That is, all
X Pixmap or all X Bitmap. If using pixmap, also supply bitmaps for
the cursor size. We recommend that you save the files in GIF format.
The following example demonstrates both the Filebase and
CursorSize entries:
SymbolType "Software": "Application" {
Filebase "app2";
CursorSize 38;
}
In this example, the cursor will be 38 by 38 pixels and will be based

on the bitmap formed by the files app2.38.p and app2.38.m.
For connection symbols, the Filebase specification can be used to
provide a bitmap called an overlay graphic that identifies a
particular connection symbol class. For example, the connection
symbol for a T1Carrier is described in the following symbol
registration file:
SymbolType "TCarrier" : "T1Carrier"
Chapter 2
111

Creating Symbols
{
LineStyle Solid;
Filebase "tcarrier";
Thickness 5;
}
This registration results in the following connection symbol:
Overlay graphics must be X pixmap format. The sizes for the overlay
graphics on a UNIX system must be 11, 12, 17, 21, 25 or 29 pixels.
Refer to the HP OpenView Application Style Guide for usage
guidelines for connection symbol overlay graphics.
Subclass Specifications for the Windows NT Operating System
Applications on the Windows NT operating system require a filebase
specification for the symbol subclass definition to define the base name
for a symbol subclass icon. No cursor size specification is required.
Bitmaps are stored in \OpenView\bitmaps\$LANG on the Windows NT
operating system.
For example, the symbol type definition in $OV_SYMBOLS\C\Computer
might look like this:
SymbolType "Computer" : "WindowsNT"
{
Filebase "winnt";
Capabilities {
isPC = 1;
}
}
112
Chapter 2

Creating Symbols
The corresponding file named by the Filebase specification in this
example would be \OpenView\bitmaps\C\winnt.pm.
As on HP-UX and Solaris connection symbols, the Filebase specification
can be used to provide a bitmap called an overlay graphic that
identifies a particular connection symbol class. Refer to the description
of overlay graphics in the previous section for a description.
Subclass Specifications for Web Applications Web-based
applications require a filebase specification for the symbol subclass
definition to define the base name for a symbol subclass icon. For
symbols displayed in the Network Presenter, inner symbols support only
GIF format graphics. If symbols have any other format the inner shape
will not be displayed. No cursor size specification is required. The gif
files are located in /opt/OV/www/htdocs/bitmaps/$LANG on UNIX
systems and in \OpenView\www\htdocs\bitmaps\$LANG on the
Windows NT operating system.
Optional Subclass Specifications
Additionally, there are optional subclass specifications you can use in
your symbol type definitions. The following specifications change the
basic behavior of the symbol type:
Default Layout
This specification was covered with symbol classes. A DefaultLayout
entry in a symbol subclass definition overrides any default layouts
specified in the class definition.
Default Status Source
This specification was also covered with symbol classes. A default
status source specification in the subclass definition overrides any
default status source statements in the symbol class definition.
Default Capabilities
This specification was covered with symbol classes. A capability
defined in a symbol class is inherited in the symbol subclass. If you
specify a subclass capability specification with the same capability
field as in the class definition, the subclass definition overrides the
class definition.
DisplayString
The DisplayString is a localizable string that is used when NNM
Chapter 2
113

Creating Symbols
must display the name of a symbol type from within its user
interface. For example, if your application will be run in German
language mode, the string would be specified as German text. If no
DisplayString is specified, the ASCII SymbolClass and SymbolType
strings are displayed.
Additional specifications for connection symbols include the following
items:
Line Style
This statement specifies whether the line will be a Solid or Dash line.
If this statement is used it will override any value given in the
connection symbol class specification.
Line Dash Pattern
This statement is used only if the line style is Dash. It is followed by a
comma separated list of Dash Lengths which specify the length of a
single dash or gap in the drawn line. The even elements in the list are
the dash length and the odd elements are the gap lengths. If this
statement is used it will override any value given in the connection
symbol class specification. For example
SymbolType "Connection" : "Dashed"
{
LineStyle Dash;
LineDashPattern 10, 5, 10, 5, 10, 5;
}
Thickness
This statement is used to specify the thickness of the connection in
pixels. The thickness of the connection cannot exceed the width of the
connected symbols.
For further symbol subclass examples, consult the symbol registration
files provided with HP OpenView (in the\OpenView\symbols\$LANG on
the Windows NT operating system or $OV_SYMBOLS/$LANG/ on UNIX
systems).
Symbol Alert Type

NOTE
Symbol alert registration is used along with the application

programming interfaces to provide symbol alerts for symbols.
114
Chapter 2

Creating Symbols
Registration files for some symbol alert types are provided with the
product. Administrators should have no need to create or modify symbol
alert registrations. Application developers should refer to Chapter 7 ,
Creating and Using Symbols, for an overview of symbol alert usages
and details about implementation.
A symbol alert is a temporary extension of an icon or connection symbol.

Symbol alert registration associates the name of a type of symbol alert
with an X pixmap that is used to display that symbol alert. Symbol alert
registration also specifies a rectangular area within that pixmap where
text can be displayed.
The format for a symbol alert declaration is:
SymbolAlert SymbolAlertTypeName {
PixmapBaseName baseName;
PixmapSize n;
TextRegion {
RegionCenter (x,y);
RegionHeight n;
RegionWidth n;
}
}
For example:
SymbolAlert FireDanger {
PixmapBaseName critical_alert;
PixmapSize 85;
TextRegion {
RegionCenter (43,45);
RegionHeight 46;
RegionWidth 75;
}
}
Symbol alert registration includes four components of symbol alert data,

described in Table 2-20.
Table 2-20
Symbol Alert Registration Components
Component
Description
SymbolAlertTypeName
Uniquely identifies the symbol alert type.
Chapter 2
115

Creating Symbols
Table 2-20
Component
Description
PixmapBaseName
Specifies the filebase name of the pixmap file used to display the
symbol alert type. Only the X pixmap format is supported.
PixmapSize
The size of the pixmap in pixels. The pixmap must be square; its size
is specified by the length, in pixels, of one of its sides. Because the
symbol alert does not scale with the submap, the graphic is needed in
only a single size, one pixmap file per symbol alert type.
116
Chapter 2

Creating Symbols
Table 2-20
Component
Description
TextRegion
TextRegion is the specification in pixels of a rectangular text

region within the pixmap. The text region is used to determine where
the upper left point of the text should be located in relation to the
pixmap. The height and width specifications do not constrain the
region in which the text may appear; that is constrained by the length
of the text lines (up to 12 characters), the number of text lines (up to
two), and the font. It is possible that symbol alert text could be
displayed outside the symbol alert text region. Both x and y
coordinates for the center are unsigned.
Text region includes the following specifications:
RegionCenter specifies the x and y coordinates of the center of

the pixmaps text region relative to the upper left corner
(designated 0,0) of the pixmap.
RegionHeight specifies the height of the pixmaps text region

in pixels.
RegionWidth specifies the width of the pixmaps text region in

pixels.
When a particular text annotation string is displayed in the text region

of the symbol alert the text can be centered or left aligned. Refer to
the OVwSetSymbolAlertText(3) reference page for further details on
the text alignment argument in the API call that supports these
options.
An incomplete text region specification, for example, is one that is
missing RegionCenter generates a parsing error and the symbol
alert type registration is ignored.
A text region specification that is complete but which specifies a
region outside the pixmap generates a parsing warning and default
values for the text region replace the specified values.
Running ovw -verify identifies all symbol alert type parsing
errors and warnings except the error of specifying a pixmap which is
not found.
Chapter 2
117

Field Registration File

Fields are the building blocks used to construct objects. Fields define
individual characteristics, which, when grouped together into a single
entity, form an object. This section describes how to use a field
registration file (FRF) to define fields for objects.
Fields are defined using a field registration file. Field registration files
are stored in the\OpenView\fields\$LANG on the Windows NT
operating system or $OV_FIELDS/$LANG/ on UNIX systems.
NOTE
Note that you can only add fields, you cannot delete them. After they are
added, you must rebuild the database.
Defining Fields
There are three components to a field definition:
the field name
the data type of the field
flags that indicate how the field is used.
The field name and field type are required.
Every field must have a data type and a unique name. Flags can be
optionally supplied to alter how the field is treated by NNM.
Use the field block structure to define fields. The FRF contains one or
more field blocks, where each field block defines a single field. The field
block has the syntax:
Field "non-localizable string" {
Type "field type";
[Enumeration <field enumeration>;]
[Flags "field flags";]
}
DisplayString is a localizable string that is displayed when the

application is run in a native language mode. For example, if your
118
Chapter 2

application will be run in German language mode, the string would be
specified as German text. If no DisplayString is specified, the
nonlocalizable ASCII string specified for Field is used to display the
label. For more information on internationalization and localization refer
to Application Registration File Support for Internationalization and
Localization on page 48 and Chapter 10 , Developing Internationalized
and Localized Applications.
Field Type
Every field has an associated data type. The Type entry declares the
fields data type. Type is a required entry, and must be set to one of four
possible types:
Boolean. This type can only have the values True or False.
String. A standard character string, limited to 256 characters in
length.
Enumeration. Declares the field to be an enumerated type. All
possible values for the enumerated type are declared in a separate
Enumeration statement.
Integer32. A 32-bit signed integer.
Field Flags
While the Type field specifies the data type of the field, the Flags field
specifies how the field is treated by HP OpenView. NNM gives you the
flexibility to treat fields in different ways. For instance, you can specify
that a particular field is a name field, which means that the value of
the field is unique across all objects that contain the field. You can also
specify that a particular field should appear in the Edit:Find->Objects
By Attribute dialog box on the NNM menu. These behaviors, as well as
others, are defined in the field registration file.
There are five types of flags (behavior) that can be applied to fields:
List
Specifies that the field contains a list of fields of the same type, rather
than just a single field. The list flag allows you to associate multiple
values of the same type with a single field definition. The list flag is
valid for string and integer data types. However, user interface
support is available only for lists of strings, not for lists of integers.
Chapter 2
119

Fields that are lists of integers can be defined and manipulated using
OVwDb routines in the OVw API. But they are not valid fields for the
Enroll blocks in an applications application registration file. Lists of
strings are the only list fields which are valid in an ARF.
For example, you might define a field for the names of administrators
of your computer network. The type would be string, and the flag
field would be set to list to allow you to store multiple names.
Name
Indicates that the value of the field uniquely identifies an object
containing this field definition. This flag can only be used for fields of
type string.
For example, the IP Hostname field is defined using the name flag,
because each node on a network must have a unique IP Hostname.
Non-string data types with unique values (such as a network
adapters link-level address) can serve as name fields provided that
they are converted to and stored as strings.
Name fields, because they are unique, can be converted to object
identifiers by using the procedure call, OVwDbNameToObjectId().
NOTE
Do not use the name flag for a field unless you require the values
assigned to that field to be unique across all objects in the database.
Locate
By specifying this flag in the field definition, the field name shows up
in the Edit:Find->Objects By Attribute dialog box when end
users attempt to locate an object.
You should use care in setting this field. If you do not specify the
locate flag, end users wont be able to locate an object based on your
field. Alternatively, indiscriminate use of the locate field will result
in an overabundance of locate entries, making that dialog box harder
to use effectively. Set this flag only if end users have a strong need to
locate objects through this field. This flag cannot be used together
with the list flag.
Capability
By setting this flag, the field is considered by NNM to be an object
120
Chapter 2

capability. In other words, the field is used to classify an object. For
example, NNM defines fields such as isRouter and isDevice. These
fields are used to classify objects and are often used in assertions. The
capability flag may only be used for Boolean and enumerated field
types. Capability fields determine menu greying (which menu
operations are available based on the selected objects).
All capability fields appear read-only in the capability fields list
presented during callbacks.
General
Fields with this flag appear in a special General Attributes dialog box
associated with every object. This is for fields that are not
application-specific and do not appear in any application-specific
dialog box. The vendor field is a good example of a general field.
As you can see from the flag descriptions, not all data types can be used
with all flags. The following list summarizes valid data type/flag
combinations:
The Integer data type can be used with these flags: List**, Locate,
and General.
** Lists of integers are not supported through the user interface.
The String data type can be used with these flags: List, Name,
Locate, and General.
The Boolean data type can be used with these flags: Capability,
Locate, and General.
The Enumeration data type can be used with these flags:
Capability, Locate, and General.
Example Field Definitions

This section shows how to use field types and flags. The first set of
examples demonstrate the use of capability fields.
Field "isNode" {
Type boolean;
Flags capability;
}
Field "isDevice" {
Type boolean;
Flags capability;
}
Chapter 2
121

Field "isComputer" {
Type boolean;
Flags capability;
}
You can see that these three fields are used to determine an objects
capabilities. An object could have device, computer, or node capabilities.
In fact, an object could even have a combination of these capabilities.
Capability fields are used to classify objects in NNM and, therefore,
cannot be used to uniquely identify (or name) an object.
The next example demonstrates how to define enumerated types, as well
as how to use the locate flag:
Field "IP status" {
Type enumeration;
Enumeration "Unknown",
"Normal",
"Marginal",
"Critical",
"Unmanaged";
Flags locate;
}
This example shows how you might use enumerated types to classify the
status of nodes on a network. Each node on a network would have a
status value from this set. By setting the locate flag, end users have the
ability to search for, or locate, all nodes on the network with a particular
status. It would not be valid to set the name flag for this field.
The next example demonstrates how to use a field as a name field.
Because the hostname of a computer would be unique for all nodes on the
network, the name flag can be set for the field.
Field "IP Hostname" {
Type string;
Flags name;
}
The following example demonstrates how to use the list flag in field
definitions.
Field "Service Contacts" {
Type string;
Flags list;
}
122
Chapter 2

This field definition specifies that the fields value is actually a list of
strings, such as the names of people who can service equipment.
Combinations of Flags
Flags can be applied to different data types and for different purposes.
The examples above do not use combinations of flags, but there may be
occasions where you want to use flags in combination. Flags can be used
in the following ways:
All flags can be used individually.
The name and locate flags can be used together (for string fields).
The capability and locate flags can be used together (for Boolean
and enumeration).
The general flag can be used with the other valid combinations
described here.
If a combination is not listed here then it is not permitted. For example,
you cannot combine the name, capability and locate flags in a single
flags statement. Because name fields must be strings, and capability
fields must be Boolean or enumeration, there is no field that would be
valid for both.
Field Registration File Support for Internationalized

and Localized Applications
HP OpenView field registration files support internationalization by
allowing a DisplayString of each field name to be localized. All other
field registration file components are restricted to ASCII characters and
must be identical in each different language version of the field
registration file.
Follow these guidelines to localize field registration files:
Specify ASCII strings for the field names.
Install your field registration files in \OpenView\fields\$LANG
on the Windows NT operating system or $OV_FIELDS/C on UNIX
systems.
Chapter 2
123

Do not modify the ASCII specifications for the field names.
Specify localized strings for the field names by using the
DisplayString statement.
Install your localized field registration files in
\OpenView\fields\$LANG on the Windows NT operating system
or $OV_Fields/$LANG on UNIX systems, where $LANG is the
locale name of the native language for your application.
For example, if an application is to be localized into German, and you
want to create a new field type, the field registration file might look like
this:
Field "New Field" {
Type String;
Flags name, locate;
DisplayString "Eignes Field";
}
Here the DisplayString statement specifies the localized string for the
field name. The string specified by the word Field must be ASCII
characters and must be identical in all language versions of this
applications field registration files. Whenever HP OpenView is started
up in German language mode, the DisplayString is displayed as the
field name. If no DisplayString is specified, the ASCII string specified
for Field is displayed.
HP OpenView Application Style Guide for design guidelines.
HP OpenView Windows Developers Guide, Chapter 10 , Developing
Internationalized and Localized Applications, for implementation
guidelines.
the OVwRegIntro(5) reference page.
124
Chapter 2

Summary
Summary
The application, symbol type, and field registration files provide a static
mechanism to configure HP OpenView behavior.
Application registration files are used to integrate applications into the
HP OpenView user interface. ARFs define all aspects of an applications
interaction with Network Node Manager, including how applications are
added to the menu structure, how applications are invoked and
application processes managed, and where application-specific help
information is located.
Symbol type registration files are used to define symbol classes and
symbol subclasses. Symbol classes can represent either icon or
connection symbols. Icon symbol classes are defined using line segments
or arcs, while icon symbol subclasses are defined by standard pixmaps.
Connection symbol classes and subclasses are described in the reference
pages. Network Node Manager provides you with a large set of
predefined symbol classes and subclasses, but you can define your own as
well.
Field registration files are used to define fields, which are attributes of
objects. Field registration files define the data type and behavior for
fields.
Chapter 2
125

Summary
126
Chapter 2
Integrating with NNM Online

Help
127
Integrating with NNM Online Help
This chapter describes the HP OpenView Windows help for HP-UX and
Solaris systems and explains how to use it. Developers should provide
application help information to assist users with their tasks. HP
OpenView Windows on the Windows NT operating systems uses the
native WinHelp functionality.
HP recommends that all HP OpenView applications on UNIX systems
provide on-line help information as described in this chapter. You are not
required to implement online help, nor are you required to follow the
exact recommendations described here. The guidelines presented in this
chapter are simply recommendations. There are, however, many
advantages to following these recommendations. End-users benefit by
having a help system that behaves consistently across applications
developed by multiple vendors. This makes application help information
easier to access, both for novice and advanced users.
Common Desktop Environment (CDE) Help, the help system provided
for HP-UX and Solaris by HP OpenView Windows, lets help authors
provide help that includes formatted text, graphics, hyperlinks, and
communication with the application. This enables development of
context sensitive help that displays information specific to the area of the
application which is currently in use.
CDE Help also provides a programmers toolkit for integrating the help
facilities into an application.
This chapter covers the following material:
an introduction to the CDE help system
deciding whether to use the CDE help system
building and integrating CDE help information with HP OpenView
Windows.
128
Chapter 3

An Introduction to the Help System
An Introduction to the Help System

OVW Help System Concepts
The HP OpenView Windows help system is conceptually very simple. In
its most basic form, the HP OpenView Windows help system is composed
of
a compiled CDE Help volume
a mechanism for linking user actions, such as selection of a Help
button or menu item, to a particular help topic identifier
a viewing facility that displays help text in a window, providing scroll
bars to allow users to move through the text.
The next section describes how users can request help in HP OpenView
Windows. After reviewing how users access help, the details of
implementing a help system are presented.
Accessing Help in HP OpenView Windows
From a developer point of view, users can access help in HP OpenView
Windows in several ways. Users can select help for any application from
the Help menu on a menu bar
[Help] buttons in application dialog boxes corresponding to the four
Add, Connect, Configure, and Describe dialog boxes
an application specific interface, such as a help button in a custom
dialog box or in the help menu in an application-specific menu bar
a command-line request for a specific help topic or the home topic of a
CDE Help volume.
Chapter 3
129

Deciding Whether to use the HP OpenView Help System
Deciding Whether to use the HP OpenView

Help System
HP recommends using the CDE Help system whenever possible.
Developers are free, however, to use another help system if appropriate
for the application. Developers are not required to supply application
help information.
There are a number of strong reasons for using the CDE Help system. By
integrating your help information into the CDE Help system, users see
help information that is consistent, in both style and format, across
multiple OVW applications. If you follow the recommendations in this
chapter and in the HP OpenView Application Style Guide, your help
information will be consistent with other applications, making help
information easier to use.
130
Chapter 3

Building and Integrating Help Information with HP OpenView Windows
Building and Integrating Help Information

with HP OpenView Windows
This section describes how to integrate application help information with
HP OpenView Windows. Table 3-1 and Table 3-2 show at a high level the
steps required to develop help with OVW.
The HP OpenView Windows Help Directory Structure

Any time a user requests help, OVW looks in a predefined directory
structure for the appropriate help information. All help volumes are
stored in subdirectories under the directory path,
$OV_HELP/$LANG/appname, then linked to
/usr/dt/appconfig/help/$LANG.
Each application that uses CDE help can place its help volume in a
separate directory. Developers integrate their help by providing links
between dialogs and help text in the help app-defaults file,
$APP_DEFS/OVw.help, and by editing the application registration file to
add access to help topics to the help pull-down menus.
The $LANG environment variable and the appname entry are described in
Chapter 2 , Creating and Using Registration Files. Recall that the
$LANG environment variable defines the default language for help files.
The default value of $LANG is C. Further, recall that applications can
specify a help directory in the application block in the application
registration file. That value is substituted for appname. For example, if
your default language variable is C and your application registration file
contains the entry:
Application "My app" {
...
HelpDirectory "thisapp";
...
}
then the root of your help directory would be: $OV_HELP/C/thisapp

All help volumes are stored relative to this directory path. Subsequent
sections in this chapter refer to the path using the $LANG and appname
arguments. You should substitute your values for $LANG and appname in
those examples.
Chapter 3
131

Adding Help Information to OVW Main Menu Bar
Adding Help Information to OVW Main Menu

Bar
You should read this section if you want your application help
information to be available under any of the menu items in the Help
menu under an OVW menu bar.
Table 3-1
Integrating Help to Pulldown Help Menus

Development Steps
Author writes help topics.
Documentation
HP OpenView Application Style Guide
CDE Help System Developers Guide
Author compiles help volume.
Developer places compiled volume into

/usr/OV/help/$LANG/app_name
This chapter.
Developer links help volume to

/usr/dt/appconfig/help/$LANG
This chapter.
Developer customizes Help menu to provide

access to help topics by editing the application
registration file.
OpenView Developers Guide (this book). Refer to

Chapter 2 , Creating and Using Registration Files.
The Help menu in the OVW main menu bar contains the following items:
Overview
Display Legend
Mouse & Keyboard
On Window
Whats New With OVW
Using Help
Misc->
Tasks
Functions
NNM->
Overview
Tasks
Whats New with NNM
About NNM
About OpenView
132
Chapter 3

The HP OpenView Application Style Guide explains the purpose of each
item on the menu.
Customizing the Help Menu

To understand how to customize the Help menu, examine the contents of
the registration file /usr/OV/registration/C/ovw. Near the beginning
of the registration file, the name of the help directory is specified:
HelpDirectory "OVW";
Note how, later in the file, the contents of the Help pull-down menu are
defined. The help browser is called to display a topic in a help window,
via the entry f.help_browser "volumeName:helpTopicId". In the
following excerpt from the ovw registration file, the first item on the Help
menu is Overview. The help system will look in the help volume ovw for
the help topic named overv.
MenuBar <100> "Help" _H
{
<100> "Overview" _V
Context (AllContexts || WantHelpMenus
f.help_browser "ovw:overv";
<100> "Display Legend" _D Context (AllContexts ||
WantHelpMenus)
f.disp_legend;
<100> "Mouse and Keyboard" _M
Context (AllContexts || WantHelpMenus)
f.help_browser "ovw:mousenkeyboard";
<100> "On Window" _W Context (AllContexts || WantHelpMenus)
f.help_browser "ovw:OnWindow";
<100> "Whats New with OVW" _N
Context (AllContexts || WantHelpMenus)
f.help_browser "ovw:whatsnewOVW";
<100> "Using Help" _U Context (AllContexts || WantHelpMenus
f.on_help;
<100> "Misc" Context (AllContexts || WantHelpMenus)
f.menu "Misc Help";
<98> "About OpenView" _A Context (AllContexts ||
WantHelpMenus)
f.about_ovw;
}
Menu "Misc Help"
{
<98> "Tasks" _T Context (AllContexts || WantHelpMenus)
f.task_index;
<98> "Functions"
_F
f.function_index;
}
The Quick Navigator menu definition shows how to use the context
definitions to exclude the help topics defined for the main help menu.
Chapter 3
133

MenuBar <100> "Help" _H
{
<100> "Overview" _V
Context (OVwNavigator)
f.help_browser "ovw:goto";
<100> "Display Legend" _D Context (OVwNavigator)
f.disp_legend;
<100> "Mouse and Keyboard"_M Context (OVwNavigator)
f.help_browser "ovw:mousenkeyboard";
<100> "On Window" _W Context (OVwNavigator)
f.help_browser "ovw:onnavwindow";
<100>
"Using Help" _U Context (OVwNavigator)
f.on_help;
<98> "About OpenView" _A Context (OVwNavigator)
f.about_ovw;
}
Note in this example that the help topic for Overview is defined as
ovw:goto. The context for this Overview item on the Help pull-down
menu is limited to the Quick Navigator window by the context
expression:
Context (OVwNavigator)
Chapter 2 , Creating and Using Registration Files, provides details

about using context expressions in registration files.
134
Chapter 3

Adding Help Information for HP OpenView Windows Dialog Boxes
Adding Help Information for HP OpenView

Windows Dialog Boxes
You should read this section if your application creates an application
registration file enroll block for a dialog box. This section describes how
to provide help information for those dialog boxes.
Several programming steps are necessary to support these types of
dialog boxes. Applications must use the application registration file to
register an Enroll block for the dialog box (refer to Chapter 2 , Creating
and Using Registration Files.)
Register an Enroll Block for an OVW Dialog Box

Each Enroll block in an application registration file defines which help
topic is displayed when a user selects the dialogs help button. The
helpfile definition in the Enroll block has the form:
Enroll Describe {
if isIP && isInterface {
Help Browser "nnm:IDescintrface.dbx";
}
}
IDescintrface.dbx is the identifier assigned to a help topic in the help

volume registered for NNM. The help text source file for the help topic
looks like this (the help identifier in the following example is
id=IDescintrface.dbx):
<s1 id=IDescintrface.dbx>Display Interface Attributes
Displays object attribute values for an interface on a node
submap of the network map.
Chapter 3
135

Adding Help Information for Application-Specific Help Access
Adding Help Information for

Application-Specific Help Access
The help integration methods described earlier will not be adequate for
all applications. While some applications only need to provide general
help information through the OVW main menu bar, other applications
might need to provide supplemental help information. Specifically, if
your application provides some form of custom user interface, such as an
application menu or dialog box, you will need to use more advanced help
integration methods to provide additional help access to your users. Read
this section to see how to supply help information for applications that
provide a custom user interface.
When an application communicates directly to the user through a
custom interface, it is not possible for OVW to completely manage the
display of help information. The application, not OVW, is responsible for
determining how and when a user requests help information. After an
application determines that a user needs help information, the
application can call an OVw API library routine, OVwShowHelp(), to
display the help information. Exposing the OVW help file viewing facility
through the OVw API benefits both developers and users. Developers
benefit by being able to quickly implement a help system using tools
provided with OVW. Users benefit by seeing help information through a
common user interface, regardless of whether the application or OVW is
responsible for determining how the user requested help.
Incorporating Help Into Your User Interface

If your application provides an application-specific user interface (that is,
an application tool window), you should provide access to application
help information through that interface. The HP OpenView Application
Style Guide describes how to structure menus and dialog boxes for
136
Chapter 3

applications. Refer to the Style Guide for help access recommendations
before designing your user interface.
Table 3-2
Integrating Help to Application-Specific Help

Development Steps
Author writes help topics.
Documentation
HP OpenView Application Style Guide
Author compiles help volume.
Developer places compiled volume into:
This chapter.
/usr/OV/help/$LANG/app_name
Developer links help volume to:
This chapter.
Developer customizes Help menu on application
menu bar to provide access to help topics by
editing the application registration file.
HP OpenView Windows Developers Guide (this

book). Refer to Chapter 2 , Creating and Using
Registration Files.
Developer uses OVwShowHelp() API to display

the appropriate help information through the CDE
help viewer.
HP OpenView Windows Developers Guide (this

book). OVwShowHelp() is described in Chapter 4 ,
Using the HP OpenView Windows API.
Application-Specific Help Files

Developers should provide application-specific help volumes using the
formats recommended in the HP OpenView Application Style Guide.
HP recommends that you store your application-specific help volume
under your help directory. You can use the following directory structure
for your application-specific help volume:
$OV_HELP/$LANG/appname/helpvolume
Note that these directories are different than those used for the
previously-described OVW help volumes.
Your help volumes then need to be linked to:
Chapter 3
137

Using the OVw Libraries to Display Help Information

The OVw API library routines let you display the contents of a help
volume through the CDE Help viewing facility
Applications call the OVwShowHelp() routine to display help information
or a help index. This routine is described in Chapter 4 , Using the HP
OpenView Windows API.
138
Chapter 3

Summary
Summary
This chapter described how to integrate application help information
into the CDE help system on HP-UX and Solaris. Developers can
integrate application help into HP OpenView Windows in one of three
ways: through the OVW main menu bar, through OVW-generated dialog
boxes, and through application-specific user interfaces.
Developers should follow the HP OpenView Application Style Guide
recommendations for content and format of help text files. This ensures
consistency for the user when viewing help information generated by
different applications.
The most general way to integrate application help information into
OVW is through the Help menu on the OVW main menu bar. Help
information available through the menu bar is general in nature.
Developers can use enroll blocks in application registration files to
define OVW-generated dialog boxes for Add, Describe, Connect, and
Configure map operations. Applications that use enroll blocks should
provide dialog box help information.
Applications that use a custom user interface (such as a custom menu or
dialog box) should also provide application-specific help through that
interface. The application, not OVW, is responsible for determining how
and when users request this help information. Developers can then call
OVw API routines to display the appropriate help information through
the OVW- provided help file viewer.
Chapter 3
139

Summary
140
Chapter 3
Using the HP OpenView

Windows API
141
Using the HP OpenView Windows API
This chapter presents application design concepts and OVw API routines
that are found, in some form, in almost all OVW applications. After
reading this chapter, you will know how to initialize your application,
how to structure your application, and how to exit once processing is
complete.
This chapter relies on information presented in Chapter 1 , Developing
Applications for HP OpenView Windows, and Chapter 2 , Creating and
Using Registration Files. Concepts and techniques presented in this
chapter appear throughout the remainder of this manual.
142
Chapter 4

Overview
Overview
This chapter describes:
the OVW programming model
connecting applications to HP OpenView Windows
defining callback routines for events
processing events
error handling
getting the application name
getting the selection list
highlighting objects on the map
using the OVw API help routines.
Chapter 4
143

The OVW Programming Model
The OVW Programming Model

In traditional programming environments, applications follow a
sequential programming model in which the program has complete,
deterministic control over its behavior. If a program wants user input, it
can request that the operating system display a prompt, followed by a
request for user keystrokes. One activity specifically follows another
under complete control of the executing program. Users must interact
with the program in a predefined way.
This traditional programming paradigm is not sufficient, though, to
handle the complex graphical environments in use today. Users can
interact with programs through a variety of input devices (such as
keyboards and mice) and can interact nondeterministically with
programs in unexpected ways. A program must be able to deal with user
requests in a much more flexible manner. Program behavior must be
driven by the activities, or events, that users initiate. Applications using
the OVw API are written using this event-driven programming
paradigm.
Programs developed under an event-driven paradigm look
fundamentally different than traditional programs. If you are familiar
with X Windows, then this event-driven paradigm may already be
familiar to you. At an abstract level, programs appear as a collection of
routines that declare an interest in specific events generated by the user
or system. These supporting routines are called as user and system
events occur and perform the real work of the program. The programs
main routine simply performs initialization, associates routines to
particular events, and then enters a loop that waits for and processes
events.
In OVw API terminology, the routine that is called when an event occurs
is known as a callback routine. The declaration of a routines interest
in a particular event is referred to as callback registration. The
portion of the main routine that waits for and processes events is called
the event loop.
144
Chapter 4

Connecting Applications to HP OpenView Windows
Connecting Applications to HP OpenView

Windows
There are three basic steps that your HP OpenView Windows application
must perform. It must
connect to HP OpenView Windows
define callback routines to be invoked when specific events occur
enter a loop that waits for and processes events
The first step, connecting to HP OpenView Windows, is the subject of this
section.
To connect your application to HP OpenView, call the OVwInit() or the
OVwInitSession() routine. The OVwInit() routine initializes internal
API data structures, ensures that the object database connection is
consistent with the GUI session, and establishes a connection from your
application to OVW. No other OVw API calls can occur before your
application connects to HP OpenView Windows. After the OVwInit() call
has been issued, you are free to issue any other calls in the OVw API.
OVwInitSession() provides the same functionality as OVwInit(), but
initializes a connection from a specific application to a specific ovw
session.
When your application has finished interacting with OVW, you must
disconnect from OVW. This is done by calling the OVwDone() routine. The
OVwDone() routine cleans up internal API data structures and closes the
connection from the application to OVW.
Chapter 4
145

Defining Callback Routines for Events

The second major step that every HP OpenView Windows application
must perform is to define callback routines that are invoked when
specific events occur. Events and callback routines form the backbone of
HP OpenView Windows application programming.
Events are notifications that OVW applications receive indicating that
some condition has changed. Events can be caused by end-user actions
(such as adding a symbol to a map) or by applications (such as creating a
submap or changing symbol status).
Applications do not receive all OVW events automatically. Applications
must specifically register callback routines for events in which they are
interested. If an event occurs and a callback routine is not registered for
it, the event is not sent to the application.
OVW Events
HP OpenView Windows defines approximately 30 events for application
use. Applications can choose to register for as many events as desired.
The full set of OVW events is defined in the file
\OpenView\include\OV\ovw.h (Windows NT operating system) or
$OV_HEADER/OV/ovw.h (UNIX systems). The following list contains a
sample of OVW events:
ovwEndSession
OVw terminated.
ovwSelectListChange
The selection list changed.
ovwMapOpen
A map was opened.
ovwMapClose
A map was closed.
ovwQueryAddSymbol
A user wants to add a symbol to a

map.
ovwConfirmAddSymbol
Confirmation that a symbol was

added to a map.
Use the OVwAddCallback() OVw API routine to register for events.

OVwAddCallback() has the following function prototype:
146
Chapter 4

int OVwAddCallback
(OVwEventType event, OVwFieldBindList *capabilitySet,
OVwCallbackProc callbackProc, void *userData);
The arguments to OVwAddCallback() are as follows:

event defines the event to be registered. All possible OVW events are
defined in the file \OpenView\include\OV\ovw.h (Windows NT
operating system) or $OV_HEADER/OV/ovw.h (UNIX systems)
and described in OVwEventIntro(5).
capabilitySet is used for callback routines that pertain to objects.
This field lets you associate callback routines not only to a specific
event, but also to specific kinds of objects based on the values of
capability fields. The callback routine will be called only for objects
that have the specified capability field values. This filtering can
reduce the number of events an application receives. You can have the
same event registered with multiple callback routines, provided that
they use different object capability fields. You can supply a NULL
value if object capability fields are not of interest to your callback
routine.
callbackProc is the name of the applications callback routine. The
argument list for each callback routine will vary, depending on the
event type.
userData is a user-defined, user-supplied parameter for the callback
procedure. You are free to use this field however you wish.
The OVwAddCallback() OVw API routine is used to register all events.
Callback routines can, however, have different arguments, depending on
the event type. As you might expect, OVW needs to pass different types
of information to the callback routine based on the type of event that
occurs. In some cases, OVW might need to pass object information, while
in another, OVW might need to pass symbol information.
A specific callback procedure function prototype exists for each event
type. These function prototypes are found toward the end of the
\OpenView\include\OV\ovw.h (Windows NT operating system) or
$OV_HEADER/OV/ovw.h (UNIX systems) header file.
The following example shows how an application connects to OVW and
how it registers a callback routine. (The argument list for the callback
routine is not described here; it is provided for completeness only.)
Chapter 4
147

#include <OV/ovw.h>
endSessionCB(userData, type, normalEnd)
void *userData;
OVwEventType type;
OVwBoolean normalEnd;
{
printf("OVW is terminating, so are we\n");
OVwDone();
exit(0);
}
main()
{
int ret;if (OVwInit() < 0) {
printf("application couldnt initialize with OVW\n");
exit(1);
}
ret = OVwAddCallback
(ovwEndSession, NULL,(OVwCallbackProc) endSessionCB,
NULL);
if (ret < 0) {
/* error processing */
}
OVwMainLoop();
}
Note that the OVwMainLoop() procedure in the main() function hasnt

yet been described. It will be discussed in Processing Events on page
151.
Action Events
In addition to receiving events, OVW applications can also receive
notification when end users invoke application-provided actions from
either OVW menu items or from executable symbols. These are special
events we call action events.
Callback registration for action events is very similar to event
registration described previously. Action events are registered with a
similar call, OVwAddActionCallback(). It has the following function
prototype:
int OVwAddActionCallback(char *actionID,
OVwActionCallbackProc callbackProc, void *userData);
148
Chapter 4

The argument list includes:
actionID, which is an Action name from the application registration
file for which a callback routine will be associated.
callbackProc, which is the name of the callback routine.
userData which is a pointer to a user-defined, user-supplied
parameter for the callback procedure. You are free to use this field
however you wish.
All action event callback routines have the same function prototype:
void (*OVwActionCallbackProc)
(void *userData, char *actionID,char *menuitemID,
OVwObjectIdList *selections, int argc, char **argv,
OVwMapInfo *map, OVwSubmapId submapID);
The arguments to an action event callback routine are as follows:

userData is a user-defined parameter that may have been specified in
the OVwAddActionCallback() procedure call.
actionID is the string by which the action is known in the
application registration file.
menuitemID is a string containing the label of the menu item used to
invoke the application. NULL indicates that the application was
invoked by an executable symbol.
selections is a copy of the current OVW selection list. Selection lists
are described in Selection Rules and the Selection List on page 159.
argc and argv contain callback arguments as defined in the
CallbackArgs statement in the ARF.
map is a pointer to an OVwMapInfo data structure that contains
information about the open map. (This is discussed in detail in
Getting Map Information on page 218.)
submapID is the ID of the submap on which the event occurred.
Submaps are described in detail in Chapter 6 , Creating and Using
Submaps.
The following example shows how to register for action events. Assume
this entry is present in the applications registration file:
Application "My application" {
MenuBar "Configure" {
"Callback Test" f.action "OVwAddActionCallback test";
Chapter 4
149

}
Action "OVwAddActionCallback test" {
Command "<your executable path>";
}
}
Here is a code segment that registers a callback routine to handle user

selection of the menu item:
#include <OV/ovw.h>
myActionCB(userData, actionID, menuitemID, selections, argc,
argv, map, submap)void *userData;
char *actionID;
char *menuitemID;
OVwObjectIdList *selections;
int argc;
char **argv;
OVwMapInfo *map;
OVwSubmapId submap;
{
...
}
main() {
int ret;
if (OVwInit() < 0) {
printf("error initializing with OVw\n");
exit(1);
}
ret = OVwAddActionCallback("OVwAddActionCallback test",
(OVwActionCallbackProc) myActionCB, NULL);
OVwMainLoop();
}
150
Chapter 4

Processing Events
Processing Events
The third and last major step that an HP OpenView Windows
application must perform is to process events. Events are processed
differently on HP-UX and Solaris than on the Windows NT operating
system.
Event Processing on HP-UX and Solaris

There are three basic techniques for processing events in OVW
applications for HP-UX and Solaris. You can
process only OVW events (using OVwMainLoop())
process both X and OVW events (using OVwXtMainLoop())
use your own select(2) loop to process events.
Your application needs to dictate which technique to use. If your
application does not use Xt calls directly, the first technique will probably
be the easiest to use. If your application uses Xt calls, you will probably
need to use the second technique using OVwXtMainLoop(). If neither of
these two general purpose routines suffice, you can use the third method
and implement your own event processing loop. The remainder of this
section describes these techniques in more detail.
Event Processing on the Windows NT Operating

System
For the Windows NT operating system, OVW events are processed
automatically. There is no special event processing required to receive
OVW events. OVwMainLoop is still provided for console applications and
for compatibility. There are two basic techniques for processing events in
OVW applications. You can
process Windows and OVW events (using Windows event loop)
process only OVW events (using OVwMainLoop()).
If your application is an OVW application, you will probably need to use
the first technique. If your application is a console application, the
second technique, using OVwMainLoop, will probably be the easiest to use.
Chapter 4
151

Processing Events
Checking for OVW Events

The simplest way to check for OVW events is to use the OVwMainLoop()
OVw routine. OVwMainLoop() loops forever, continually processing OVW
registered events. This routine checks each OVW event against a list of
preregistered events, and, if a callback routine is registered for the event,
the callback routine is invoked. Previous examples in this chapter have
shown how to use the OVwMainLoop() routine.
You may have noticed in the examples that the last statement in each
main() routine is a call to OVwMainLoop(). Since OVwMainLoop()
executes indefinitely, the main() routine never exits. OVW applications
must exit through another routine.
Checking for File Descriptor Input with OVwMainLoop() (HP-UX
and Solaris Only)
By default, the OVwMainLoop() routine processes only OVW events. As a
convenience, the OVw API lets you extend the OVwMainLoop() routine to
also check for and process file descriptor input events.
The OVwAddInput() routine adds an application file descriptor to the
OVW event processing mechanism as another source of events. The
routine has the syntax:
OVwInputId OVwAddInput(int file_descriptor, int conditionMask,
OVwInputCallbackProc proc, void *userData);
OVwAddInput() is passed the source file descriptor, a condition mask

that specifies a read event, and an application specific user data
parameter to be sent to the callback routine. The callback routine has
the function prototype:
void (*OVwInputCallbackProc)(int fileDescriptor, void
*userData);
The following example shows how to use the OVwAddInput() routine.

#include <OV/ovw.h>
my_fd_event_CB(fileDescriptor, userData)
int fileDescriptor;
void *userData;
{
...
}
152
Chapter 4

Processing Events
main()
{
int fd;
OVwInputId ret;
printf("error initializing with OVW\n");
exit(1);
}
/* <open socket fd, connect to a remote system
and wait for input> */
ret = OVwAddInput(fd, ovwReadMask, my_fd_event_CB, NULL);
OVwMainLoop();
}
Processing X Events and OVW Events (HP-UX and

Solaris Only)
OVW applications that perform X event processing should not use
OVwMainLoop(). Rather, they should use OVwXtMainLoop() to process
events. The OVwXtMainLoop() OVw API routine is designed specifically
to incorporate both OVW event processing and X event processing within
a single event handling call.
Sample code that demonstrates X event processing can be found in the
file \OpenView\prog_samples\ovw_examples\app6\six.c (Windows
NT operating system) or
$OV_PROG_SAMPLES/ovw_examples/app6/six.c (UNIX systems).
Checking for File Descriptor Input with OVwXtMainLoop()
(HP-UX and Solaris Only)
You can extend OVwXtMainLoop() to support file descriptor input events
by calling OVwAddInput() or XtAddInput(3X). For those readers
interested in OVW implementation details, OVwXtMainLoop() calls
XtMainLoop(3X) after using XtAddInput(3X) to ensure that OVW
events will be processed.
Using Your Own select() Loop (HP-UX and Solaris

Only)
If your application has special event processing needs that are not met
by OVwMainLoop() or OVwXtMainLoop(), you can process events yourself
using select(2) directly. You can use OVwFileDescriptor() to obtain
Chapter 4
153

Processing Events
the file descriptor associated with OVW event processing. Once you have
the file descriptor, you can add it to your select mask in your own
select(2) processing loop.
Checking the Event Queue

There may be occasions where your application is performing long,
intense operations under the assumption that OVW map status has not
changed in the interim. It is possible, though, that critical events could
occur that might justify interruption of your processing. One such event
would be the ovwMapClose event.
You can check the OVW event queue for the presence of specific events
using the OVwPeekOVwEvent() routine. This routine is called with a
specific event as an argument. It non-destructively examines the OVW
event queue and returns a boolean value indicating the presence of the
event.
Advanced Event Queue Management

A number of other advanced mechanisms are also available to check for
OVW events. The OVwPending() and OVwProcessEvent() routines
provide low-level control over OVW event processing and are not
described here. If the basic OVW event checking calls are not adequate
for your application, you can refer to the reference pages for information
on these advanced calls.
154
Chapter 4

Error Handling
Error Handling
Retrieving a Routines Result Code
OVW stores an internal result code for every OVw API call you make.
This internal result code contains an integer value that represents either
success or, if an error occurs, the cause of the error.
You can request this value by calling the OVwError()OVw API routine.
OVwError() returns the result code of the last OVw routine called by the
application. All error values are defined in the file
\OpenView\include\OV\ovw_errs.h (Windows NT operating system) or
$OV_HEADER/OV/ovw_errs.h (UNIX systems). Refer to the reference
pages to determine how particular OVw API routines return errors.
Converting a Result Code to a String

The OVw API also provides a routine that converts an integer result code
into the corresponding text string description. The OVwErrorMsg()
routine returns a pointer to a character string in static memory that
describes the error. The call has the syntax:
char *OVwErrorMsg(int error);
Since OVW allocates the memory for the character string from a static
buffer, you should not attempt to free the string memory after use.
The following example shows one way to use the OVwError() and
OVwErrorMsg() routines:
#include <OV/ovw.h>
...
main(argc, argv)
int argc;
char **argv;
{
if (OVwError() == OVw_OVW_NOT_RUNNING) {
printf("OVW must be running prior to running this
application!\n");
} else {
printf("%s\n", OVwErrorMsg(OVwError()));
}
Chapter 4
155

Error Handling
}
...
}
Checking OVW IDs

Upon completion, many OVw API routines return an ID of some form.
IDs are described later, but examples include object IDs, field IDs,
symbol IDs, and submap IDs.
As a convenience, the OVw API provides functions that test IDs in
different ways. They have the form:
OVwBoolean OVwIsIdNull(id);
OVwBoolean OVwIsIdEqual(id1, id2);
Though you could bypass these functions and implement these tests
yourself, we recommend using these functions. They hide the underlying
ID data types, making your program more portable in the event that an
ID implementation changes in the future.
156
Chapter 4

Getting your Application Name
Getting your Application Name

Recall from Chapter 2 , Creating and Using Registration Files, that an
Application Block within an application registration file defines your
application name. A number of OVw API calls require an application
name as an input argument.
You could, of course, hard-code those OVw API calls to use your
application name defined in your application registration file. This
solution is not foolproof, though, since changing the application name in
the ARF would cause your application to fail.
This problem is solved by using a routine in the OVw API that
programmatically retrieves your application name from the ARF. The
routine OVwGetAppName() returns your application name as defined in
the ARF. The following code segment demonstrates:
char *myname;
...
myname = OVwGetAppName();
printf("My name is: %s\n", myname);
free(myname);
...
Note that OVwGetAppName() returns a pointer to a string whose memory

is dynamically allocated. You should free the memory when it is no
longer needed.
Chapter 4
157

Getting the Object Selection List

The object selection list is the primary means for end users to pass
arguments to OVW applications. The selection list is automatically
provided as an input argument to Action callback routines when they are
invoked. This is the standard mechanism for applications to receive the
contents of the object selection list.
Some applications, however, need to determine the contents of the object
selection list at other times. The OVw API provides a routine that has
the function prototype:
OVwObjectIdList *OVwGetSelections(OVwMapInfo *map,
char *actionId);
It returns the current contents of the selection list. The

OVwGetSelections() routine returns a pointer to an OVwObjectIdList
structure that contains
a count of the number of selected objects in the list.
a pointer to a contiguous area of memory containing object IDs. The
memory may be treated as an array.
Most OVw API list data structures are implemented using a pointer to a
contiguous area of memory, rather than a NULL-terminated linked list.
The following example shows how to use the OVwGetSelections()
routine to traverse the list of objects whose IDs are represented in the
selection list. This example uses the OVwGetMapInfo() routine to get the
map information. OVwGetMapInfo() will be described in Getting Map
Information on page 218.
#include <OV/ovw.h>
...
main()
{
int i;
OVwObjectIdList *op;
OVwMapInfo *map;
OVwObjectId *lp;
...
map = OVwGetMapInfo();
op = OVwGetSelections(map, NULL);
printf("There are %d objects in the selection
158
Chapter 4

list\n", op->count);
for (i=0, lp = op->object_ids; i<op->count; i++, lp++) {
printf("object id[%d] is %ld\n", i, *lp);
}
OVwDbFreeObjectIdList(op);
...
}
Objects and object IDs are described in detail later in this manual.
Selection Rules and the Selection List

Recall from Creating and Using Registration Files, that you can define
selection rules for entries in the selection list. Selection rules are defined
within the context of a particular action and determine whether the
action will be available based on the list of selected objects. Selection
rules in the ARF are available for programmatic use as well.
To use selection rules in OVW programs, you simply take the Action ID
associated with the selection rule in the ARF and use it as an input
argument to the OVwGetSelections() routine.
For example, consider the following ARF.
Application "My app"
{
...
Action Trends {
SelectionRule isNode && isDevice;
...
}
...
}
To use the above selection rule in your program, you pass the "Trends"
argument to your OVwGetSelections() call. OVwGetSelections()
returns the current selection list only if the selection rule in the
"Trends" action is valid for all the objects in the selection list.
The ovwSelectionListChange Event

OVW generates the ovwSelectionListChange event whenever the
selection list changes. You can register a callback routine that, when this
event is received, determines the current selection list using
OVwGetSelections(). Selection list changes can occur frequently in
Chapter 4
159

OVW, so you should register for the ovwSelectionListChange event
only if absolutely required. Excessive use could degrade system
performance.
Changing the Selection List

OVW provides two functions that can be used to change object selection,
either by replacing it with a new selection or by adding to it.
The signatures for these APIs are:
int OVwSelectObject(OVwMapInfo *map,
OVwObjectId object, OVwBoolean clearPrevious)
and
int OVwSelectObjects(OVwMapInfo *map,
OVwObjectIdList objectList, OVwBoolean clearPrevious)
The object ID or list of object IDs is passed as an argument. Object ID

lists are described in Chapter 5 , Creating and Using Objects and
Fields. The mapInfo parameter may be NULL, in which case these
routines will refer to the open map.
The clearPrevious flag controls whether previously selected objects are
cleared. If FALSE, previously selected objects remain selected. If TRUE,
previously selected objects are cleared. Applications should use the
clearPrevious flag once at the beginning of each action for which the
selection is being done. If the application is performing selection in
successive calls, then it should use the clearPrevious flag only for the
first call.
These functions could be used to respond to the selection changed event
to implement security (to prevent some objects from being selected). To
do this, the application would set up a callback to be invoked when the
selection changes. This callback would call OVwGetSelections() and
look at the objects to determine whether an illegal selection was being
made. If so, the illegal object IDs would be removed from the list and the
callback would call OVwSelectObjects(map,objectList,TRUE).
160
Chapter 4

Highlighting Objects
Highlighting Objects
Applications can highlight one or more objects on a map as a result of a
user-initiated action (e.g., identifying all objects with a particular
characteristic). All symbols representing highlighted objects are
graphically displayed with symbol labels in reverse video. After
highlighting, users can select highlighted objects with the Select
Highlighted OVW menu item to make them input for another
operation.
The highlighting routines have the following function prototypes:
int OVwHighlightObject(OVwMapInfo *mapInfo,
OVwObjectId object,OVwBoolean clearPrevious);
int OVwHighlightObjects(OVwMapInfo *mapInfo,
OVwObjectIdList *objectList,OVwBoolean clearPrevious);
The object ID (or list of object IDs) is passed as an argument. Object ID

lists are described in Chapter 5 , Creating and Using Objects and
Fields. The mapInfo parameter may be NULL, in which case these
routines will refer to the open map.
The clearPrevious flag controls whether previously highlighted objects
are cleared. If FALSE, previously highlighted objects remain
highlighted. If TRUE, previously highlighted objects are cleared.
Applications should use the clearPrevious flag once at the beginning of
each action for which the highlighting is being done. If the application is
performing highlighting in successive calls, then it should use the
clearPrevious flag only for the first call.
Chapter 4
161

Using the Help Routines (HP-UX and Solaris Only)
Using the Help Routines (HP-UX and Solaris

Only)
Recall from Chapter 3 , Integrating with NNM Online Help, that most
applications can integrate help information into the OVW help system
without resorting to programming. Some applications, however, must use
the OVw API to integrate application-specific help information into
OVW. This section describes how to use the OVw API to incorporate help
information into OVW.
A single OVw API routine is used to programmatically access and
display help information. The OVwShowHelp() routine can display to the
user either a help file or an index of help topics. The routine has the
function prototype:
int OVwShowHelp(unsigned long helpType, char *helpRequest);
It has the following arguments:

helpType specifies the type of help being requested. The standard
help types are defined in \OpenView\include\OV\ovw.h (Windows
NT operating system) or $OV_HEADER/OV/ovw.h (UNIX systems).
The value of helpRequest can vary, depending on the help type. If
helpType is ovwHelpBrowser or ovwquickHelp, then the
helpRequest argument contains the volume name and help topic ID
of a specially-formatted help file.
ovwHelpBrowser helpRequest is assumed to contain either a
relative or fully-qualified path to the help volume,
and the location id of the help link within the help
volume. These two pieces of information must be
separated by a colon.
ovwquickHelp helpRequest is assumed to contain either a relative
or a fully-qualified path to the help volume, and the
location id of the help link within the help volume.
These two pieces of information must be separated
by a colon.
ovwHelpString helpRequest is assumed to contain a character
string to display in a help dialog.
ovwManPage
162
helpRequest is assumed to contain a character
Chapter 4

Using the Help Routines (HP-UX and Solaris Only)
string specifying the name of a reference page to
display in a help dialog. The name may be preceded
by a section number.
ovwTextFile
helpRequest is assumed to be the fully-qualified

pathname of a plain ASCII text file to display in a
help dialog.
ovwHelpOnHelp helpRequest is ignored for this helpType. The

CDE Help on Help volume is displayed in a help
dialog.
ovwHelpIndex helpRequest is assumed to be the path, relative to
the registered help directory, of an ovhelp index. If
the application has not registered a help directory,
the path is assumed to be relative to the OVW help
directory, $LANG. (Provided for applications
developed before NNM 4.0.)
ovwHelpFile
Chapter 4
helpRequest is assumed to be the path, relative to

the registered help directory, of an ovhelp help file.
If the application has not registered a help
directory, the path is assumed to be relative to the
OVW help directory, $LANG. (Provided for
applications developed before NNM 4.0.)
163

Summary
Summary
This chapter described the basic OVw API routines that are important to
most OVW applications. Most typical applications must perform three
steps: 1) connect to HP OpenView Windows, 2) define callback routines to
be invoked when specific events occur, and 3) enter a loop that waits for
and processes events. Applications connect to HP OpenView Windows by
calling the OVwInit() or the OVwInitSession() routine. Applications
then register callback routines to be invoked when specific events occur.
HP OpenView Windows supports different types of event processing. HPUX and Solaris applications that have no graphical user interface and
the Windows NT operating system console applications can use the
simple OVwMainLoop() routine. HP-UX and Solaris applications that use
X Windows and have a graphical user interface process events using
OVwXtMainLoop(). On the Windows NT operating system,
graphical-user-interface applications process OVW events automatically.
Applications that need advanced control over event processing can use
the OVW event processing primitives to implement customized event
processing.
Other general purpose routines were then described. These routines
perform such functions as: checking for OVw API errors, getting the
application name, getting the object selection list, highlighting objects,
and, for applications on HP-UX and Solaris, using the OVw API help
routines.
164
Chapter 4
Creating and Using Objects and

Fields
165
Creating and Using Objects and Fields
This chapter introduces the OVw API object database routines. These
routines create and manipulate objects and fields in the HP OpenView
Windows object database.
You should read this chapter if you want to create and/or manipulate
objects in the HP OpenView Windows object database.
166
Chapter 5

Overview
Overview
Topics in this chapter include:
the HP OpenView Windows object database
creating fields
creating objects
getting/setting object field values
deleting objects.
Chapter 5
167

The HP OpenView Windows Object Database

Database Implementation
The HP OpenView Windows object database manages all object and field
information for OVW. All OVW maps use the same object database.
Developer access to the OVW object database is limited to the supplied
OVw API object database routines. These OVw object database routines
shield the developer from having to code to a particular database
implementation. This scheme also allows for the potential substitution of
a different underlying database engine in the future without impacting
applications.
The OVW object database is implemented as a stand-alone module that
works in conjunction with the rest of OVW. This has interesting
ramifications for developers. Entries in the OVW object database persist
across OVW sessions. Fields and objects created in one OVW session are
available to all other applications in all OVW sessions. Since the OVW
object database is separate from the rest of OVW, developers can even
access the OVW object database without connecting to OVW with the
OVwInit() routine. (Developers can use a subordinate routine called
OVwDbInit() to connect directly to the object database).
In terms of naming conventions, the OVw API object database routines
all begin with the prefix OVwDb.
Fields
Fields are object attributes stored in the OVW object database. Fields are
the building blocks from which objects are constructed.
Fields can have one of the following four data types:
32-bit integer
Boolean
character string
enumerated value.
168
Chapter 5

Each field definition is uniquely identified by a field ID. Fields can
contain a single data element, or they can contain a list of data elements
of the same type.
The OVw API provides a number of routines to create and manipulate
fields. Other API routines retrieve field values and field information from
the object database in various ways.
By themselves, fields are not very useful. Only after a field is associated
with an object can you perform the real manipulation of data, such as
setting or retrieving field values. Fields can contain data only when they
are associated with objects.
Objects
In OVW, an object is an internal representation of a logical or physical
entity or resource that exists somewhere in a computer network. An
OVW object consists of a unique object identifier and a set of fields that
specify all the characteristics of the object.
The OVw API provides routines that create and delete objects, as well as
routines that change the object fields. Other OVw API routines perform
such functions as retrieving the list of all fields associated with an object
and searching the object database for objects that contain specific field
values.
Base Routines and their Variants

The OVw API provides almost 50 functions for interaction with the HP
OpenView Windows object database. The API is not as complex as it
might first appear, though.
A few basic data structures and general purpose function calls will
suffice for most applications. Many of the general purpose function calls
also have specialized variations that are more convenient in certain
situations. Once the general purpose routines are understood, the
specialized routines follow easily. This chapter presents all of the general
purpose object database routines, as well as some of the specialized
variations.
The complete set of function prototypes and data structure definitions for
all field and object database routines are located in the file
\OpenView\include\OV\ovw_obj.h (Windows NT operating system) or
$OV_HEADER/OV/ovw_obj.h (UNIX systems).
Chapter 5
169

Creating Fields
Creating Fields
Fields are created using either the field registration file (FRF) or the
OVwDbCreateField() routine. Field values are set using other API
routines described later in this chapter. You are free to use existing fields
or to create new ones as your application needs dictate.
Using the FRF versus the API to Create Fields

The field registration file is the normal and preferred way to create fields.
The OVwDbCreateField() routine is exposed for flexibility, but should
only be used in restricted cases.
There are two important reasons why you should create fields using the
FRF
OVW parses all application and symbol type registration files during
OVW startup. If an entry in these files refers to a field not already
defined, application startup may fail. Using the field registration file
to define a field is the easiest and surest way to guarantee that a field
definition exists during OVW startup.
The FRF makes field specifications visible to end users and
developers. Users can easily examine the set of field registration files
to see which fields are present in the object database. If fields are
created through the OVw API, their existence can only be determined
programmatically.
Creating Fields Programmatically

Fields are created using the OVwDbCreateField() routine. This routine
creates an entry in the OVW database that describes how data will be
stored and treated. This routine does not, however, assign data for the
field (the field value). You can assign a field value only after you have
created an object that uses that field. Once an object exists, you are free
to manipulate all field values associated with that particular object.
Though the same field can be used in different objects, each object can
have a different field value. Object creation is described later in this
chapter.
170
Chapter 5

Creating Fields
The OVwDbCreateField() call has the following function prototype:
OVwFieldId OVwDbCreateField(char *fieldName, int
fieldType, unsigned int fieldFlags);
When calling OVwDbCreateField, you need to supply these arguments:

fieldName is a character string containing the textual name for the
field.
fieldType is the data type. Valid types are ovwIntField,
ovwBooleanField, ovwStringField, and ovwEnumField. If the data
type is a list, then the fieldFlags argument will have the
ovwListField value set.
fieldFlags is a logical expression containing the flags to be set for
the new field. Valid flags are ovwListField, ovwNameField,
ovwCapabilityField, ovwLocateField, and ovwGeneralField.
(Valid combinations of field flags were described in Chapter 2 ,
Creating and Using Registration Files, in the field registration file
section.) The fieldFlags argument is 0 if no flags are needed. Valid
types and flags are defined in \OpenView\include\OV\ovw_obj.h
(Windows NT operating system) or $OV_HEADER/OV/ovw_obj.h
(UNIX systems).
The OVwDbCreateField() call returns an identifier of type OVwFieldId.
This identifier is used in subsequent OVw API calls involving the field.
At this point, the field exists in the database, and values can be set for
the field for particular objects.
The following short code segment shows how to create a field that is a list
of integers.
...
OVwFieldId field_id;
field_id = OVwDbCreateField("a_test", ovwIntField,
ovwListField);
Converting between Field Names and Field IDs

Most OVw API routines use the field ID, not the field name, when
dealing with fields. Both are unique ways to identify a field. You are free
to use either form in your programs, as long as it is converted to the
appropriate form for calls to the OVw API.
Chapter 5
171

Creating Fields
Two OVw API routines are available to convert between field names and
field IDs. They have the function prototypes:
OVwFieldId OVwDbFieldNameToFieldId(char *fieldName);
dchar *OVwDbFieldIdToFieldName(OVwFieldId fieldId);
Applications that create fields using the field registration file will need to
use the OVwDbFieldNameToFieldId() routine at some time. As
mentioned before, many of the OVW object database routines take a field
ID, not a field name, as an argument. To use these types of routines, you
will need to first convert the field name in the field registration file to a
field ID using OVwDbFieldNameToFieldId().
See the reference pages if you need more information about these
routines.
Defining Enumeration Values

1. The OVw API supports enumerated types as one of the field data
types. If you use enumerated types, you must follow the procedures in
this section to define the values for the enumeration. First, allocate
memory for the appropriate data structures. You need to allocate
memory for two data structures:
You must allocate memory for an array of pointers, where each
array entry points to one of the enumeration value strings.
You must allocate memory for the OVwEnumConstants data
structure, which contains a count of the number of enumeration
values and a pointer to the array containing pointers to the
enumeration values.
The data structure has the form
typedef struct {
int count;
char **names;
} OVwEnumConstants;
2. Define each enumeration value, storing the address of the string in

the array of string pointers.
3. Call the OVwDbSetEnumConstants() routine to set the values.
The following code segment example shows how to define an enumerated
type with three possible values.
172
Chapter 5

Creating Fields
...
OVwFieldId id;
OVwEnumConstants *p;
int ret;
/*
id
if
/*
}
create the field without special flags */

= OVwDbCreateField("enum_test", ovwEnumField, 0);
(OVwIsIdNull(id)) {
error processing */
/* allocate the memory for the enumerated constants structure

*/
p = (OVwEnumConstants *) malloc(sizeof(OVwEnumConstants));
/* allocate the memory for the pointers to the 3 names */
p->names = (char **) malloc(sizeof(char *) * 3);
/* now assign
p->count = 3;
p->names[0] =
p->names[1] =
p->names[2] =
each name */
"red";
"green";
"blue";
ret = OVwDbSetEnumConstants(id, p);
Retrieving Field Information

The OVw API provides routines that return information about a field.
These routines return such information as the field ID, the field name,
the field data type, etc. They return information about the field, rather
than field values for particular objects. You can retrieve information for a
single field or for all fields with particular characteristics in the object
database.
Use the OVwFieldInfo data structure to retrieve information about a
field. The data structure contains the field name, type, and flags, as well
as the field ID. The data structure has the form:
typedef struct {
char *field_name;
int field_type;
unsigned int field_flags;
} OVwFieldInfo;
Chapter 5
173

Creating Fields
Getting Field Information for a Single Field
The OVwDbGetFieldInfo() call returns field information for a single
field. When called with a field ID, it returns a pointer to an
OVwFieldInfo data structure containing field information. Since the
memory for the structure is dynamically allocated by OVW, you should
use the associated OVw API routine to free the memory when finished.
For example:
OVwFieldInfo *fp;
OVwFieldId id;
...
/* Create a boolean field */
id = OVwDbCreateField("test", ovwBooleanField, 0);
...
/* Retrieve the field information from the database */
fp = OVwDbGetFieldInfo(id);
printf("field_id
is %d\n, ", fp->field_id);
printf("field_name is %s\n, ", fp->field_name);
printf("field_type is %d\n, ", fp->field_type);
printf("field_flags is 0x%x\n", fp->field_flags);
OVwDbFreeFieldInfo(fp);
Getting Field Information for All Fields

The OVwDbListFields()routine searches the entire OVW object
database and returns a list of field information for fields that have the
appropriate flags set. Valid flags are ovwAllFields, ovwNameField,
ovwLocateField, ovwCapabilityField, and ovwGeneralField.
For example, the following code segment shows how to retrieve a list of
all fields in the object database that have the ovwNameField flag set.
OVwFieldList *flp;
OVwFieldInfo *fip;
int i;
...
flp = OVwDbListFields(ovwNameField);
for (i=0, fip=flp->field_list; i<flp->count; i++, fip++) {
<process the entry pointed to by fip>
}
OVwDbFreeFieldList(flp);
Getting Enumeration Type Values

After you have defined an enumeration, you can use a number of OVw
API routines to retrieve information about the enumeration. You can
174
Chapter 5

Creating Fields
retrieve the symbolic name list (OVwDbGetEnumConstants()) as well as
translate between symbol names and values (OVwDbGetEnumValue() and
OVwDbGetEnumName()). See the reference pages for more information on
these and other related routines that operate on enumerated data types.
Predefined Fields
Two name fields are predefined by OVW and are available for application
use
Selection Name
IP Hostname (IP networks only)
Applications should not attempt to redefine or change these predefined
OVW fields.
The field creation routines presented in this section let you create fields
and retrieve field information from the object database. They do not,
however, let you define field values. The next section describes how to
create objects and assign initial field values for fields in the object.
Chapter 5
175

Creating Objects
Creating Objects
When you create an object, an object definition is added to the OVW
object database. The object definition is created with a selection name
and an optional field value. Before describing how to create objects, some
discussion of the field value data structures and the selection name is
necessary.
The Field Value Data Structures

The OVwFieldValue data structure defines field values. Most OVw API
object database routines use the OVwFieldValue data structures in some
form, either as an argument or a returned result. The field value
structure is implemented as follows:
typedef struct {
OVwBoolean is_list;
int field_type;
union {
int32 int_val;
oVwBoolean bool_val;
char *string_val;
int enum_val;
OVwListFieldValue *list_val;
} un;
OVwBoolean modified;
} OVwFieldValue;
When used for simple data types, the is_list Boolean value is set to
FALSE, and the field value is stored as an integer, Boolean, string, or
enumerated value. The field_type entry specifies which union entry is
used.
The modified entry is not used during field creation and can be
temporarily ignored.
If the field value is a list, then the is_list entry is set to TRUE and
list_val points to a structure that heads the list.
The following additional data structures define the list head and the list
entries:
typedef struct {
union {
176
Chapter 5

Creating Objects
int32 int_val;
OVwBoolean bool_val;
char *string_val;
int enum_val;
} un;
OVwBoolean selected;
} OVwListFieldEntry;
typedef struct {
int count;
OVwListFieldEntry *list;
} OVwListFieldValue;
Note that for lists the data type is not specified in the
OVwListFieldEntry data structure. Since all items in the list must be
the same type, it is sufficient to specify the data type in the
OVwFieldValue structure.
The selected entry in the OVwListFieldEntry can be ignored
temporarily.
The following example shows how the OVwFieldValue,
OVwListFieldValue, and OVwListFieldEntry data structures are
related.
Chapter 5
177

Creating Objects
Figure 5-1
Lists of Field Values
OVwListFieldEntry
union {
int
boolean
string val
enum_val
OVwFieldValue
isList
field_type
union {
int
boolean
string val
enum_val
list_val
}
modified
}
selected
OVwListFieldValue
count
list
union {
int
boolean
string val
enum_val
}
selected
...
union {
int
boolean
string val
enum_val
}
selected
Note that the list of values is not implemented as a standard linked list.
The OVwListFieldValue structure that heads the list contains an
integer count of the number of list entries, followed by a pointer to a
contiguous array of list entries. For internal memory management
reasons, most OVW list data structures are implemented in this way.
The Selection Name

A selection name is a special name field that is set for all objects. Before
178
Chapter 5

Creating Objects
describing how the selection name is used, though, we need to review
some name field concepts.
Every object is uniquely identified by an object ID that is returned when
the object is created. In addition, an object can have multiple name
fields, such as a hostname (for TCP/IP networking), a Fully
Distinguished Name (for OSI networking), or a name created by an
application. A name field value for any object is guaranteed to be unique.
Therefore, any name field can be used to uniquely identify an object.
A selection name is required for every OVW object, regardless of other
name fields the object might have. You can define your own selection
name value when your object is created, or you can let OVW choose a
value for you.
As a name field, a selection name uniquely identifies an object. The
purpose of the selection name is to make sure that every object has a
human readable textual name that can be displayed through the user
interface to identify the object. The selection name is the principal name
by which the object is known through the user interface. Since the
selection name is intended for presentation purposes and can be changed
by the end user, applications should not rely on the value of the selection
name.
Creating an Object
With the field value data structure and selection name background
behind us, we can proceed with an example of object creation. Three OVw
API routines are available to create objects:
A generic routine that can create any type of OVw object
(OVwDbCreateObject()).
Two convenience routines that create objects by their hostname or
selection name (OVwDbCreateObjectByHostname() and
OVwDbCreateObjectBySelectionName()).
In general, objects are created with the OVwDbCreateObject() routine.
It has the following function prototype:
OVwObjectId OVwDbCreateObject(OVwFieldBinding *name);
The name argument is a pointer to an OVwFieldBinding structure, which

is simply a structure that links a field ID with a field value. The
OVwFieldBinding structure is defined as follows
Chapter 5
179

Creating Objects
typedef struct {
OVwFieldId
field_id;
OVwFieldValue *field_val;
} OVwFieldBinding;
If you call OVwDbCreateObject() with a NULL parameter, OVW will

create an object for you and assign it a system-generated selection name.
If you supply a pointer to a valid OVwFieldBinding structure in the
OVwDbCreateObject() call, one of three things can happen:
If the field value you supply is a selection name, then OVW will
attempt to define the object. If the selection name is already
allocated, the call will return an error. (You can optionally use the
OVwDbGetUniqName() routine to generate a selection name that is
guaranteed to be unique. OVwDbGetUniqName() is described later in
this chapter.)
If the field value is a name field other than the selection name, OVW
will attempt to define the object. If the name field value is not unique,
an error will be returned. If the name is unique, OVW will then define
the object, set the name field value, and generate a selection name for
you based on the name field you supply.
If the field value you supply is not a name field, then OVW will create
a selection name for you. The name will be in the form Selection
Namen, where n is some unique integer. You can change the
selection name later if you desire.
The following example shows how to create an object that contains a
name field. In this example, the name field is the NetBIOS system name,
as defined in a field registration file. Since the field is not a selection
name, OVW will also generate a selection name for the object.
OVwFieldId f_id;
OVwObjectId obj_id;
OVwFieldBinding *bp;
/* get the field ID associated with the NetBIOS Name */
f_id = OVwDbFieldNameToFieldId("NetBIOS Name")
if (OVwIsIdNull(f_id)) {
}
/* allocate an OVwFieldBinding structure */
bp = (OVwFieldBinding *) malloc(sizeof(OVwFieldBinding));
/* fill in the field_id entry and the field_value structure */
bp->field_id = f_id;
180
Chapter 5

Creating Objects
bp->field_val = (OVwFieldValue *)
malloc(sizeof(OVwFieldValue));
bp->field_val->un.string_val = "nametest";
bp->field_val->field_type = ovwStringField;
bp->field_val->is_list = FALSE;
/* create the object and save the object ID that is returned */
obj_id = OVwDbCreateObject(bp);
if (OVwIsIdNull(obj_id)) {
}
...
Generating Unique Names

The OVwDbCreateObject() routine returns an error if you attempt to
create an object with a name field value that is not unique. You could try
to generate a new name and try the call again, but there is no guarantee
that your new name is unique. The OVw API solves this problem by
providing a routine that generates a unique name for you, using a name
you supply as a base. The call has the following function prototype:
char *OVwDbGetUniqObjectName(OVwFieldId nameFieldId,
char *nameValue);
Heres how the routine behaves:

If you supply a name field value that is already unique, the same
name is returned to you.
If you supply a name field value that is not unique, OVW will choose a
unique name based on the value you provide. OVW will append an
integer to the base name such that the newly formed name is unique.
If you pass a NULL parameter for the nameValue parameter, OVW
will choose a unique name field value for you. OVW will convert the
field ID to a base field name, and will append an integer to the base
field name such that the new name is unique.
The name generated by the call is guaranteed to be unique, which lets
you call OVwDbCreateField() with assurance that your name is not
already allocated.
Creating Objects by Hostname or Selection Name

You can use the general purpose OVwDbCreateObject() routine to create
Chapter 5
181

Creating Objects
an object that has a hostname or selection name. The following steps are
involved:
1. Call the OVwDbFieldNameToFieldId() routine to retrieve the field ID
associated with the Hostname or Selection Name. (The "IP
Hostname" and "Selection Name" fields are already present in the
database, so you dont need to create them.)
2. Allocate memory for the OVwFieldValue structure.
3. Fill in the OVwFieldValue structure, setting the string_val entry to
the name.
4. Allocate an OVwFieldBinding structure and set the field ID and a
pointer to the field value.
5. Call OVwDbCreateObject().
As a convenience, the OVw API provides two routines that create objects
by IP Hostname or Selection Name. They require only a single call, and
they have the following function prototypes:
OVwObjectId OVwDbCreateObjectByHostname(char *hostname);
OVwObjectId OVwDbCreateObjectBySelectionName(char
*selectionName);
These routines are a convenient alternative to using the generic

OVwDbCreateObject() routine.
182
Chapter 5

Getting/Setting Object Field Values

After creating fields and objects, you can use the remaining OVw object
database routines to manipulate the fields in a wide variety of ways. The
OVw API object database routines described in this section let you
get and set field values in the OVw database
associate new fields with existing objects
retrieve a list of all the fields associated with an object
retrieve the list of capability or name fields set for an object
get all objects in the object database that contain specific field values
convert between any field name and object ID.
Basic Field Value Get/Set Calls

Using the basic routines presented in this section, you can access all field
and object information in the OVW object database. As youll see later,
many convenience versions of these basic calls are also available. The
convenience versions are easier to use since they reduce the number of
parameters or simplify the result returned. In some cases, they can
reduce the number of calls you need to make to get field information. The
convenience versions do not, however, perform actions that could not be
performed using the basic calls.
The most basic way to retrieve field value information is with the
OVwDbGetFieldValue() routine. Given a field ID and object ID, this
routine returns a pointer to a field value structure. The
OVwDbGetFieldValue() routine has the following function prototype
OVwFieldValue *OVwDbGetFieldValue(OVwObjectId objectId,
OVwFieldId fieldId);
Since the memory used to store the returned field value is allocated by
OVW, you should free the memory when no longer needed. This is done
by calling the OVwDbFreeFieldValue() routine.
The following example shows how to retrieve the selection name field
value from the OVW object database. This example converts the field
name to a field ID, then calls OVwDbGetFieldValue() to retrieve the
field value information.
Chapter 5
183

OVwObjectId obj_id;
OVwFieldValue *val_ptr;
...
field_id = OVwDbFieldNameToFieldId(ovwNselectionName);
/*Get the field value.Assume that obj_id is set for our
object.*/
val_ptr = OVwDbGetFieldValue(obj_id, field_id);
printf("The Selection Name for this object is %s\n",
val_ptr->un.string_val);
OVwDbFreeFieldValue(val_ptr);
...
Note that the ovwNselectionName OVW string constant is passed in the

call to OVwDbFieldNameToFieldId(). This constant is easier to use than
specifying "Selection Name and is less prone to programming error. The
file \OpenView\include\OV\ovw_string.h (Windows NT operating
system) or $OV_HEADER/OV/ovw_string.h (UNIX systems) contains
string constant definitions. ovw_string.h is included for you
automatically when you include \OpenView\include\OV\ovw.h
(Windows NT operating system) or $OV_HEADER/OV/ovw.h (UNIX
systems).
Setting Field Values
The OVwDbSetFieldValue() routine is used to set field values as well as
to add fields to existing objects. It has the following function prototype:
int OVwDbSetFieldValue(OVwObjectId objectId, OVwFieldId
fieldId,OVwFieldValue *fieldValue);
To set a field value, you must allocate memory for an OVwFieldValue

data structure, set the appropriate entries, and call the
OVwDbSetFieldValue() routine. This technique was shown earlier in
the section that described how to create an object.
If you attempt to set a field value for a field that is not already associated
to the object, OVW will add the field to the object for you. Note that the
OVwDbCreateObject() routine is used to set a single field value and to
create an object. The OVwDbSetFieldValue() routine is used to add
other fields to the object and set their values.
Other Ways to Get and Set Single Field Values

Since retrieving and setting individual field values are common
184
Chapter 5

operations, the OVw API provides convenience routines that simplify
these tasks. Some OVw API convenience routines retrieve particular
field values directly, bypassing the overhead of using the OVwFieldValue
data structure upon return. Examples include
OVwDbGetFieldIntegerValue() and OVwDbGetFieldBooleanValue().
To use these routines, you must know the data type of the field you are
interested in.
Other convenience routines eliminate the need to set up an
OVwFieldValue data structure. The desired value is simply passed as an
argument to the appropriate routine. Examples of these types of routines
include OVwDbSetFieldStringValue() and OVwDbSetSelectionName().
The convenience routines are straightforward and easy to use. See the
reference pages for more details on these calls.
Getting All Fields Associated with an Object

The OVw API also provides routines that can return a list containing
multiple fields, each of which may have different types. The
OVwDbGetFieldValues() routine, for instance, returns a list of all field
values for fields associated with an object. Since it returns all the fields
of an object, OVwDbGetFieldValues() essentially returns the full
definition of a particular object.
Representing lists of fields of different types requires a new data
structure. The OVwFieldBindList data structure performs this function.
It has the form
typedef struct {
int count;
OVwFieldBinding *fields;
} OVwFieldBindList;
This structure follows the list scheme used by other OVw list data
structures. The fields pointer points to the first entry in a contiguous
array of count data structures (in this case, OVwFieldBinding data
structures).
Chapter 5
185

Figure 5-2
Field Binding List Data Structures
OVwFieldValue
OVwFieldBindList
count
FieldBinding
OVwFieldBinding
isList
field_type
union {
int
boolean
string val
enum_val
list_val
field_id
field_val
}
modified
field_id
field_val
isList
field_type
union {
int
boolean
string val
enum_val
list_val
...
field_id
field_val
}
modified
isList
field_type
union {
int
boolean
string val
enum_val
list_val
}
modified
The following example shows how the OVwFieldBindList data structure

is used. For convenience, well assume that each field is a simple type,
not a list of simple types.
OVwFieldBindList *fbl_ptr;
OVwFieldBinding *fb_ptr;
OVwObjectId obj_id;
186
Chapter 5

int i;
...
/* assume that obj_id is the object ID for our object */
fbl_ptr = OVwDbGetFieldValues(obj_id);
for (i=0,fb_ptr=fbl_ptr->fields; i<fbl_ptr->count: i++,
fb_ptr++{
printf("Processing field binding entry %d\n", i);
printf("The field ID is %d\n", fb_ptr->field_id);
switch (fb_ptr->field_val->field_type) {
case ovwStringField:
printf("String value is %s\n",
fb_ptr->field_val->un.string_val);
break;
case ovwIntField:
printf("Integer value is %d\n",
fb_ptr->field_val->un.int_val);
break;
case ovwBooleanField:
printf("Boolean value is %s\n",
fb_ptr->field_val->un.bool_val);
break;
case ovwEnumField:
printf("Enum value is %s\n",
fb_ptr->field_val->un.enum_val);
break;
}
}
OVwDbFreeFieldBindList(fbl_ptr);
...
Convenience Routines
The OVw API provides many convenience routines that, in some
situations, are easier to use than the basic calls. These convenience
routines depend on data structures and concepts presented in this
Chapter 5
187

chapter. The following table lists some of the OVw API object database
convenience routines.
Table 5-1
Routine
OVwDbGetFieldIntegerValue()
OVwDbGetFieldBooleanValue()
OVwDbGetFieldStringValue()
OVwDbGetFieldEnumByValue()
Purpose
These routines take an object ID and field ID as
arguments and return the appropriate field value.
They save you the trouble of having to dereference pointers into the OVwFieldValue
structure.
OVwDbGetFieldEnumByName()
OVwDbSetFieldIntegerValue()
OVwDbSetFieldBooleanValue()
OVwDbSetFieldStringValue()
OVwDbSetFieldEnumByValue()
These routines take an object ID, field ID, and

value as arguments and set the appropriate field
value. You do not need to set up the
OVwFieldValue structure yourself if you use
these routines.
OVwDbSetFieldEnumByName()
OVwDbSetSelectionName()
OVwDbSetHostname()
OVwDbGetCapabilityFieldValues()
OVwDbGetNameFieldValues()
These routines take an object ID and a string and

then set the appropriate name field.
These routines return a list of name or capability
fields set for the object.
OVwDbNameToObjectId()
This routine converts the value of any name field

to the object ID it identifies.
OVwDbSelectionNameToObjectId()
These routines translate between selection

name/object ID and hostname/object ID.
OVwDbObjectIdToSelectionName()
OVwDbHostnameToObjectId()
OVwDbObjectIdToHostname()
OVwDbListObjectsByFieldValue()
OVwDbListObjectsByFieldValues()
OVwDbFreeObjectIdList()
188
The Locate calls search the entire OVW object

database for objects/fields that match certain
criteria. They are slow, since the entire database is
searched.
Chapter 5

Table 5-1
Routine
OVwDbGetFieldValuesByObjects()
OVwDbFreeObjectFieldList()
Purpose
These routines get a list of values for a certain
field for a list of objects.
These routines are not described here since their use is straightforward
once the basic calls are understood. See the reference pages if you want
more information on these routines.
Chapter 5
189

Deleting Objects
Deleting Objects
Objects should be deleted from the OVW object database when they are
no longer needed. OVWs process for deleting an object addresses the
possibility that the object might still be used by another application. The
OVw API provides a set of routines that applications can call to
cooperatively delete an object. This process guarantees that an object is
not deleted while still being used by another application.
The Steps for Deleting an Object

When an application is finished using an object, the application should
1. Call OVwDbUnsetFieldValue() for every field that it controls or sets.
The OVwDbUnsetFieldValue() routine has the function prototype:
int OVwDbUnsetFieldValue(OVwObjectId objectId, OVwFieldId
fieldId);
2. Call OVwDbDeleteObject() to delete the object. The

OVwDbDeleteObject() routine has the function prototype:
int OVwDbDeleteObject(OVwObjectId *objId);
OVW will delete the object if either

no fields are set for the object, or
the object only has fields with either the capability or general flag
set.
If either of these conditions are true, OVW will delete the object. If any
application has fields set for the object, the object will not be deleted
until that application unsets its field values and calls
OVwDbDeleteObject().
See the OVwDbUnsetFieldValue(3) and OVwDbDeleteObject(3) reference
pages if you need more information about deleting objects.
Determining when to Delete Objects

The previous text describes how to delete objects, but it does not describe
when to delete objects. Put simply, an object should be deleted when it is
deleted from the last map on which it appears. Applications can
190
Chapter 5

Deleting Objects
determine that an object is no longer in use by registering for the
ovwConfirmDeleteObjects event. Chapter 8 , Map Editing and Map
Events, describes map editing and map events in detail. The
OVwConfirmDeleteObjectsCB(3) reference page also describes when to
delete objects.
Chapter 5
191

Summary
Summary
This chapter described how to use the OVw object database routines to
create fields and objects in the OVW object database.
Fields are object attributes. Fields are created using either the field
registration file or the OVwDbCreateField() OVw API routine. Objects
are created with the OVwDbCreateObject() routine or one of its
convenience versions. When objects are created, a value is assigned to a
single field and, if necessary, a selection name is assigned. The
OVwDbGetUniqObjectName() routine generates values for name fields
that are guaranteed to be unique.
The OVw API data structures used for object manipulation were
presented. The OVwFieldValue data structure contains either a single
value or a pointer to a list of values. Lists are implemented using
pointers to contiguous areas of memory containing the list items. Lists
within a field value must contain objects of the same type. The
OVwFieldBindList data structure is used to create lists of field values.
A variety of OVw API convenience routines are available and are based
on their basic counterparts. They ease your programming task by
incorporating the actions of multiple calls into a single call or by
reducing the number of data structures you must use.
Applications delete objects through a two-step process. Applications first
unset each field that they control, then applications call an OVw API
routine to delete the object. OVW removes the object from the OVW
object database only if the object is no longer in active use by any
application.
192
Chapter 5
Creating and Using Submaps
193
This chapter covers maps and submaps in HP OpenView Windows. This

chapter explains how to work with maps, how to create and manipulate
submaps, and how to change the background of submaps.
map and submap concepts
creating submaps
getting map and submap information
opening and closing maps
using submap background graphics
integrating your application with an existing map application.
194
Chapter 6

Map and Submap Concepts

This section briefly discusses the relationship between maps and
submaps.
Maps
A map is a collection of OVW objects and their relationships. Users dont
view maps directly they view windows called submaps that display a
subset of map information.
Users, not applications, create maps. Users can create several maps, and
they can also control which applications operate on the various maps.
Whereas users create maps and define their scope, applications
dynamically update maps to reflect the state of the management
environment.
Among all the maps that might exist, users can select one map to be the
open map. The open map is the only map that can be updated. If
updates are needed for other maps, the updates are made at the time the
map is opened. Only one map can be open at a time in any given OVW
session.
Different users can open the same map through different OVW sessions.
The first user that opens a map is given read/write privileges on the map.
Users and applications can freely update and modify a map that has
read-write permissions. Subsequent users who open the map are given
read-only privileges on the map. Read-only maps are intended for
viewing purposes only and cannot be updated by users or applications.
Changes made to the read-write display of the map are not immediately
reflected on any read-only display. (Using the Refresh Map menu item, a
user can request that their read-only display be updated to reflect the
latest information.) There is, however, one exception to this policy of not
updating read-only displays, and it relates to status updates.
Applications can set status on a map that is opened with read-only
permissions. The status is not saved with the map, but it does allow for
timely status updates that mirror the read-write map.
Submaps
A submap is a collection of related symbols that are displayed in a single
Chapter 6
195

graphical window. Submaps essentially provide a view into the map
object space. Each submap displays a different perspective of the
information in the map, with the submaps typically organized in a
hierarchical fashion.
OVW provides a rich set of symbol types for applications to use in
submaps. An OVW symbol can represent any one of a variety of entities
on the network, from a network interface to a computer to an entire
network. Symbols are described in detail in the next chapter.
The most common method users employ to navigate through submaps is
double-clicking the mouse on special symbols called explodable
symbols. Double-clicking on an explodable symbol will cause a submap
to be displayed, if one exists. The submap contains additional symbols
that describe, in more detail, the object associated with the explodable
symbol. The object associated with the explodable symbol is called the
parent object. The submap that is displayed by double clicking on the
symbol associated with the parent object is called a child submap. The
child submap shows all the objects contained within the parent object.
The submap on which the parent object is represented is called the
parent submap. Since several submaps may contain symbols that
explode into the same submap, a submap may have several parent
submaps.
For example, consider a submap that contains a single symbol that
represents an entire organization. From this high-level view, a user could
double-click on the symbol to display a child submap that contains a view
of the network map, from the perspective of a particular location. From
there, the user could select a specific department, followed by the
selection of a specific node. Each of these submaps graphically displays a
different map perspective.
Submap Context
Submap context provides a way for application developers to describe the
intended use for the submap. This context is then used to selectively add
and remove menu items for the submap. Thus, the menus remain
uncluttered and applicable to the particular submap view.
A developer can assign context identifiers to a submap to describe the
capabilities of the submap and to determine the menu items in the
submap menu bar. Thus, applications dynamically determine a submaps
context when the submap is created. A child submap inherits the context
196
Chapter 6

of its parent. End users can add and remove context identifiers for a
submap through the Submap Description and New Submap dialog boxes.
When a developer uses the application registration files to customize a
menu, the developer defines a menu placement rule that specifies the
contexts in which the menu item can be placed. When a submap is
opened, the full list of possible menu items is checked. If a menu items
placement rule evaluates as true for the given submaps context, it is
added to that submaps menus.
A developer may define a submap context that blocks other applications
from adding any menu items to the submap. Such a submap is
exclusive, and no other application can change its context.
Refer to HP OpenView Application Style Guide for the design guidelines
for defining context identifiers.
Special Submaps
Before you can create a hierarchy of submaps, one special submap must
be chosen as the navigation entry point. In OVW, this submap is called
the root submap. HP OpenView Windows automatically creates a
single root submap for every map. The root submap represents the
highest, most abstract view of the map. You cannot delete a root submap.
HP OpenView Windows lets users configure, or customize, which submap
they want to see when a map is opened. Rather than seeing the root
submap, users can specify that they want to see a particular submap.
This is called the home submap. Selection of the home submap is done
entirely through the OVW user interface. Applications do not need to
know which submap is the home submap, nor is there any mechanism
for programmatically determining the home submap for a map.
Though most submaps are based on an object hierarchy, you can
programmatically create a submap that is not related to a parent object.
These types of submaps are called orphaned submaps. Orphaned
submaps have limited value. The main drawback to using orphaned
submaps is that users cannot easily locate and display them through
objects on the map. (Users can, however, display orphaned submaps
through a submap list box accessible through the main menu bar). In
general, you should not create orphaned submaps.
Meta-connection submaps are submaps that OVW automatically
creates to represent multiple connections between symbols. When a first
connection is made between two symbols, the connection is treated as a
simple connection. If additional connections are made between the
Chapter 6
197

symbols, OVW automatically creates a submap, called a meta-connection
submap, that contains the multiple connection symbols. Users can view
the meta- connection submap to see all connections between symbols.
Developers cannot add connections directly to the meta-connection
submap. Rather, connections are made between the symbols, and OVW
automatically adds the new connections to the meta-connection submap.
Symbol Status and Submaps

Each symbol on a submap has some form of status associated with it.
Status is discussed at length in Chapter 7 , Creating and Using
Symbols, but one form of status is worth mentioning here compound
status.
In HP OpenView Windows, a parent object may be represented in more
detail by a child submap. The child submap contains an expanded view of
the parent object. For example, by double-clicking on a computer node
symbol, a user might see a submap that contains an expanded view of
the node. The submap could contain symbols representing the file
system, interface cards, and system throughput. Each of these
lower-level components may have a specific status value. The status
values of these components can be summarized and represented by a
single status value in the parent object. In OVW, this transmission of
status values from underlying objects to the parent object is called
compound status propagation.
For the most part, applications do not need to understand the algorithms
OVW employs to propagate compound status. For one reason, the
algorithms are configurable. Users can fine-tune the status propagation
algorithms to their liking. Managing Your Networks describes compound
status propagation in more detail.
Relationship Between Maps and Submaps

The following diagram illustrates the relationship between maps,
submaps, and symbols.
198
Chapter 6

Figure 6-1
Relationship between Maps and Submaps
MAP
SUBMAP 1
SUBMAP 2
...
SUBMAP n
ROOT SUBMAP
SUBMAP 2
SYMBOL
SYMBOLS
SUBMAP 3
SYMBOLS
SUBMAP 3a
SUBMAP 3b
SYMBOLS
In Figure 6-1, submap 1 is the root submap for the map. Submaps 3A
and 3B are child submaps of the objects whose symbols appear in
submap 3. Submap 2 is an orphaned submap. Each submap contains
symbols that represent objects on the map. The map is a collection of
Chapter 6
199

objects and their relationships, and submaps are the vehicle by which
this map information is displayed.
Submap Layout Algorithms

When you create a submap, you also define the default algorithm used to
place symbols on the submap. Layout algorithms are fixed for the life of
the submap.
Submaps can use any one of seven layout algorithms:
Table 6-1
Layout Algorithms for Submaps
Algorithm
Purpose
No Layout
Use for unrelated objects or objects whose only relationship is having the same
parent object. You can also use this layout algorithm for applications that need to
specify the exact placement of symbols (e.g., when using background graphics).
Point to Point
Use for point-to-point network connections, showing logical relationships between

objects. This layout algorithm is also applicable for submaps whose objects have
multiple arbitrary connections.
Bus
Use for network connections on a bus segment or for showing multiple objects that
tie into a common relationship.
Star
Use for network connections on a star segment or for showing multiple objects
connected into a common master or hub object.
Ring
Use for network connections on a ring segment or for showing multiple objects
with equal connectivity between all objects.
Row/Column
Use for submaps of unrelated objects, or objects whose only relationship is having
the same parent object. This layout algorithm is preferred over no layout algorithm
as it provides order for the user.
Multiple
Connections
Use for submaps that primarily contain a set of connections between two objects
(e.g., the logical channels of a physical link).
OVW uses the submap layout algorithm to automatically determine
symbol placement within the submap. Though automatic placement is
adequate for most applications, you can override the default symbol
layout algorithm and place symbols at particular locations in the
submap. This feature is described in Chapter 7 , Creating and Using
Symbols.
200
Chapter 6

Submap Planes
When users look at a submap, they see a graphical window containing
symbols, connections between the symbols, and, optionally, a special
window background. But in fact, submaps are actually composed of three
separate planes that are superimposed on one another. OVW manages
the graphical information maintained in these planes. The three planes
are:
a background plane, which contains either a solid color or a
user/developer supplied graphical image
an application plane, where applications add symbols
a user plane, where users add symbols.
The background plane is fairly straightforward. Applications can select
an image to serve as a backdrop for the submap. The image resides in the
background plane. If the background plane is empty, OVW displays a
solid color.
Symbols added by applications go on the submap application plane. The
presence of a symbol on the application plane indicates that the
underlying object has semantic meaning to the application.
Symbols added by users go on the user plane, at least initially.
Applications can request notification whenever a user adds a symbol to
the user plane. If the application judges that the symbol is appropriate
for that submap, then the application can move the symbol from the user
plane to the application plane, where it will be managed by the
application. Applications should not normally add, modify, or delete
symbols on the user plane, although the OVw API permits this.
Chapter 8 , Map Editing and Map Events, explains how applications
can determine when symbols or connections are added to submaps. See
that chapter if your application needs to determine when icon or
connection symbols are added to submaps.
Shared vs. Exclusive Submaps

When applications create submaps, they can specify whether the submap
is a shared or an exclusive submap. A shared submap is one in which
multiple applications use the same application plane. Any application
can add, modify, or delete a symbol in a shared submap. Further, any
application can delete a shared submap.
Chapter 6
201

An exclusive submap is submap that can be modified only by the
creating application and the end user. Only the creating application can
add, delete, or modify symbols on the application plane of the submap.
Users can add symbols only to the user plane of an exclusive submap.
Further, only applications can create exclusive submaps. Submaps
created by users through the OVW interface are created as shared
submaps.
In general, HP recommends using shared submaps whenever possible.
See the HP OpenView Application Style Guide for more guidance on
when to use shared versus exclusive submaps.
Persistent vs. Transient Submaps

A submap is, by default, considered persistent on NNM on UNIX
systems. On NNM on the Windows NT operating system, a submap is
transient by default. A persistent submap exists in the map database
permanently, until the user or an application decides to delete it. Most
applications create persistent submaps on the map. In previous releases
(earlier than 4.1), all submaps were persistent.
An application may have a large number, perhaps thousands, of submaps
and symbols to present in the map. Creating thousands of submaps and
symbols in the map presents a problem of scalability; the bigger the map,
the bigger the OVW process becomes and the less manageable the map
becomes.
Such an application should consider creating submaps only when
necessary (for example, when the user explodes a symbol on a submap)
and should consider creating its submaps marked as transient
submaps. A transient submap is a submap that exists only when
necessary when a user is viewing the transient submap and/or when
the transient submap is a parent of a persistent submap. Applications
that create transient submaps are considered transient submap
applications.
Transient submaps are useful for maintaining a reasonable size for the
map database. Transient submaps are created upon user request and are
removed from the map as soon as it becomes clear they are no longer
needed. For example, if an application creates a transient submap in
response to a user double-clicking on a symbol, that submap and its
contents will be removed from the map as soon as the user closes it, thus
keeping the map a manageable size.
It is also important to understand that users may open a transient
202
Chapter 6

submap on a read-only map. To handle this case, applications are
permitted to create and populate transient submaps on a read-only map,
but only between the notification of the ovwUserSubmapCreate event and
the OVwAckUserSubmapCreate() acknowledgment.
A transient submap remains transient until one of the following events
occurs:
The user performs an edit operation on the submap. An example of
this is the user changing a symbol label or disabling auto-layout.
Another application performs an edit operation on the transient
submap; for example, an application adds a symbol to the transient
submap.
The application that created the submap clears the submaps
transient flag (via OVwModifySubmap()).
In such cases, the transient flag is cleared for the submap, applications
are notified of the change, and the submap is henceforth considered
persistent.
If you choose to create transient submaps, you must supply locate
information to OVW. Details on supplying locate information are covered
in Participating in Map Locates In Transient Map Applications on
page 309.
Submap Presentation
The presentation of submaps in an OVW session is determined by two
features: submap overlay and submap geometry. When submap
overlay is on, the content in a parent submap window is overlaid when
its child submap is accessed. Alternatively a user can choose to display a
new submap window for each child submap. Submap overlay allows
users to browse through a submap hierarchy without having to explicitly
close unwanted submaps.
Submap geometry is the size and location of submap windows on the
display. Users can use the submap geometry features to construct
workspaces by arranging frequently-used windows in known locations.
Developers can change the default state of overlay and geometry. Refer to
Setting Submap Overlay on page 215 and Setting Submap Geometry
on page 216 for a description of the relevant APIs and data structures.
Chapter 6
203

NOTE
When several applications are integrated into HP OpenView, divergent

implementation of the features described in this section have the
potential to cause usability problems for users. To eliminate potential
usability problems, follow the implementation guidelines in the HP
OpenView Application Style Guide.
Submap Overlay
The behavior for submap overlay is based on how a submap is accessed.
When a user accesses a submap directly by double-clicking on a parent
symbol in a submap or by selecting root, parent, home or navigator from
the menus or the tool bar, the parent submap is overlaid by the child
submap.
Alternatively, when a user accesses a submap indirectly as a result of the
locate functionality or by selecting a submap from the Submap List
dialog, the new submap is redisplayed in the last location where it was
displayed or, if it has never been displayed or is transient, it is displayed
in a default location.
When a map is first open, all submaps, except the navigator submap, are
set to have overlay On. Users can turn submap overlay off or on for a
submap using the View->Submap Overlay menu items. For read/write
maps, this setting does not change until the user specifically changes the
value again. It is retained across submap closings for persistent submaps
and across sessions.
Submap Geometry
Users can also affect submap presentation by saving the
geometrysize and locationof a submap. A user who moves a submap
or resizes the submap window can save the new geometry using the
View->Window Geometry menu item. Geometry is saved only when an
operator uses View->Window Geometry-> Save For This Submap to
explicitly save it.
Typically, Window Geometry menu items force a submap to be open at
the same size and location as it was when the Window Geometry menu
items were selected; however, if the position and size specified for a
window is inappropriate for the current display screen, the window
manager determines where the window is placed.
204
Chapter 6

Note that when the geometry for a transient submap is saved, the
submap becomes persistent.
Also note that the maximize state of the window is not a part of submap
geometry and will not be saved.
Chapter 6
205

Creating Submaps
Creating Submaps
As already described, submaps are the means by which users view
network and system management objects. From a programming point of
view, the creation of a submap and the display of a submap are actually
two separate operations. Applications can create submaps at any time
and have them available to service a user need. Users control when the
submap is displayed by some interaction with OVW, such as selection of
a menu item or double-clicking on an explodable symbol.
Creating a Submap
You can programmatically create submaps using the
OVwCreateSubmap() OVw API routine. OVwCreateSubmap() creates a
submap on the open map. It has the function prototype
OVwSubmapId OVwCreateSubmap(OVwMapInfo *mapInfo,
OVwObjectId parentObject,int submapPolicy,
int submapType, char *submapName,
int layout,unsigned int flags);
When calling OVwCreateSubmap(), you need to supply the following

arguments
mapInfo points to an OVwMapInfo data structure that contains
information about the map. Applications can retrieve map
information in the OVwMapInfo data structure in two ways.
Applications can call the OVwGetMapInfo() routine, or applications
can save the map information that accompanies a map open event.
Later sections will describe how to handle map open events and how
to manipulate fields in the OVwMapInfo data structure. To create
submaps, though, you can simply pass in the data structure returned
by the OVwGetMapInfo() routine or supplied with the map open
event. An example will show how to use the OVwGetMapInfo()
routine when creating submaps.
parentObject is the object ID of the parent object that this submap
will represent. You can also specify ovwNullObjectId, which means
that this submap does not have a parent object. This is known as an
orphaned submap.
submapPolicy indicates whether this submap will be shared by other
applications or if it will be owned exclusively by this application. The
206
Chapter 6

Creating Submaps
possible values are ovwSharedSubmap and ovwExclusiveSubmap.
Shared and exclusive submaps were described earlier in this chapter.
submapType is an application-defined field that applications can use
to classify submaps. Applications may use this field however they
wish. If your application does not use a particular submap type, use
the special value ovwNoSubmapType.
submapName specifies the name of the submap. This name appears in
the submap title bar. You should keep the name short, and the first
letter of each word in the name should be capitalized.
layout specifies the automatic layout algorithm that controls symbol
placement on the submap. Valid values are ovwNoLayout,
ovwPointToPointLayout, ovwBusLayout, ovwStarLayout,
ovwRingLayout, ovwRowColumnLayout, and
ovwMultipleConnLayout.
flags may be either ovwNoSubmapFlags, ovwDisableAutoLayout, or
ovwTransientSubmap. ovwDisableAutoLayout initially disables
automatic layout for the submap, but this setting can be changed by
the user. ovwTransientSubmap marks the submap as being transient.
OVwCreateSubmap() checks the input arguments and, if all arguments
are valid, creates the submap. It returns a submap ID that uniquely
identifies the submap within the map. The submap ID is used in future
calls involving the submap, such as adding symbols to the submap or
deleting the submap.
The following example shows how to use OVwCreateSubmap() to create a
shared submap. The submap has a bus symbol layout algorithm.
(Assume that the object ID of the parent object is already known.)
#include <OV/ovw.h>
...
OVwSubmapId sub_id;
OVwObjectId obj_id;
OVwMapInfo *mapInfo;
/* assume obj_id is set to the ID of the parent object */
mapInfo = OVwGetMapInfo();
sub_id = OVwCreateSubmap(mapInfo, obj_id, ovwSharedSubmap, 0,
"Administer: System Mgmt", ovwBusLayout, ovwNoSubmapFlags);
if (OVwIsIdNull(sub_id)) {
Chapter 6
207

Creating Submaps
}
...
At this point, the submap has been created and is internally known by
OVW. No symbols have yet been placed on the submap, and the submap
has not been displayed to the user.
NOTE
Refer to the HP OpenView Application Style Guide for guidance on

creating submaps. Many of the arguments to the OVwCreateSubmap()
are associated in some way with application style.
Setting Submap Context

An application sets submap context by assigning a list of context
identifiers to the submap via the OVw API call OVwAddSubmapContext().
Context identifiers are symbol definitions, not values.
To protect a submap from revision by other developers you can set an
exclusive submap flag via the OVw API call OVwCreateSubmap(). When
the exclusive submap flag is set, no other applications may change the
submaps context. When the exclusive submap flag is unset, other
applications may add non-generic context identifiers to the submap but
may not delete any context identifiers from the submaps context.
An application changes the submap context with the OVw API calls
OVwAddSubmapContext() and OVwRemoveSubmapContext(). Context can
also be set via the OvwModifySubmaps() call.
Displaying a Submap
There are two ways for submaps to be displayed, depending on how users
interact with OVW:
If the user performs any of the following steps, OVW automatically
displays the submap:
The user double-clicks the mouse on an explodable symbol.
The user selects a submap through the OVW submap list box.
The user selects the open operation on a symbols pop-up menu.
If the user performs one of these steps and the submap does not
already exist, OVW will notify the user of this and prompt for
208
Chapter 6

Creating Submaps
additional information needed to create the child submap. OVW will
then display the submap. The application does not need to issue a call
to the OVw API to display the submap.
If a user requests an application action through an OVW menu item,
the application must explicitly inform OVW when the submap should
be displayed. For example, the user might be able to invoke an
application-supplied action to create a submap. The submap might
use the object selection list as a form of input. The application is
responsible for explicitly telling OVW to display the submap.
To display a submap window, use the OVwDisplaySubmap() OVw API
routine. The OVwDisplaySubmap() routine has the function prototype
int OVwDisplaySubmap(OVwMapInfo *mapInfo, OVwSubmapId
submapId);
Given a submap ID, this routine does one of two things:

If the submap is not already displayed, it displays the submap
window.
If the submap window is already displayed, it raises the window to
the top.
Choosing When to Create a Submap

One of the important decisions you need to make as an OVW application
developer is determining when to create submaps. Applications that are
driven entirely by user requests (e.g., menu item selection) may need to
wait until the user selection has occurred before the submap can be
created. Other applications that are driven by network or system events
(for example, LAN monitoring applications) should create submaps as
soon as possible.
In general, applications should create submaps as soon as they know
that the submaps are needed (for example, when a new node or network
is discovered). There are several advantages to creating submaps in this
way:
The map is always up to date and is a complete representation of the
management environment.
Users do not incur unnecessary delays when they display submaps.
Status information is current for symbols with compound status
source.
Chapter 6
209

Creating Submaps
Submap information is present in the event that a user saves a map
snapshot.
Conversely, applications that will be creating large numbers of submaps
should consider creating transient submaps on demand, to minimize the
overall size of the map database.
Organizing your Submap Hierarchy

By default, HP OpenView Windows automatically displays the root
submap when a map is opened. (Users can, however, set another submap
as the home submap.) If your application creates submaps, tie the
submaps into an existing map hierarchy through one of two methods:
You can create a submap hierarchy within your application and place
a symbol representing a top-level object in the root submap. The
symbol in the root submap provides an entry point into the
applications hierarchy.
You can create a child submap for an object in an existing submap
hierarchy. If you want to add a child submap to an existing submap
hierarchy but a prospective parent object is not already defined, you
can add a parent object to a submap in the existing hierarchy.
You should create a child submap of an existing object only if, from
the users point of view, it provides a meaningful extension to the
existing hierarchy. For example, the submap of a computer system
that displays the components in a computer system (software,
peripherals, interface cards, etc.) is a good candidate for a child
submap.
Further discussion of submap hierarchies appear in the HP OpenView
Application Style Guide.
Closing a Submap
There are several ways for submaps to be closed, depending on how users
interact with OVW.
If the user performs any of the following steps, OVW automatically closes
the submap; the application does not need to issue a call to the OVw API
to close the submap:
The user double-clicks the window menu button.
The user selects Map->Close Submap.
210
Chapter 6

Creating Submaps
The user clicks on the close icon in the tool bar.
However, when an application does need to close a submap, use the
OVwCloseSubmap() OVw API routine which has the function prototype:
int OVwCloseSubmap(OVwMapInfo *mapInfo, OVwSubmapId submapId);
Given a submap ID, this routine does one of two things:

If the submap is not already closed, it closes the submap window.
If the submap window is not found or if the map is not open an error
is returned.
Chapter 6
211

Loading and Unloading Submaps

NNM allows applications to programmatically load or unload a submap.
This provides a convenient way to load a transient submap into memory.
The submap may also be displayed when it is loaded. OVW maintains a
reference count of the number of user and programmatic requests to load
or unload a transient submap. Each load request increments the
reference count. Each unload request decrements the reference count.
When the reference count reaches 0, OVW unloads the submap
information and, if necessary, closes the submap display.
In general, loading and unloading submaps programmatically is
independent of users opening and closing submaps. Usually when users
open and close submaps the reference count is not affected. When
loading/unloading submaps by application interferes with
opening/closing submaps by users, the user actions take precedence. For
example:
When an application loads the submap that is already open by the
user, the reference count is incremented. When this application
unloads the submap the reference count is decremented but the
submap is not closed until the user closes it.
When the user closes the submap that was loaded/opened by the
application, then the reference count is not decremented until the
application calls the unload submap function.
The OVwLoadSubmap() routine causes OVW to load into memory the
information for the child submap of the specified symbol and to
increment the reference count. (If the requested submap is already
loaded, OVW bypasses the load request and increments the reference
count.) OVwLoadSubmap() returns the submap ID for the newly loaded
submap. The calling application can use this submap ID for adding its
own information to the submap and for unloading the submap from
memory. The function prototype for OVwLoadSubmap() is:
OVwSubmapId OVwLoadSubmap (OVwMapInfo *map, OVwSymbolId
parentID, OVwBoolean display, OVwBoolean layout);
where:
map specifies a pointer to a map structure for an open map
parentID specifies the parent symbol id of the loaded submap
212
Chapter 6

display specifies whether the newly loaded submap should be
displayed
layout specifies whether to perform a layout of the newly loaded
submap.
The OVwLoadSubmaps() routine loads multiple submaps with a single
call. The returned submap list provides the submap IDs of the loaded
submaps. The function prototype is:
OVwSubmapLoadAckList *OVwLoadSubmaps (OVwMapInfo *map,
OVwSymbolIdList *symbolList, OVwBoolean display,
OVwBoolean Layout);
The parameters display and layout apply to all of the loaded submaps.
The return value is a list of loaded submaps.
OVwLoadSubmaps() returns a pointer to an OVwSubmapLoadAckList
structure. The OVwSubmapLoadAckList data structure uses the standard
OVw API list form: it contains a integer count of the number of entries in
the list, and a pointer to the first in a contiguous array of entries.
typedef struct
int count;
OVwSubmapLoadAckInfo
} OVwSubmapLoadAckList;
*submaps;
Within this list, each OVwSubmapLoadAckInfo->acknowledgment field

indicates the success or failure of the specified submap load.
typedef struct {
OVwSymbolId symbol;
OVwSubmapId submap;
int acknowledgement;
} OVwSubmapLoadAckInfo;
OVwUnloadSubmap() unloads the specified submap and decrements the

reference count.
OVwUnloadSubmap (OVwMapInfo *map, OVwSubmapID submap);
The OVwUnloadSubmaps() routine unloads multiple submaps with a

single call. The OVwSubmapLoadAckInfo->acknowledgment fields within
the returned submap list indicates the success or failure of the submap
unloads. The OVwSubmapLoadAckInfo->symbol fields are not valid when
unloading submaps.
OVwSubmapLoadAckList *OVwUnloadSubmaps (OVwMapInfo *map,
OVwSubmapIdList *submapList);
Chapter 6
213

Changing Submap Characteristics

When you create a submap using the OVwCreateSubmap() routine, you
supply a number of arguments that define the submaps characteristics.
These characteristics include: parent object, submap layout algorithm,
submap policy, submap name, and submap type. Of these characteristics,
the submap name is the only one that can be changed after the submap
has been created. All other characteristics are fixed for the life of the
submap.
OVW provides several APIs to let you change the submap name, context,
and background graphics for individual submaps. You can also use
OVwModifySubmap() and OVwModifySubmaps() to change one or more of
the following attributes for a single submap or several submaps:
submap name
submap type
automatic layout algorithm
background graphic
addition or removal of context
drop action
submap geometry
submap overlay.
This section describes how to perform these operations.
OVwModifySubmaps() and OVwModifySubmaps() have the following
function prototypes:
int OVwModifySubmap (OVwMapInfo *mapInfo,
OVwSubmapUpdateInfo *submap)
int OVwModifySubmaps (OVwMapInfo *mapInfo,
OVwSubmapUpdateList *submaps);
When calling OVwModifySubmaps() and OVwModifySubmap(), you need

to supply these arguments:
complete map information. You can use the OVwGetMapInfo() routine
to get the map information.
214
Chapter 6

OVwSubmapUpdateInfo includes the submap parameters to be
modified.
OVwSubmapUpdateList contains a list of OVwSubmapUpdateInfo
items, describing each symbol to be updated.
Many of the characteristics defined in the ovw.h file for the submap data
structure (refer to Getting Submap Information on page 220) can be
changed using the OVwModifySubmaps() and OVwModifySubmap() APIs.
Style considerations may apply to these operations. Refer to the HP
OpenView Application Style Guide for complete guidelines on symbol
manipulation.
Changing a Submap Name

To change a submap name, use the OVwSetSubmapName() OVw API
routine. The routine has the function prototype:
int OVwSetSubmapName(OVwMapInfo *mapInfo,
OVwSubmapId submapId, char *submapName);
The arguments are straightforward. You only need to supply a pointer to

a mapInfo structure, the submap ID of the particular submap, and a
character string containing the new submap name. The name does not
have to be unique.
Setting Submap Overlay

Developers specify via OVwModifySubmap and OVwModifySubmaps
whether a submap can be overlaid by another submap. If a submap
cannot be overlaid, then submaps opened from that submap will create a
new window on the display. By default a submap can be overlaid. Refer
to Submap Presentation on page 203 for a description of the end-user
functionality and to the HP OpenView Application Style Guide for
implementation guidelines.
The update flag is:
ovwUpdateSubmapOverlay
The field in the OVwSubmapInfo structure is:

submap_overlay
Chapter 6
215

Setting Submap Geometry

An application sets the size and location of a submap via the
OVwModifySubmap() and OVwModifySubmaps() APIs.
Changes take effect when a submap is opened. You should close and
reopen a submap when making such a change because changes to an
open submap take effect only after the submap is closed and reopened.
If you dont want to reset the geometry each time the submap is opened,
you also need to ensure that the submap is persistent. Refer to
Persistent vs. Transient Submaps on page 202.
An applications request to change the geometry of a submap will be
denied if a user has saved a submaps geometry through the menu items.
For a read-write map, window geometry will be saved between sessions.
Read-only maps will not have geometry saved between sessions.
OVW will not return a failure even if the x and y coordinates are outside
the range of the current display screen or the width and height are larger
than the current display screen. Therefore, if the submap's geometry
indicates ranges and sizes inappropriate for a display screen, the
submap's position and size will be determined by a window manager's
window placement algorithm. As a result, the geometry of a window may
not exactly match the values in the OVwSubmapInfo structure.
The four flags to update the geometry via the OVwModifySubmap(s) API
are:
ovwUpdateSubmapWindowWidth
ovwUpdateSubmapWindowHeight
ovwUpdateSubmapWindowX
ovwUpdateSubmapWindowY
The four relevant fields in the OVwSubmapInfo structure are:

submap_window_width;
submap_window_height;
submap_window_x;
submap_window_y;
216
Chapter 6

Deleting a Submap
Deleting a Submap
The OVwDeleteSubmap() routine deletes a submap. You can delete any
submap that has the shared submap policy, or you can delete an
exclusive submap if your application created the submap. The
OVwDeleteSubmap() routine has the function prototype
int OVwDeleteSubmap(OVwMapInfo *mapInfo,
OVwSubmapId submapId);
NOTE
When you delete a submap, OVW assumes that all symbols in the
submap should be deleted as well. OVW will delete all symbols in that
submap. If a symbol is deleted that is the last symbol that represents an
underlying object, then the object will be deleted also. Also, since an
object might serve as a parent object of a child submap, deleting an object
might result in the deletion of a child submap. Deleting a submap can set
off a series of symbol, object, and submap deletions. This recursive
deletion guarantees that unneeded symbols, objects, and submaps are
removed when no longer needed. Applications should not delete submaps
created by other applications.
The OVwDeleteSubmap() routine does not delete the submaps parent

object.
Chapter 6
217

Getting Map and Submap Information

The OVw API provides a number of routines that are useful for finding
out information about the open map and its component submaps. These
routines can
tell you when a map was created or last closed
tell you how the user has configured your application for a map
return a list of all submaps within a given map
retrieve submap information
produce a list of all objects on a map.
Getting Map Information

The OVwGetMapInfo() routine retrieves information about the open
map. It returns a pointer to a data structure containing the map name,
map permissions, map creation time, the time the map was last closed,
and the submap ID of the root submap. Map information is valid until
the map is closed. The OVwGetMapInfo() routine has the function
prototype:
OVwMapInfo *OVwGetMapInfo();
It returns a pointer to the OVwMapInfo data structure, which has the

following form:
typedef struct {
char *map_name;
int permissions;
/* ovwMapReadOnly or ovwMapReadWrite
time_t creation_time;
/* map creation time
time_t last_closed_time;
/* time read-write map was last closed
OVwSubmapId root_submap_id; /* root submap for adding top-level symbols
} OVwMapInfo;
*/
*/
*/
*/
The root_submap_id field is particularly interesting, since it provides an

entry point into the submap hierarchies present for the map. Using
OVwListSymbols(), an OVw API routine that has not yet been
discussed, you can retrieve a list of all symbols present in a given
submap. Using the root_submap_id as an argument to this routine, you
can determine which symbols, and hence, which submap hierarchies, are
present in the root submap.
218
Chapter 6

Many OVw API routines take a pointer to the mapInfo data structure as
the first argument. You should use the OVwGetMapInfo() OVw API
routine to generate a mapInfo data structure. Though you could call
OVwGetMapInfo() every time you need a mapInfo structure, a more
efficient technique is to retrieve the map information once, and save it for
future use. The most logical place to do this is in a callback routine that
is registered for the ovwMapOpen event. Within that callback routine, you
can use OVwCopyMapInfo() to save the map information returned with
the ovwMapOpen event. The OVwCopyMapInfo() routine copies the
memory in an OVwMapInfo data structure.
When finished with the OVwMapInfo data structure, call
OVwFreeMapInfo() to free the memory allocated by OVW.
Getting Application Configuration Information

Users can configure the behavior of some applications through an
application configuration dialog box that appears when either a new map
is opened or the map configuration menu item is selected. User
configuration may impact the applications initialization behavior. This
section describes how applications can determine how they are
configured by the user.
Some applications present an application configuration dialog box to the
user when a new map is opened. The application configuration dialog box
is defined in an enroll block in an application registration file. The enroll
block contains entries for all configuration fields used by the application.
(The HP OpenView Application Style Guide describes how applications
should support application configuration).
Applications can retrieve the values of application configuration fields
using the OVwGetAppConfigValues() routine.
OVwGetAppConfigValues() has the following function prototype:
OVwFieldBindList *OVwGetAppConfigValues(OVwMapInfo *mapInfo,
char *appName);
OVwGetAppConfigValues() returns a pointer to a list of field values. The

OVwFieldBindList data structure was described in Chapter 5 ,
Creating and Using Objects and Fields. By following the pointers in the
field data structures, applications can determine the values of all
application configuration fields. Based on these values, the application
can determine how the user has configured the application. For example,
the user may have disabled the application, or may have enabled only
Chapter 6
219

certain parts of application functionality. The application, not OVW, is
responsible for determining how the fields are used and what the field
values mean.
When finished, call OVwFreeFieldBindList() to free the memory
allocated by the OVwGetAppConfigValues() routine.
Applications can set the application configuration fields using the
OVwSetAppConfigValues() routine. It has the function prototype:
int OVwSetAppConfigValues(OVwMapInfo *mapInfo,
OVwFieldBindList *configParams);
This routine is useful for setting the values of general fields that may
change. The default values for application configuration fields can be set
in the configuration enroll block in the application registration file. See
the reference pages if you need more information on this call.
Getting Submap Information

The OVw API provides two routines that retrieve information at the
submap level, OVwGetSubmapInfo() and OVwListSubmaps().
Using OVwGetSubmapInfo()
The OVwGetSubmapInfo() routine returns complete information about a
given submap, including the submap name, policy, and parent object ID.
It has the function prototype:
OVwSubmapInfo *OVwGetSubmapInfo(OVwMapInfo *mapInfo,
It returns a pointer to an OVwSubmapInfo data structure. The data

structure has the form:
typedef struct {
OVwSubmapId submap_id;
/* submap ID
char *submap_name;
/* submap name
int submap_policy; /* ovwSharedSubmap,
ovwExclusiveSubmap
char *app_name;
/* app that created submap; NULL == user
int submap_type;
/* application-specific submap type
OVwObjectId parent_object_id;
/* parent object of submap;
/*ovwNullObjectId if orphan submap
int layout_style;
/* automatic layout algorithm
OVwBoolean layout_on;
/* automatic layout on/off
char *bg_graphics;
/* background graphics set for submap
char **submap_context;
/* submap context identifiers
220
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
Chapter 6

unsigned int submap_flags;
/* state, mode flags
#if (OVwAPILevel > 4)
char *drop_app_name;
char *drop_action;
int submap_window_width; /* width of submap window in pixels
int submap_window_height;/*height of submap window in pixels
int submap_window_x;
/* x coordinate location of window
int submap_window_y;
/* y coordinate location of window
OVwBoolean submap_overlay;
/* submap overlay on/off
#endif
} OVwSubmapInfo;
*/
*/
*/
*/
*/
*/
When finished, call OVwFreeSubmapInfo() to free the memory allocated

by OVwGetSubmapInfo().
Using OVwListSubmaps()
The OVwListSubmaps() routine retrieves a list of submaps on the open
map. There are a variety of ways to filter which submaps are included in
the list:
You can select whether the list of submaps should include all
submaps, or only those created by a particular application.
You can filter the list of submaps to include only those submaps that
have a particular submap type. Applications define submap types
when they create submaps.
You can filter the list of submaps to include only those submaps
whose parent objects have particular field values. Field values are
defined using an OVwFieldBindList structure, which is a list of field
values. The OVwFieldBindList data structure is described in
Chapter 5 , Creating and Using Objects and Fields.
The OVwListSubmaps() routine has the following function prototype:
OVwSubmapList *OVwListSubmaps(OVwMapInfo *mapInfo,
char *appName, int submapType,
OVwFieldBindList *parentFieldValues);
The arguments to OVwListSubmaps() are used in the following way:

mapInfo is a pointer to a map information data structure.
appName if NULL, OVW will search all submaps on the open map. If
non-NULL, OVW will limit the search to submaps created by the
application with the name appName.
Chapter 6
221

submapType is a value that has meaning to the creating application.
The special value ovwAnySubmapType matches any submap type.
Submaps created by users always have a value of ovwAnySubmapType.
Submap types were described earlier in this chapter.
parentFieldValues is a pointer to an OVwFieldBindList data
structure that contains the particular field values against which
parent objects should be compared. The OVwFieldBindList data
structure is described in Chapter 5 , Creating and Using Objects and
Fields.
OVwListSubmaps() returns a pointer to an OVwSubmapList structure.
The OVwSubmapList data structure uses the standard OVw API list
form: it contains a integer count of the number of entries in the list, and
a pointer to the first in a contiguous array of entries.
The following code segment shows how to use the OVwListSubmaps()
routine. This code retrieves a list of submaps that were created by any
application and that have parent objects that have the isNode capability
field set to TRUE.
#include <OV/ovw.h>
...
OVwSubmapList *list_ptr;
int i;
OVwFieldId f_id;
OVwFieldBinding binding;
OVwFieldBindList bind_list;
OVwFieldValue field_value;
f_id = OVwDbFieldNameToFieldId("isNode");
binding.field_id = f_id;
binding.field_val = &field_value;
binding.field_val->is_list = FALSE;
binding.field_val->field_type = ovwBooleanField;
binding.field_val->field_bool_val = TRUE;
bind_list.count = 1;
bind_list.fields = &binding;
list_ptr = OVwListSubmaps(mapInfo, NULL,
ovwAnySubmapType,&bind_list);
if (! list_ptr) {
}
for (i=0; i<list_ptr->count; i++) {
printf("%s\n", list_ptr->submaps[i].submap_name);
222
Chapter 6

}
OVwFreeSubmapList(list_ptr);
...
When you are done with the data structure returned by

OVwListSubmaps(), call OVwFreeSubmapList() to free the data
structure memory allocated by OVW. OVwFreeSubmapList() has the
function prototype:
void OVwFreeSubmapList(OVwSubmapList *submapList);
Using OVwListOpenSubmaps()
This API returns the list of open submaps. This list of open submaps can
be filtered on an application name. Using this list, developers can bring
up an application to be in the same state it was when the user finished
using it. This API could be used to create a save session feature in an
application.
The signature for this API is:
OVwSubmapList *OVwListOpenSubmaps (OVwMapInfo *mapInfo,
char *appName)
The arguments to OVwListOpenSubmaps() are used in the following way:

mapInfo is a pointer to a map information data structure.
If appName is NULL, OVW will return a list of all open submaps on
the open map. If non-NULL, OVW will limit the results to a list of
opened submaps created by the application with the name appName.
OVwListOpenSubmaps() returns a pointer to an OVwSubmapList
structure. The OVwSubmapList data structure uses the standard OVw
API list form: it contains an integer count of the number of entries in the
list, and a pointer to the first in a contiguous array of entries.
When you are done with the data structure returned by
OVwListOpenSubmaps(), call OVwFreeSubmapList() to free the memory
allocated by OVW. OVwFreeSubmapList() has the function prototype:
void OVwFreeSubmapList(OVwSubmapList *submapList);
Chapter 6
223

Opening and Closing Maps

If your application modifies the map, there are certain steps that it must
perform anytime a map is opened or closed by the user. The following
sections describe how applications should respond to user requests to
open or close a map.
Processing a Map Open Request

Applications can detect a user request to open a map by registering a
callback routine for an ovwMapOpen event. Within that callback routine,
the application might need to perform these steps:
Determine what changes, if any, are allowed for the map. The main
factors in this decision are the map permissions and whether the user
has enabled the application for the new map through the application
configuration values.
Make the updates to the map as appropriate for the application. The
application can examine the time at which the map was last closed to
determine what changes need to be made to make the map current.
If a significant number of time-consuming updates need to be made,
the application can call special OVw API routines to inform the user
that a potentially lengthy map update is occurring. The process of
updating a new map is referred to as map synchronization.
Receiving Map Open Events
Applications register for the ovwMapOpen event using the
OVwAddCallback() routine. (Chapter 4 , Using the HP OpenView
Windows API, describes how to register callback routines.) The map
open callback routine has the following function prototype:
void (*OVwMapOpenCB) (void *userData, OVwEventType type,
OVwMapInfo *mapInfo, OVwFieldBindList *configParams,
OVwEventSource source);
The arguments to the callback routine are as follows:

userData is a pointer to data defined by the user when the callback
routine was registered.
type is the event (ovwMapOpen in this case).
224
Chapter 6

mapInfo is a pointer to a OVwMapInfo data structure. The
permissions field and the last_closed_time field in the
OVwMapInfo data structure are of special interest. Applications can
check the permissions to determine if all updates are allowed
(read-write permission) or only status updates are allowed (read-only
permission). The map close time is useful in determining what
changes need to be made to make the map current.
configParams is used to return application configuration values.
Applications can traverse the pointers in the OVwFieldBindList data
structure to access values for each of the application configuration
fields.
source returns an ovwEventSource value, as defined in ovw.h, which
gives a hint as to the cause of the callback.
Based on the map information and application configuration parameters,
applications can determine if updates are allowed, as well as what
updates are required to make the map current. Developers can use the
application configuration values in any way that makes sense for the
application. For example, some applications might use a Boolean
configuration field to indicate if the application is enabled or disabled for
the map. Other applications might use a numeric scheme where different
values indicate that different levels of map updates are allowed. It is the
developers responsibility to determine how the user has configured the
application and to act appropriately.
Synchronizing the Map
Anytime a new map is opened, there may be a brief period in which map
applications are updating the map to reflect changes that occurred since
the map was last used. Applications can call certain OVw API calls to
inform users that the map is being updated. Users see a message stating
that the map is being synchronized, hence the term map
synchronization.
Map Synchronization Routines The OVw API provides two routines
that inform users of map synchronization. These routines are optional
but recommended. They have the function prototypes:
int OVwBeginMapSync(OVwMapInfo *mapInfo);
int OVwEndMapSync(OVwMapInfo *mapInfo);
Call the OVwBeginMapSync() routine to mark the beginning of a

synchronization phase. Other applications may also synchronize at the
Chapter 6
225

same time. While one or more applications are synchronizing, the user
sees an appropriate message in the status line of all submap windows.
Each application should call OVwEndMapSync() to mark the end of the
synchronization phase. When the last map application completes
synchronization, the synchronizing message is removed from the user
interface. Users can then view submaps with confidence that the
information is current.
Checking for Events while Synchronizing Recall from Chapter 4 ,
Using the HP OpenView Windows API, that applications can manually
check the OVW event queue for the presence of specific events that would
justify processing interruption. Since map synchronization is potentially
a time-consuming operation, you should consider checking the event
queue for the presence of important events, such as the ovwMapClose
event. You can check the OVW event queue for the presence of a
particular event using the OVwPeekOVwEvent() routine.
Starting an Application after a Map is Opened
When OVW starts a new user session, the map is opened before the map
applications are started. Applications do not receive an ovwMapOpen
event if the map is opened before the application is started. Because of
this behavior, applications need to take special steps at startup time to
determine if the currently open map needs to be updated. These steps
include retrieving the map information (for permissions and last close
time) and the application configuration values.
If you design your map open callback routine correctly, you can use the
same routine to handle map initialization both when the application is
being started and when it is already running. You can retrieve the map
information and application configuration values, and you can invoke
your callback routine directly. This simulates the reception of an
ovwMapOpen event. In the following example, error checking has been
removed for brevity.
#include <OV/ovw.h>
void mapOpenCB(void *userData, OVwEventType type,
OVwMapInfo *mapInfo, OVwFieldBindList *config_params)
{
/* check the map permissions, last close time, and app
** configuration values to determine what map updates are
** needed */
OVwBeginMapSync(mapInfo);
226
Chapter 6

...
OVwEndMapSync(mapInfo);
}
main()
{
int ret;
char *appname;
OVwFieldBindList *bind_list;
ret = OVwInit();
ret = OVwAddCallback(ovwMapOpen, NULL, (OVwCallbackProc)
mapOpenCB, NULL);
/* Get the map information and app config values, then invoke
the callback routine */
appname = OVwGetAppName();
bind_list = OVwGetAppConfigValues(map, appname);
mapOpenCB(NULL, ovwMapOpen, map, bind_list);
/* start checking for events */
OVwMainLoop();
}
Processing a Map Close Request

When the user makes a request to close a map, OVW begins a dialog with
each application that has registered callback routines for the
ovwMapClose event. OVW provides each application with a number of
arguments, including a proposed closing time for the map. Applications
then respond back to OVW with an indication that the close request was
acknowledged. Within that acknowledgment, the application can agree
to the proposed close time, or can reply with an earlier close time. An
application can specify an earlier closing time if it is the midst of a map
update that is not yet complete.
OVW closes the map when it receives acknowledgment from all
applications registered to receive the close event. (If applications do not
respond within the configured time period, OVW assumes that the
application agrees with the proposed closing time. The acknowledgment
timer is configurable through the OVW X resource file). OVW uses the
earliest of all the returned map close times as the official map close time.
The next time the map is opened, it will reflect the earliest close time
returned by all applications. An application can then make appropriate
updates to make the map current.
Chapter 6
227

NOTE
Applications must acknowledge the map close event. OVW uses a timer
to detect unacknowledged close events, but that timer duration is
typically infinite.
The map close event callback routine and the map close acknowledgment
routines have the following function prototypes:
void (*OVwMapCloseCB) (void *userData, OVwEventType type,
OVwMapInfo *mapInfo,
time_t closing_time,
int OVwAckMapClose(OVwMapInfo *mapInfo, time_t close_time);
See the reference pages if you need more information about these calls.
228
Chapter 6

Using Submap Background Graphics

By default, OVW uses a solid color as a background for all submaps. The
background graphic for any submap can, however, be changed to contain
a bit image. The background graphic can be changed either by the end
user through the OVW user interface, or by the developer through the
OVw API.
Background graphics provide a number of useful functions. You can, for
instance, choose a more visually pleasing background with a different
pattern or color. But the most useful function, by far, is the ability to
display a graphical map of the environment being managed. You can
display a bit image of, say, a country, a state, or an office or building floor
plan. By placing symbols at coordinates relative to the background
graphic, you can provide context for submap symbols in a meaningful,
visual way.
Setting and Clearing Background Graphics

The OVw API provides two routines that let you programmatically
control the background graphics for submaps. They have the following
function prototypes
int OVwSetBackgroundGraphic(OVwMapInfo *mapInfo,
OVwSubmapId submapId, char *filename);
int OVwClearBackgroundGraphic(OVwMapInfo *mapInfo,
These routines are quite easy to use. The OVwSetBackgroundGraphic()

routine takes a particular submap ID and the full pathname of a bit
image file, and it sets the background graphic for the given submap.
OVW then scales the bit image to fit the window size.
The OVwClearBackgroundGraphic() routine restores the submap
background to the default solid color pattern.
Symbol Placement and Background Graphics

If you use a background graphic that provides some form of geographical
map (e.g., a building floor plan), then you will probably also want to place
symbols explicitly at particular locations relative to that map. For this
Chapter 6
229

behavior to work correctly, specify ovwNoLayout as the layout algorithm
when you create the submap.
Image Formats
Graphic files are quite large and may significantly increase the time
required to open each submap and significantly increase the amount of
memory required to view a submap. If the submap is transient, it
becomes persistent when you add a background graphic. Supported file
formats for background graphics are as follows:
NNM for all platforms:
GIF (CompuServe Graphics Interchange Form)
NNM for Windows NT and UNIX: Supports these graphic file formats
(not displayed when accessing NNM over the web):
BMP (Bitmap)
TIFF (Tag Image File Format
NNM for UNIX only: Supports these graphic file formats (not
displayed in NNM for Windows NT or NNM on the web):
XBM (X11 monochrome bitmap format)
PCX
Image
Starbase
XPM (X Pixmap format)
XWD (X Window Dump)
NNM for UNIX and NNM on the web only: Supports these graphic file
formats (not displayed in NNM for Windows NT):
JPEG (Joint Photographics Experts Group)
230
Chapter 6

Integrating your Application with an Existing Map Application
Integrating your Application with an Existing

Map Application
Applications that operate on maps might create objects or submaps that
have meaning to other map applications. Developers are encouraged to
leverage existing map applications to build new ones.
HPs IP Map application is a good example to follow. IP Map provides a
number of useful features that other map applications might be
interested in. IP Map automatically discovers IP nodes on a network and
adds them to a network map. Developers might leverage this existing
functionality when developing new applications.
If your application could potentially serve as an integration point for
other applications, you should provide adequate instructions for other
developers to follow to integrate their application with yours. Appendix
A , Guidelines for Documenting Map Applications, describes what
information you should provide to help other developers understand how
to integrate with your application. You can refer to the documentation
provided with the HP IP Map application for an example.
Chapter 6
231

Summary
Summary
This chapter presented important OVW map and submap concepts. It
explained how submaps are related to maps, and how submaps provide
exploded views of objects. OVW provides a number of submap layout
algorithms that applications can choose from. The three submap planes
were described. Each submap has an application, user and background
plane.
To create a submap, a developer must specify a parent object, a submap
layout algorithm, a submap policy (shared vs. exclusive), a submap type,
and a submap name. Determining the application submap hierarchy is
an important part of designing an OVW application, and this chapter
described ways for developers to structure their submap hierarchy.
Applications that will be creating large numbers of submaps should
consider creating transient submaps on demand, to minimize the overall
size of the map database.
Numerous routines that retrieve map and submap information were
described. Developers can retrieve information about the open map or
any of the submaps in the open map.
Background graphics images were explained. Developers can use OVw
API routines to programmatically set or clear submap background
graphics.
Application integration was mentioned last. Applications are encouraged
to leverage existing map applications that provide useful services. For
example, the HP IP Map application performs many functions that other
map applications might be able to build upon. Map application
integration is addressed in Appendix A , Guidelines for Documenting
Map Applications, as well as in the HP OpenView Application Style
Guide.
232
Chapter 6
Creating and Using Symbols
233
This chapter introduces the OVw API symbol routines. These routines
create, manipulate, and delete symbols in HP OpenView Windows.
You should read this chapter if your application deals with symbols in
HP OpenView Windows. You should already be familiar with
HP OpenView Windows objects, maps, and submaps, which were the
subjects of previous chapters.
234
Chapter 7

Overview
Overview
characteristics of symbols
creating symbols
changing symbol appearance and behavior
retrieving symbol information
retrieving object information.
Chapter 7
235

Characteristics of Symbols
This section reviews basic symbol concepts that you must know before
you can create and manipulate symbols.
Symbols versus Objects

The terms symbols and objects appear throughout this chapter. You must
understand the distinction between symbols and objects before you can
use the OVw API symbol routines.
Symbols are presentation elements, while objects are underlying
database elements that represent real-world objects. A symbol is a
graphical representation of an object as it appears on a submap of a
particular map. An object may be represented by multiple symbols.
As presentation elements, symbols have attributes beyond those of the
objects they represent. Important symbol attributes include:
label
status
status source
symbol type
plane location
position
behavior
presentation.
Since these attributes are symbol-specific rather than object-specific,
they can vary between the different symbols representing a particular
object.
Symbol Characteristics
Every symbol has an assortment of attributes that apply directly to the
symbol, rather than to the underlying object the symbol represents. This
section describes the concepts behind these symbol attributes.
236
Chapter 7

Symbol Label
The symbol label is a textual string that is displayed at the bottom of
each symbol. The symbol label is provided as a convenience to users.
The label does not have to be unique, as it is not used to uniquely identify
the symbol internally. (Numeric symbol IDs uniquely identify symbols.)
Applications can assign the initial value of the symbol label when the
symbol is created, but users are free to change the label to their liking.
Applications or end users can disable the display of the label.
Symbol Type
The symbol type determines the graphical representation of the symbol.
The term symbol type is a convenient way of referring to the symbol
class/subclass pair that defines how the symbol is displayed.
Symbol types can be defined with certain default capability fields. If a
symbol with default capability fields is created in a submap, those
capability fields will be added to the existing capability fields of the
underlying object.
Symbol classes, symbol subclasses, and default capability fields are
described in detail in Chapter 2 , Creating and Using Registration
Files.
Symbol Variety
OVW symbols come in two varieties: icon symbols and connection
symbols. All symbol types belong to one of these two varieties.
Icon symbols are displayed as a symbol graphic (or bitmap) within
some outer shape (circle, square, diamond, etc.). In addition to the basic
symbol attributes (label, status, status source, plane), an icon symbol has
the following additional attributes:
class shape, based on the class of the symbol type
symbol graphic (or bitmap), based on the subclass of the symbol type
position.
A connection symbol is a symbol that connects two icon symbols. A
connection symbol appears as a line drawn between two icon symbols. A
connection symbol has the following attributes beyond the basic symbol
attributes:
Chapter 7
237

line style based on the subclass of the symbol type
two connection endpoints.
A connection symbol can connect any two icon symbols on the same
submap. If the submap has a ring or bus layout, a connection symbol can
also connect an icon symbol and the backbone symbol. A connection
symbol cannot connect other connection symbols.
The variety of a symbol type is determined by its symbol class. For
example, symbol types of the Computer class are of the icon variety,
while symbol types of the Connection class are of the connection
variety.
Later, this chapter will show how to programmatically change the
symbol type of existing symbols. This is allowed, as long as the new
symbol type has the same variety as the symbol. For example, you can
change the symbol type of an icon symbol to a new icon symbol type, but
not to a connection symbol type. Symbol variety is fixed for the life of the
symbol.
Symbol Behavior
A symbol can either be explodable or executable. This characteristic
determines what will happen when the user double-clicks on the symbol.
By default, symbols added to a map are explodable in nature. That is,
double clicking on an explodable symbol results in the display of the
child submap that shows the contents of the object represented by the
symbol.
Applications and users can make a symbol executable. Double clicking
on an executable symbol results in the invocation of an action provided
by an application. (Actions are described in Chapter 2 , Creating and
Using Registration Files.) You can define the selection list when you
make the symbol executable.
Symbol Position
The submap layout algorithm controls how symbols are placed on a
submap. The layout algorithm is chosen during submap creation, and is
fixed for the life of the submap. (Submap creation was presented in the
previous chapter.)
Submaps can use any one of seven layout algorithms:
no layout algorithm
238
Chapter 7

point to point
bus
star
ring
row/column
multiple connections.
OVW uses the submap layout algorithm to automatically determine
symbol placement. You can, however, override the default symbol
placement and programmatically specify a particular position for the
symbol. Table 7-1 lists the four different forms of position:
Table 7-1
Forms for Positioning Symbols
Form
What It Does
No Position
The symbol has no specific position on the submap. OVW will use the default
symbol placement algorithm if you choose this placement value. This position is
valid for any layout algorithm.
Coordinate
Position
The symbol has an X, Y coordinate position within a grid of given width and
height. This position is valid for any layout algorithm.
Sequence Position
The position is specified as part of a sequence, relative to its predecessor. The

display of the sequence differs for bus, row/column, star, and ring layouts. A
special value is used to indicate the first symbol in the sequence. This position is
valid only for ring, star, bus, or row/column layout algorithms.
Star Center
The symbol is the center of a star layout. This position is valid only for the star
layout algorithm.
Note that not every position form is valid for every submap default
layout algorithm. Specifically, the Sequence Position and Star Center
Position are valid for only some layout algorithms. You should use care in
selecting a position form that is compatible with your submap default
layout algorithm.
Symbol Status
Each symbol within HP OpenView Windows can display status
information through the use of color. Each of the different possible status
values has an associated color that indicates the status of the symbol.
Chapter 7
239

Table 7-2 summarizes the possible status values, when they are used,
and the color associated with each status condition.
Table 7-2
Status
Category
HP OpenView Status Colors

Status
Condition
Status Meaning
Icon Color/
Connection
Color
Administrative
Unmanaged
Users can set this value, which indicates

that the object should not be monitored
and that the status should be ignored.
Off-white/Black
Administrative
Testing
An application sets the status to testing

when an object is undergoing temporary
diagnostic or maintenance procedures.
Salmon/Salmon
Administrative
Restricted
An application sets the status to

restricted when an object is functioning
normally, but it may not be available to all
users.
Tan /Tan
Administrative
Disabled
An application sets the status to disabled

when an object is inactive (although there
may not necessarily be anything wrong
with the object).
Dark Brown /Dark

Brown
Operational
Unknown

unknown when the status of an object
cannot be determined.
Blue/Black
Operational
Normal
An application sets the status to normal

when the object is in a normal operational
state.
Green/Black
Operational
Warning
An application sets the status to warning

when an object may face a potential
problem.
Cyan/Cyan
Operational
Minor/ Marginal

minor/marginal when an object has a
minor problem; this status should not,
however, impede the normal use of the
object.
Yellow/Yellow
240
Chapter 7

Table 7-2
Status
Category
HP OpenView Status Colors

Status
Condition
Icon Color/
Connection
Color
Status Meaning
Operational
Major
An application sets the status to major

when an object has serious problems;
these problems are likely to impede
normal use of the object.
Orange/Orange
Operational
Critical
An application sets the status to critical

when an object is not functioning.
Red/Red
These status colors are preset by OVW. For UNIX system applications,
developers or users can, however, change these colors through the X
resource file (see the ovw(1) reference page).
OVW Status Types - ISO 10164 Severity Levels If you are familiar
with the ISO 10164 standard for alarm reporting functions, use the
following list to map the ISO severity levels to their OVW equivalents:
Table 7-3
OVW - ISO Equivalents

ISO 10164 Severity Levels
OVW Status Conditions
none
unmanaged
cleared
normal
indeterminate
unknown
critical
critical
major
critcal
minor
minor/marginal
warning
minor/marginal
Status Sources Symbols can receive status from one of three sources:
Status by Object This status source causes the symbol to reflect the
status for the underlying object. This status source allows multiple
Chapter 7
241

symbol instances of the object to receive and reflect the same status
information to the user.
HP recommends that you use this status source for symbols representing
objects at the lowest level in the object hierarchy. Objects at this level
typically do not have component objects below them. Examples of these
types of objects include interface cards or specific software applications.
This status source benefits users who copy symbol instances between
submaps, as each new symbol instance has the same status as the
original symbol instance.
Compound Status This status source can be used for a symbol whose
underlying object serves as a parent object for a child submap. Using this
status source, the symbol status represents a summation of the status
for all symbols in the child submap. This status source lets higher level
symbols reflect the state of lower level components controlled by multiple
applications.
OVW uses its own algorithm to determine how to summarize the status
of symbols in a submap, but users can tune the algorithm to their liking.
Developers have no control over the algorithm used to summarize status
for a child submap.
Compound status is appropriate only for symbols whose underlying
objects serve as parent objects of child submaps.
Status by Symbol This status source lets a specific symbol instance
receive status directly from an application. Use this status source if your
application has the exclusive responsibility for setting status for the
specific symbol instance.
Creating a new symbol instance with symbol status source assures
application control over the symbol status. It also eliminates the
possibility of status conflict between applications.
The HP OpenView Application Style Guide discusses the ramifications of
selecting a particular status mechanism. See that manual for more
guidance in using status consistently across applications.
Symbol Alerts
A symbol alert is an addition to an icon or connection symbol, it
provides a way to get a users attention. It is a visual cue to facilitate
monitoring at a glance and should be used when there are urgent
242
Chapter 7

conditions of immediate importance. Symbol alerts are used in addition
to, not instead of, symbol status color.
Symbol alerts can be created and deleted only by applications. A symbol
alert appears in the display when an application detects a condition
which needs immediate user attention and it creates a symbol alert on
the appropriate base symbol. The urgency of the condition may be
indicated to the end user by the color and type of symbol alert shape. The
nature or location of the condition may be communicated to the end user
by text within the shape of the symbol alert. Additional information
about the condition may be available through a pop-up menu available
for the symbol alert.
Users can respond to and act on a symbol alert. For every symbol alert
two user actions are available. The user can 1) make a selection from the
symbol alerts pop-up menu or 2) by double clicking on the symbol-alert
shape execute the default action that is registered for the symbol alert.
As soon as a user responds to a symbol alert it should be deleted by the
application that displayed it. The user cannot then restore it or any
information about it.
A symbol alert cannot be selected or moved independently of its base
symbol (the icon or connection symbol to which it is attached). A symbol
alert is not copied when its base symbol is copied. A symbol alert can be
hidden only if its base symbol is hidden. A symbol alert is not a valid
drop site.
A base symbol cannot be deleted or moved to another submap while it
has a symbol alert.
The symbol alert is fixed at a size that is visible and readable. Unlike the
base symbol it does not scale and is not displayed in the panner. It is
depicted as a flag beside the symbol so that there is no ambiguity about
which symbol is the base symbol.
Symbol Presentation
Table 7-4 lists the symbol presentation capabilities that provide visual
cues to emphasize or to de-emphasize a symbol.
Chapter 7
243

Table 7-4
Symbol Presentation Attributes
Attribute
Description
Flashing symbols
Applications can cause symbols to start and stop flashing. This

feature is used to catch an operators attention. Operators can
disable this feature by changing a setting in an X resource file.
Refer to Flashing Symbols on page 272.
Transparent symbol backgrounds
Applications can present symbols that have normal status and size
so that only the inside graphic is visible. This results in a less
cluttered submap where non-normal status is more easily
perceived. Operators can disable this feature by changing a setting
in an X resource file. Refer to Transparent Symbol Background
on page 270.
Disable executable symbol cue
Applications can present executable symbols without the box

around the symbol the provides the visual cue that they are
executable. This functionality can be disabled by operators by
changing a setting in an X resource file. Refer to Executable
Symbol Appearance on page 271.
Connection symbol thickness
Developers can specify the line width of a connection in pixels.

Formerly, all connection symbols were 1 pixel wide. This
specification is part of the definition of connection symbol type in
symbol registration files. Developers can query the thickness by
querying the connection symbol type and referring to the
registration file description to learn the thickness.
Operators can change connection width by changing the symbol
type. Operators can query the thickness by querying the
connection symbol type and referring to the registration file
description to learn the thickness. Refer to Connection Symbol
Appearance on page 274.
244
Chapter 7

Table 7-4
Symbol Presentation Attributes
Attribute
Description
Connection symbol percentage

full
Developers can control the appearance of a connection symbol so

that it appears empty, partially filled, or completely filled. By
default the connection symbol appears completely filled.
Applications can dynamically change connection symbol fill to a
value between 0% and 100%.
This functionality provides operators additional feedback about the
state of a connection; however, they have no control over display
of connection symbol fill percentage. Refer to Connection
Symbol Appearance on page 274.
Connection symbol secondary

status
The primary status of a connection symbol is used to control the

color of the borders of the symbol and the amount of the
connection that is filled.
The secondary status is used to present the unfilled portion of the
of the connection symbol. This functionality provides operators
additional feedback about the state of a connection; however, they
have no control over display of secondary status. Refer to
Connection Symbol Appearance on page 274.
Text annotation
Applications can dynamically superimpose text over icon

symbols, connection symbols, and symbol alerts. Refer to Text
Annotation for Symbols on page 273.
Chapter 7
245

Creating Symbols
Creating Symbols
This section describes how to create icon and connection symbols. Once
you understand the symbol characteristics presented in the previous
section (label, position, status, status source, type, etc.), symbol creation
is quite straightforward. You should read this section even if you dont
plan to create your own symbols. This section describes other elements
that are important later in this chapter, such as symbol placement.
Creating Icon Symbols

The OVwCreateSymbol() routine is a general purpose routine that can
create any type of icon symbol for an existing object. It has the function
prototype:
OVwSymbolId OVwCreateSymbol(OVwMapInfo *mapInfo,
OVwSubmapId submapId,OVwObjectId objectId,
OVwSymbolType symbolType, char *label,
OVwStatusType status, int statusSource,
OVwSymbolPosition *symbolPosition, unsigned int flags)
The arguments to OVwCreateSymbol() are described on the next page.

The mapInfo argument, however, deserves special attention here.
Most OVw API symbol routines take a pointer to the mapInfo data
structure as the first argument. You can use the OVwGetMapInfo() OVw
API routine to generate a mapInfo data structure, or you can save the
map information in a callback routine that handles the map open event.
Within that callback routine, you can use OVwCopyMapInfo() to save the
map information returned with the ovwMapOpen event. Map information
is valid until the map is closed.
When calling OVwCreateSymbol(), you need to supply these arguments:
complete map information. You can use the OVwGetMapInfo()
routine to get the map information.
submapId identifies which submap the symbol should be placed on.
Submaps were described in a previous chapter.
objectId is the object ID of the associated underlying object. Object
creation was discussed earlier in this manual.
246
Chapter 7

Creating Symbols
symbolType is a character string identifying a symbol class/subclass
pair as defined in a Symbol Registration File. The header file
\OpenView\include\OV\sym_types.h (Windows NT operating
system) $OV_HEADER/OV/sym_types.h, (UNIX systems), which is
automatically included by \OpenView\include\OV\ovw.h (Windows
NT operating system) or $OV_HEADER/OV/ovw.h (UNIX systems),
contains localized string definitions for symbol types shipped with
OVW.
label is a character string that is initially displayed at the bottom of
the symbol. Users can change the label at any time, and both users
and developers can optionally disable the display of the label.
status is the initial status of the symbol. Possible values are
ovwUnknownStatus, ovwUpStatus, ovwMinor Status,
ovwCriticalStatus, and ovwUnmanagedStatus.
statusSource defines how the symbol receives status information.
Possible values are: ovwSymbolStatusSource,
ovwObjectStatusSource, and ovwCompoundStatusSource.
symbolPosition is set to NULL in most cases. A NULL value tells
OVW to use its own symbol placement algorithm. As youll see later,
you can optionally specify where the symbol is positioned on the
submap.
flags specifies symbol creation flags. Possible values are
ovwNoSymbolFlags, ovwMergeDefaultCapabilities, or
ovwDoNotDisplayLabel. These values may be logically ORed
together. These values are described later.
The OVwCreateSymbol() routine returns a symbol ID, which is a unique
numeric identifier for the symbol. The symbol ID is used in subsequent
calls involving the symbol.
The following code segment shows how to create a symbol. The ID of the
object that the symbol represents is passed as an argument.
#include <OV/ovw.h>
create_symbol(object_id)
OVwObjectId object_id;
{
OVwSymbolId symid;
OVwMapInfo *map;
Chapter 7
247

Creating Symbols
/* Create the symbol, using an OVW constant to represent the
*/
** symbol type */
symid = OVwCreateSymbol(map, map->root_submap_id, object_id,
ovwSWorkstationComputer, "test", ovwUnknownStatus,
ovwSymbolStatusSource, NULL, ovwNoSymbolFlags);
...
OVwFreeMapInfo(map);
}
In this example, the symbol type for the symbol class/subclass

Computer: Workstation is placed on the root submap of the open map.
The symbol has the label test. The initial status is unknown, and the
status is set on a symbol basis.
Variants of the OVwCreateSymbol() Routine
While the OVwCreateSymbol() routine can create any type of icon
symbol, convenience routines are available that are easier to use in
certain situations. They include
OVwCreateSymbolByName(), OVwCreateSymbolBySelectionName(),
OVwCreateSymbolByHostname()
These routines let you identify the object by one of its names, instead of
by its object ID. If the object does not yet exist, these routines will first
create the object for you using OVwDbCreateObject():
OVwCreateComponentSymbol(), OVwCreateComponentSymbolByName()
These two routines let you create symbols on a submap by identifying the
parent object of the submap, rather than by identifying the submap ID. If
the submap does not exist, OVW will create it for you.
These convenience routines use many of the same parameters as the
general purpose OVwCreateSymbol() routine and are quite similar in
concept. See the reference pages if you need more information on these
calls.
Symbol Creation Flags
Flags control miscellaneous aspects of symbol creation. You can use one
of the following flags when you create a symbol:
ovwNoSymbolFlags
This is equivalent to passing a NULL value for the flags parameter
to OVwCreateSymbol().
248
Chapter 7

Creating Symbols
ovwDoNotDisplayLabel
Setting this flag will prevent the symbol label from being displayed.
This flag is typically used when creating connection symbols.
ovwMergeDefaultCapabilities
If this flag is set, the default capability fields of the symbol type
specified in the OVwCreateSymbol() call will be merged with the set
of capability fields for the object. If a capability field exists in the
symbol type definition but not the object definition, it will be added to
the object. Existing field values within the object are not changed.
See the OVwCreateSymbol(3) reference page if you need more
information about these flags.
Specifying Symbol Position
The previous OVwCreateSymbol() example showed how to create a
symbol using the default symbol position. The default position is
adequate in most cases. You can, however, specify a particular symbol
position when you create a symbol. OVW will place symbols where you
request and will make the appropriate connections between symbols for
you.
Recall from earlier in this chapter that there are four different positions
that you may specify when symbols are created or moved. The following
list summarizes the position forms and when they can be used:
No position (ovwNoPosition), which is valid for any layout algorithm.
Coordinate Position (ovwCoordPosition), which is valid for any
layout algorithm.
Sequence Position (ovwSequencePosition), which is valid for any
sequence layout algorithm (ring, star, bus, or row/column).
Star Center Position (ovwStarCenterPosition), which is valid only
for the star layout algorithm.
You can specify these position forms, as well as the associated
information for the position, using the following data structure:
typedef
int
#define
#define
#define
struct {
placement;
ovwNoPosition
ovwCoordPosition
ovwSequencePosition
Chapter 7
0
1
2
/* type of symbol placement

/* no symbol position
/* x, y position
/* serial order
*/
*/
*/
*/
249

Creating Symbols
#define ovwStarCenterPosition
union {
struct {
int x;
int y;
int width;
int height;
} coords;
OVwSymbolId pred_symbol;
} un;
#define pos_coord_x
#define pos_coord_y
#define pos_coord_width
#define pos_coord_height
#define pos_pred_symbol
} OVwSymbolPosition;
/* star center */
/* ovwCoordPosition */
/* x position on grid */
/* y position on grid */
/* width of grid */
/* height of grid */
/* ovwSequencePosition */
un.coords.x
un.coords.y
un.coords.width
un.coords.height
un.pred_symbol
The placement field is set to one of the four position forms. If you use
either the ovwCoordPosition or ovwSequencePosition, you will also
need to set the appropriate values within the un union.
NOTE
If automatic layout is disabled, the symbol may not be placed until

automatic layout is re-enabled. See the OVwSetSymbolPosition(3)
reference page if you need precise information about how OVW treats
explicit symbol placement for the various layout algorithms when
automatic layout is enabled or disabled.
Setting Sequence Position Symbols that use any of the sequence

layout algorithms (ring, star, bus, row/column) are related to each other
by positional order. Each symbol is related to the previous symbol in the
sequence by the pred_symbol field. Setting sequence position is
essentially a process of placing a symbol at a particular place in the
sequence.
To override OVWs automatic symbol placement, you simply specify the
symbol ID of the predecessor symbol in the pred_symbol field in the
OVwSymbolPosition data structure. The first symbol in the sequence has
the special value ovwNullSymbolId. OVW will place the symbol in the
sequence immediately after the specified predecessor symbol. Depending
on whether the user has enabled or disabled automatic symbol layout,
the symbol may or may not be placed immediately.
250
Chapter 7

Creating Symbols
Setting Coordinate Position You can use coordinate placement to
position symbols relative to one another or at some fixed point on a
background graphic. Submaps without background graphics are scaled
so that unused space on the periphery of the submap is not displayed.
This does not happen for a submap with a background graphic, since
symbol placement is relative to the background graphic and the entire
background graphic is always displayed.
Specifying symbol position by coordinate position requires two sets of
values:
a width and height to specify a coordinate system, or grid
an X and Y coordinate on the specified coordinate system where the
symbol should be placed.
You define the coordinate system according to which symbols will be
placed. You do not need to know the current virtual size of the submap or
its screen size when scaled for display. (OVW translates the grid
coordinate position to a virtual position based on the virtual size of the
submap. Under certain circumstances, the grid specification affects the
virtual size of the submap.)
For example, a symbol placed at position [100,100] on a [200 x 200] grid
will be placed at the center of the submap. A symbol placed at position
[150,200] on a [300 x 400] grid will also be placed in the center of the
submap. For best results, use the same grid size for all symbols placed on
a particular submap.
You can use the grid size to determine how large symbols appear on the
submap. For example, two symbols placed at positions [25,25] and
[75,75] on a [100 x 100] grid will appear in the same positions relative to
one another as symbols placed at positions [250,250] and [750,750] on a
[1000x1000] grid. Symbols in the latter case, however, will appear
smaller because of the greater distance between them.
Symbol placement by coordinates takes effect immediately, regardless of
whether automatic layout is enabled or disabled.
Note that symbol positions specified by coordinates are lost whenever the
user invokes the automatic layout algorithm. If your application needs to
disable all automatic layouts, it should create the submap with the
layout algorithm set to ovwNoLayout.
The following code segment shows how to define coordinate positions
using the OVwSymbolPosition data structure:
Chapter 7
251

Creating Symbols
...
OVwSymbolPosition *position;
position->placement = ovwCoordPosition;
position->un.coords.x = 50;
position->un.coords.y = 30;
position->un.coords.width = 100;
position->un.coords.height = 90;
...
The ovwNoPosition and ovwStarCenterPosition position forms are

simple to use and will not be described here. See the
OVwSetSymbolPosition(3) reference page if you need more details about
these forms of symbol placement.
Guidelines for Symbol Placement There are a few guidelines to
consider when using explicit symbol placement:
If the submap represents a logical or semantic view of the
real-world objects, place the symbols according to the rules that apply
to the logical or semantic relationship.
If the submap represents a physical view of real-world objects, place
the symbols according to their correspondence to the real-world
objects.
If the submap contains multiple semantics and you cannot provide an
accurate mapping to the real-world objects, let OVW place the
symbols for you.
Creating Connection Symbols

Creating a connection symbol is very similar to creating an icon symbol.
Many of the parameters are similar to those used to create an icon
symbol.
Use the OVwCreateConnSymbol() routine to create a connection symbol.
This routine has the function prototype:
OVwSymbolId OVwCreateConnSymbol(OVwMapInfo *map,
OVwObjectId connectId, OVwSymbolId endpoint1,
OVwSymbolId endpoint2, OVwSymbolType symbolType,
char *label, OVwStatusType status, int statusSource,
unsigned int flags);
252
Chapter 7

Creating Symbols
An object that represents the connection must already exist in order to
use the OVwCreateConnSymbol() routine. The objectId argument
contains the object ID of the object that represents the connection.
The endpoint1 and endpoint2 parameters have not been described
previously. They specify the symbol IDs of the icon symbols to be
connected. The special value ovwSubmapBackbone may be substituted for
one of the endpoints if the submap layout algorithm uses a backbone.
OVW supports two layout algorithms that use backbones: ovwBusLayout
and ovwRingLayout.
The symbolType parameter must specify a symbol type belonging to the
Connection symbol class. For convenience, you can use a value of NULL
for symbolType to indicate the default symbol type. (A NULL symbol
type value is not allowed when creating icon symbols.)
Connection Symbols and Meta-connections
When the first connection is created between two symbols, a simple
connection symbol is added to the submap. When a second connection is
made between the two symbols, a special meta-connection submap is
automatically created by OVW to hold the two connections and a
meta-connection symbol replaces the original simple connection.
Double-clicking on the meta-connection symbol displays the
meta-connection submap showing all connections between the two
symbols.
Developers do not need to be concerned with meta-connection symbols
when creating connections. OVW manages meta-connections for you
automatically.
Developers must be prepared to deal with meta-connections, though,
when reading symbol information. The meta-connection, not the actual
connection, appears in references to connection symbols in the submap
containing the connection. For example, assume that you need to modify
the status of a connection symbol. When you get a list of all symbols on a
submap, you would find a meta-connection symbol, not the actual
connection symbol for the particular connection. You would need to get
the submap associated with the meta-connection symbol and check that
submap for the presence of your connection symbol. After finding your
connection symbol in the meta-connection submap, you could change the
status of the connection symbol.
See the OVwCreateSymbol(3) reference page if you need more
information about meta-connections.
Chapter 7
253

Creating Symbols
Creating Multiple Symbols with a Single Call

The OVw API provides the OVwCreateSymbols() routine to let you
create multiple symbols in a single call.
The OVwCreateSymbols() routine can create combinations of both icon
and connection symbols. To do this, OVwCreateSymbols() uses a rather
complex data structure that allows you to define either icon or connection
symbols. Most of the data structure elements have been described in
some form earlier in this chapter; however, three of the data structure
elements have not yet been described:
text_annotation
percent_full
secondary_status
For a description of these elements, refer to Text Annotation for
Symbols on page 273 and Connection Symbol Appearance on page
274.
The OVwCreateSymbols() routine has the function prototype:
int OVwCreateSymbols(OVwMapInfo *mapInfo,
OVwSymbolCreateList *symbolList);
The symbolList parameter points to a data structure of type

OVwSymbolCreateList that contains a count of the number of symbols
and a pointer to an array of OVwSymbolCreateInfo data structures, each
of which fully defines the symbol to be created. The
OVwSymbolCreateList data structure is defined as follows:
typedef struct {
int count;
/* number of items in the list */
OVwSymbolCreateInfo *symbols; /* contiguous list of items */
} OVwSymbolCreateList;
Use the OVwSymbolCreateInfo data structure to define each symbol you

want to create. The OVwSymbolCreateInfo data structure has the form:
typedef struct {
/* input values */
int submap_name_style;
/* how submap is specified */
#define ovwSubmapIdValue
1 /* submap specified by submap ID */
#define ovwSubmapParentIdValue 2 /* submap specified by parent
object */
union {
/* submap on which to create symbol */
/* ovwSubmapIdValue */
254
Chapter 7

Creating Symbols
OVwObjectId parent_id;
/* ovwSubmapParentIdValue*/
} submap_un;
/* ignored if variety == ovwConnSymbol*/
#define sc_submap_id
submap_un.submap_id
#define sc_parent_id
submap_un.parent_id
int object_name_style;
/* how object of symbol is identified */
#define ovwObjectIdValue
1
/* object specified by object ID */
#define ovwObjectNameValue 2
/* object specified by name field value */
union {
/* object this symbol represents */
/* ovwObjectIdValue */
OVwFieldBinding *object_name;
/* ovwObjectNameValue */
} obj_un;
#define sc_object_id
obj_un.object_id
#define sc_object_name obj_un.object_name
char *label;
/* symbol label */
OVwStatusType status;
/* initial symbol status */
int status_source;
/* symbol status source */
OVwSymbolType symbol_type;
/* symbol type */
int symbol_variety;
/* ovwIconSymbol, ovwConnSymbol */
union {
/* variety-specific information */
OVwSymbolPosition *position;
/* ovwIconSymbol variety */
struct {
/* ovwConnSymbol variety */
int endpoint1_name_style;
/* how endpoint 1 is specified */
#define ovwEndpointSymbolIdValue 1
/* endpoint specified by symbol ID */
#define ovwEndpointIndexValue
2
/* endpoint specified by list index */
/* for OVwCreateSymbolList entry i, endpoint index j, j must be less than i */
union {
/* connection endpoint 1 */
OVwSymbolId symbol_id;
/* ovwEndpointSymbolIdValue */
int symbol_index;
/* ovwEndpointIndexValue */
} un_endpoint1;
int endpoint2_name_style;
/* how endpoint 2 is specified */
union {
/* connection endpoint 2 */
/* ovwEndpointSymbolIdValue */
int symbol_index;
/* ovwEndpointIndexValue */
} un_endpoint2;
} endpoints;
} sc_var_un;
#define sc_icon_position sc_var_un.position
#define sc_conn_endpoint1_style sc_var_un.endpoints.endpoint1_name_style
#define sc_conn_endpoint1_id
sc_var_un.endpoints.un_endpoint1.symbol_id
#define sc_conn_endpoint1_index
sc_var_un.endpoints.un_endpoint1.symbol_index
#define sc_conn_endpoint2_style
sc_var_un.endpoints.endpoint2_name_style
#define sc_conn_endpoint2_id
Chapter 7
255

Creating Symbols
sc_var_un.endpoints.un_endpoint2.symbol_id
#define sc_conn_endpoint2_index
sc_var_un.endpoints.un_endpoint2.symbol_index
unsigned int flags;
/* symbol creation flag values
char *object_comments;
/* object comments; used if not already set
/* result values
int error;
/* OVw_SUCCESS or error value
/* symbol ID result or ovwNullSymbolId
OVwStatusType secondary_status;
/* initial symbol status
int percent_full;
/* percent_full
char *text_annotation;
/* text annotation text
#endif
} OVwSymbolCreateInfo;
*/
*/
*/
*/
*/
*/
*/
*/
The following example shows how to create multiple symbols with the
OVwCreateSymbols() routine (assuming that it is compiled with
OVwAPILevel=4):
#include <OV/ovw.h>
#define BUILD_ICON(sym,sid,oid,stype,slabel,stat,src,pos,flgs)
{\
sym.submap_name_style = ovwSubmapIdValue; \
sym.sc_submap_id = sid; \
sym.object_name_style = ovwObjectIdValue; \
sym.sc_object_id = oid; \
sym.label = slabel; \
sym.status = stat; \
sym.status_source = src; \
sym.symbol_type = stype; \
sym.symbol_variety = ovwIconSymbol; \
sym.flags = flgs; \
sym.sc_icon_position = pos; \
sym.object_comments = "No comment"; \
sym.error = 0; \
sym.symbol_id = ovwNullSymbolId; \
}
#define BUILD_CONNECTION(sym, oid, stype, slabel,
svalue,src,sym1,sym2,flgs) {\
sym.object_name_style = ovwObjectIdValue; \
sym.sc_object_id = oid; \
sym.label = slabel; \
sym.status = svalue; \
sym.status_source = src; \
256
Chapter 7

Creating Symbols
sym.symbol_type = stype; \
sym.symbol_variety = ovwConnSymbol; \
sym.flags = flgs; \
sym.sc_conn_endpoint1_style = ovwEndpointSymbolIdValue; \
sym.sc_conn_endpoint1_id = sym1; \
sym.sc_conn_endpoint2_style = ovwEndpointSymbolIdValue; \
sym.sc_conn_endpoint2_id = sym2; \
sym.object_comments = NULL; \
sym.error = 0; \
sym.symbol_id = ovwNullSymbolId; \
}
void
CreateSymbol(void *, char *actionID, char *menuItemID,
OVwObjectIdList *, int, char **)
{
OVwSymbolInfo *symbol;
OVwSymbolCreateList symbolList;
OVwSymbolCreateInfo symbolInfo;
OVwMapInfo *map = OVwGetMapInfo();
fprintf(stderr, "ACTION: %s\n", actionID);
fprintf(stderr, "MENUITEM: %s\n", menuItemID);
symbolList.count = 1;
symbolList.symbols = &symbolInfo;
object_id = OVwDbCreateObject(NULL);
BUILD_ICON(symbolInfo, map->root_submap_id, object_id,
"Computer:Workstation", "new symbol", ovwNormalStatus,
ovwSymbolStatusSource, NULL,
ovwMergeDefaultCapabilities);
OVwCreateSymbols(map, &symbolList);
symbol_id = symbolList.symbols[0].symbol_id;
symbol = OVwGetSymbolInfo(map, symbol_id);
OVwPrintSymbolInfo(symbol, TRUE);
}
void
CreateConnection(void *, char *actionID, char *menuItemID,
OVwObjectIdList *, int, char **)
{
OVwSymbolCreateList symbolList;
Chapter 7
257

Creating Symbols
OVwSymbolCreateInfo symbolInfo[3];
OVwSymbolId symbol1_id;
OVwSymbolId symbol2_id;
OVwSymbolInfo *symbol;
fprintf(stderr, "ACTION: %s\n", actionID);
fprintf(stderr, "MENUITEM: %s\n", menuItemID);
symbolList.symbols = &symbolInfo[0];
object_id = OVwDbCreateObject(NULL);
BUILD_ICON(symbolInfo[0], map->root_submap_id, object_id,
"Computer:Workstation", "number one", ovwMarginalStatus,
ovwObjectStatusSource, NULL, 0);
BUILD_ICON(symbolInfo[1], map->root_submap_id, object_id,
"Computer:Workstation", "number two", ovwMarginalStatus,
ovwObjectStatusSource, NULL, 0);
symbol1_id = symbolList.symbols[0].symbol_id;
symbol = OVwGetSymbolInfo(map, symbol1_id);
symbol2_id = symbolList.symbols[1].symbol_id;
symbol = OVwGetSymbolInfo(map, symbol2_id);
BUILD_CONNECTION(symbolInfo[0], object_id, NULL, NULL,
ovwNormalStatus, ovwObjectStatusSource,
symbol1_id, symbol2_id, 0);
symbol_id = symbolList.symbols[0].symbol_id;
symbol = OVwGetSymbolInfo(map, symbol_id);
symbol = OVwGetConnSymbol(map, symbol1_id, symbol2_id);
}
main(int, char **)
258
Chapter 7

Creating Symbols
{
fprintf(stderr, "%s\n", OVwErrorMsg(OVwError()));
exit(1);
}
OVwAddActionCallback("Symbol",
(OVwActionCallbackProc)CreateSymbol, NULL);
OVwAddActionCallback("Connection",
(OVwActionCallbackProc)CreateConnection, NULL);
OVwMainLoop();
}
Advantages/Disadvantages to Using OVwCreateSymbols()

The advantage to using this routine is mainly in speed. It takes less
execution time to create multiple symbols with OVwCreateSymbols()
than it does to create them individually. OVwCreateSymbols() has some
disadvantages, however. The data structures are more complex. Also,
users can encounter delays while long lists of symbols are being created.
In general, if users need timely, continuous feedback, you should
consider using the simpler OVwCreateSymbol() routine or use
OVwCreateSymbols() with only a few symbols. If users do not expect
immediate feedback, you can use the more efficient
OVwCreateSymbols() routine.
Deleting Symbols
The OVw API provides two routines to delete symbols. The
OVwDeleteSymbol() routine deletes a single symbol from the open map,
while the OVwDeleteSymbols() routine deletes a list of symbols. Either
routine can be used to delete icon or connection symbols.
These routines have the function prototypes:
int OVwDeleteSymbol(OVwMapInfo *mapInfo,
OVwSymbolId symbolId);
int OVwDeleteSymbols(OVwMapInfo *mapInfo,
OVwSymbolIdList *symbolList);
In general, an application should delete only those symbols that it

creates. Applications should not delete symbols created either by the
user or by another application.
Chapter 7
259

Creating Symbols
Symbol Deletion and Object Deletion
If you delete a symbol that is the last symbol on the map that represents
an object, you might need to delete the object as well. Chapter 5 ,
Creating and Using Objects and Fields, describes how to delete objects.
That chapter describes the steps for deleting an object once it is known
that the object should be deleted.
Chapter 8 , Map Editing and Map Events, describes how to determine
when objects should be deleted. Specifically, that chapter describes how
to register for map editing events that indicate that an object should be
deleted.
Creating Symbol Alerts

NOTE
Refer to the important style recommendations for using symbol alerts in

the HP OpenView Application Style Guide.
You implement symbol alerts through a combination of registration file

specification and API calls:
In the application registration file you need to define:
at least one popupItem, the one associated with the default
action
at least one action, the one associated with a default action.
In the application you need to implement:
a procedure for evaluating the conditions for symbol alert
a callback procedure for actions
a callback procedure for event
storage of symbol alert instance information.
The following sections explain symbol alert behavior, provide an example
of symbol alert usage, and explain how to use the OVw APIs to
implement symbol alerts. For information about definition of registration
file components of symbol alerts, refer to Creating and Using
Registration Files on page 39.
260
Chapter 7

Creating Symbols
Symbol Alert Behavior
A developer determines a symbol alerts behavior on a per-instance basis.
A symbol alert that is created by an instance of an application on a
particular instance of a map is not propagated to other instances of the
map by OVW. This is different from the creation of an icon symbol or a
connection symbol by applications. It is the responsibility of the instance
of the application associated with the other instances of the map to do
their own symbol alert creation and deletion. This applies to read-only
maps as well as the read-write map; symbol alert creation is allowed on
read-only maps. A default action for a symbol alert is most effective if it
can be performed on a read-only map as well as in a read-write map.
Symbol alerts are not saved when a map is closed. When a map is
re-opened, applications should use the current state of objects of interest
and their event history to determine whether they need to post any
symbol alerts.
Contents of the pop-up menu are determined dynamically using a
variation on the existing runtime evaluation of registered pop-up menus
and items. The evaluation is based on the alert type, the submap context
and the application.
Use Model
Symbol alerts are best used on base symbols that are container symbols
that monitor and manage a collection of other symbols representing
objects of particular importance. It is these contained objects that are
most often the targets of the symbol alerts default action and of its
pop-up menu actions.
The symbol alerts default action and menu item actions are associated
with the base symbol as the target object for the action. These actions
must be able to determine the actual target(s) for the action (that is, the
contained objects) at run time. This determination must be based on
information that the application stores for the symbol alert at the time
that it creates that symbol alert.
Determining the target objects for an action on a particular symbol alert
at run time can be achieved using 1) action registration which specifies
only the action name and 2) registering an action as the callback
procedure using the OVwAddActionCallback(). When a user selects an
item from the symbol alert pop-up menu the associated action should
have no command, so no application command is automatically executed
by the system. But the application, which has registered for the
Chapter 7
261

Creating Symbols
OVwAddActionCallback() for all of its symbol alert actions, is notified of
the menu pick, object ID and the submap ID (that is, it gets the action
callback for the symbol) and determines the actual command to invoke
and the objects it needs to target, based on the information it has stored
for the symbol alert instance.
For example, suppose symbol FireExitDoors represents all of the fire
doors that are monitored at the Telephone Control Center. The map
contains symbols representing each of the monitored rooms. Container
symbol FireExitDoors represents all of them and reflects the collective
status of all of the contained symbols so it is always displayed in an open
submap.
Suppose that fire door opened events are received for the objects
representing Room #7 and Room #8. The monitoring application posts a
red flag symbol alert for the FireExitDoors symbol and stores the
names of the room object associated with the open door event. The action
for this symbol alert is CheckSmoke but there is no command in the
action registration. Using OVwAddActionCallback(), the application
has registered a callback routine to handle the CheckSmoke action.
When the user double-clicks the symbol alert or selects the
corresponding menu item for the CheckSmoke action the application is
notified of an action associated with the object represented by the target
symbol FireExitDoors. Based on the information that it has stored for
the FireExitDoors alert, it sends a probe to the smoke detector for Room
#7 and to the smoke detector for Room #8. Those are the actual objects of
interest.
The symbol alert action registration example in the application
registration file would look like this:
Application "FireFighter" {
Action "CheckSmoke" {
.
.
and the callback registration code would look like this:

ret =
OVwAddActionCallback("CheckSmoke",(OVwActionCallbackProc)
sendProbe, NULL);
262
Chapter 7

Creating Symbols
Symbol Alert Components
The symbol alert, illustrated in Figure 7-1 and described in the
remainder of this section, consists of five parts.
Figure 7-1
Symbol Alert
3
Text Annotation for
Symbol Alert
Pop-Up Menu
4
Default Action
5
Alert Action 2
Alert Action 3
A Base Symbol
1. Designated base symbol, either icon or connection.

This is the symbol to which the alert is attached. It must exist at
the time that the application creates the alert for it. If an attempt is
made to create a symbol alert for a non-existent symbol, OVW
returns an error. The symbol may represent a single device of
interest, but is more likely to be a container symbol representing a
collection of important objects.
In the context of transient and persistent submaps, a symbol
exists if one of the following conditions is true:
It is displayed on an open submap.
It is hidden on an open submap.
It is on a closed submap that has been made persistent.
Chapter 7
263

Creating Symbols
Only one symbol alert per symbol is allowed; an attempt to create
one for a symbol that already has a symbol alert returns an error.
The OVwConfirmDeleteSymbolAlert() event informs an
application when a symbol alert is deleted. It is used by the
application to time its retry when a create call fails because the
base symbol already had a symbol alert.
2. A displayed shape.
The shape is chosen by the developer from among those shipped
with HP OpenView Windows; the symbol alert pixmaps come in
the three colors that represent the three most critical status
states. As with other symbols, developers may provide and use
their own registration and custom pixmaps. Refer to Creating
and Using Registration Files on page 39 for more information.
When the alert is displayed with its base symbol, the alerts
location and orientation (that is, its relationship to the base
symbol) is determined by OVW. Its orientation is changed
automatically if the base symbol is moved by the end user.
The HP OpenView Application Style Guide provides guidelines to
developers regarding the size, shape, color, and the use of custom
symbol alert shapes.
3. Text annotation.
A text string determined by the developer at symbol alert creation
time is displayed inside the symbol alert in its text region. The
purpose of the text is to give the end user information about the
urgent condition. While text annotation is not mandatory, it is
strongly recommended.
The text region for each alert type is specified in its registration
file, refer to Creating and Using Registration Files on page 39.
The text annotation string is limited to two lines of 12 characters
each.
The text annotation on a symbol alert can be added or changed
programmatically by the application that created the alert via
OVwSetSymbolAlertText() (See Setting Symbol Alert Text
Annotation on page 267.)
4. Default action.
The default action is the action that is executed when a symbol
264
Chapter 7

Creating Symbols
alert is double-clicked. The default action is also provided as a
menu item by the developer in the symbol alert pop-up menu. The
default action is defined in the same way as any other menu
action. Refer to Creating and Using Registration Files on page
39 for instructions on registering menu items and actions for
symbol alerts.
A default action is associated with a symbol alert by the
application at symbol alert creation time.
5. Pop-up menu.
Every alert has a pop-up menu that can be displayed with at least
one menu item-the one for the default action. If there are no
registered pop-up menu items for that symbol alert type, this
menu is not presented.
Applications register menus, menu items and associated actions in
their application registration file. Refer to Creating and Using
Registration Files on page 39 for more information.
Contents of the pop-up menu are determined dynamically using a
variation on the existing run time evaluation of the registered
pop-up menus and items. The evaluation is based on the symbol
alert type, the submap context, and the application.
Implementing Symbol Alerts
An application integrates a symbol alert with the following five steps:
1. Within an application registration file, the developer defines the
actions that can be executed when a user responds to a symbol alert,
defines pop-up menus for each symbol alert type, and links each
menu item to a specific action.
2. The application registers one or more action callback functions for the
symbol alert pop-up menu actions defined within its application
registration file. These callback functions will perform the work
required by each particular action.
3. The application detects a situation or fault and creates a symbol alert
on a specific base symbol. The application specifies the text that
should be displayed within the symbol alert.
4. The user clicks mouse button three on the symbol alert (not the base
symbol) and chooses one of the symbol alert pop-up menu items.
Chapter 7
265

Creating Symbols
5. OVW invokes the applications specific action callback function for the
menu item the user chooses.
NOTE
Symbol alerts are not stored when a map is closed. When the map is
closed all symbol alert information for that map disappears.
Creating the Symbol Alert OVwCreateSymbolAlert() has the

following signature:
int OVwCreateSymbolAlert (OVwMapInfo *mapInfo,
OVwSymbolId baseSymbolId,OVwSymAlertType symAlertType,
char *defaultActionId, char *defaultActionAppId,
char *textAnnotation,
OVwAlertTextAlignment alertTextAlignment);
OVwCreateSymbolAlert() requires the following arguments:

mapInfo specifies a pointer to a map structure for an open map. The
mapInfo parameter can be obtained using OVwGetMapInfo() or saved
from the ovwMapOpen event using OVwCopyMapInfo.
baseSymbolId specifies the symbol ID of the base symbol.
symAlertType specifies the alert type to use for displaying the alert.
Alert type values are defined in the alert type registration files. Refer
to Creating and Using Registration Files on page 39. The value of
symAlertType must be in double quotes like other values of the type
char*.
defaultActionId specifies the default action that is assigned to the
symbol alert. This action must be defined in the application
registration file for the defaultActionAppId. Refer to Creating and
Using Registration Files on page 39.
defaultActionAppId specifies the application that registered the
default action named by the default ActionId.
textAnnotation specifies the text string to display in the alert. The
string may include the newline character. Text is limited to two lines
of twelve characters each. If textAnnotation is set to NULL no text
is provided.
alertTextAlignment indicates how to align the text when it is
displayed in the alerts text region. These may be
266
Chapter 7

Creating Symbols
ovwCenterAlignAlertText, ovwLeftAlignAlertText, and
ovwNoAlertText (must be used when there is no text).
Deleting the Symbol Alert OVwDeleteSymbolAlert() has the
following function prototype:
int OVwDeleteSymbolAlert(OVwMapInfo *map,
OVwSymbolId baseSymbolId);

Setting Symbol Alert Text Annotation OVwSetSymbolAlertText()
lets applications dynamically create or change the contents of a symbol
alerts text region. The function prototype for
OVwSetSymbolAlertText() is:
int OVwSetSymbolAlertText(OVwMapInfo *map,
OVwSymbolId baseSymbolId, char *textAnnotation,
OVwAlertTextAlignment alertTextAlignment);

textAnnotation specifies the text string to display in the alert. The
string may include the newline character. Text is limited to two lines
of twelve characters each. If textAnnotation is set to NULL no text
is provided.
alertTextAlignment indicates how to align the text when it is
displayed in the alerts text region. These may be
ovwCenterAlignAlertText, ovwLeftAlignAlertText, and
ovwNoAlertText (must be used when there is no text).
Registering for Confirmation of Symbol Alert Deletion
Applications can register to handle a symbol alert deletion via
OVwConfirmDeleteSymbolAlertCB(). Because a symbol can have only
one symbol alert at a time and symbol alerts are not queued, it is
possible for an applications symbol alert creation attempt to fail because
there is already a symbol alert on the target base symbol. In this
Chapter 7
267

Creating Symbols
situation, an application can register for the
ovwConfirmDeleteSymbolAlert event. As other applications delete
symbol alerts, OVW will invoke the registered applications callback
function. Within the callback function, the application will test the
symbol_id element within the baseSymbolInfo parameter and
determine whether the symbol alert deletion is from the targeted symbol.
The function prototype for OVwConfirmDeleteSymbolAlertCB()is:
void (*OVwConfirmDeleteSymbolAlertCB) (void *userData,
OVwEventType type,OVwMapInfo *mapInfo,
OVwSymbolInfo *symbolInfo, OVwEventSource source);
userData is the return user data provided when callback was added.
type is the event type which invoked the callback.
mapInfo is the map structure for the open map.
symbolInfo is the OVwSymbolInfo of the symbol whose alert was
deleted.
source returns an OVwEventSource value, as defined in ovw.h. For
OVwConfirmDeleteSymbolAlertCB(), source is always 5
ovwEventSourceApp.
268
Chapter 7

Changing Symbol Appearance and Behavior

Once a symbol exists, there are a number of ways to manipulate it. You
can
change the visual appearance
change the symbol type (the icon or connection graphic)
override OVWs symbol placement algorithms and manually place the
symbol yourself
change the symbol behavior to be explodable or executable
change the symbol label
change the status source for the symbol
set or clear application interest in a symbol.
OVW provides several APIs to let you change type, behavior, label, status
source, application interest, or placement for symbols individually. You
can also use OVwModifySymbol() and OVwModifySymbols() to change
several attributes of one or more symbols with a single API. This section
describes how to perform these operations.
Style considerations may apply to these operations. Refer to the HP
OpenView Application Style Guide for complete guidelines on symbol
manipulation.
Changing a Symbols Appearance

You can use OVwModifySymbols() and OVwModifySymbol() to change
attributes of symbols. OVwModifySymbols has the following function
prototype:
int OVwModifySymbol (OVwMapInfo *map,
OVwSymbolUpdateInfo *symbol);
int OVwModifySymbols (OVwMapInfo *map,
OVwSymbolUpdateList *symbols);
When calling OVwModifySymbols(), you need to supply these arguments:

map to an OVwMapInfo data structure that contains complete map
information. You can use the OVwGetMapInfo() routine to get the
map information.
Chapter 7
269

symbols contains a list of OVwSymbolUpdateInfo items, describing
each symbol to be updated.
symbol points to the OVwSymbolUpdateInfo structure containing the
updated symbol information and the flags indicating which elements
of information to change.
Transparent Symbol Background
Typically an icon symbol has a background shape and an inner shape
(the bitmap). The status of an icon symbol is represented by a color filling
in the background shape. However, an icon symbol that has normal
status can be displayed without a background shape and without a
status color. This is useful for applications that require quick response to
non-normal status conditions, because when the backgrounds of symbols
with normal status are transparent, symbols with non-normal status are
more noticeable.
Note that even when transparency is enabled for a symbol, it is
transparent only while a symbol is large enough to have a bitmap. When
a submap has been resized so that icons are very small, an icon may not
have a bitmap. When that happens, the symbols background shape and
status color will be shown so that it will be visible. Because the generic
symbol does not have an internal bitmap, generic symbols cannot be
displayed as transparent.
Transparent symbols have special behavior during map editing such as
cut/paste and drag/drop. Because transparency requires a normal status
and the status of a moved symbol is dependent on its status source, there
are three scenarios:
1. If a symbol has the status source set to ovwObjectStatusSource,
then a moved symbol will have the same status that it had before it
was moved. Therefore, a transparent symbol with a status source set
to ovwObjectStatusSource will most likely appear as transparent
after it is moved. It will only appear different if the status of the
object changed during the move or shortly after it was moved.
2. If a symbol has the status source set to ovwCompoundStatusSource,
the status of the moved symbol will be determined by the status
propagation algorithm set for the map. Typically, the status will be
the same and the symbol will appear as transparent unless the status
of the other objects changed.
3. If a symbol has the status source set to ovwSymbolStatusSource,
270
Chapter 7

then a moved symbol will have a status of unknown. Therefore, the
symbol will not be transparent when it is moved because it needs a
normal status to be transparent. It will continue to have an unknown
status until an application adopts the symbol.The application may
then set the status to normal and the symbol will become
transparent. If an application never recognizes the symbol it will
remain in an unknown status.
You specify via the OVwModifySymbol and OVwModifySymbols APIs
whether a symbol should be transparent or not on a per-symbol basis.
The update flag is:
ovwUpdateSymbolTransparency
The field in the OVwSymbolInfo structure is:

transparent
A symbol will be transparent if the developer has specified that the

symbol should be transparent and the user has enabled the functionality
in the app- defaults file. If the X resource is not specified in the
app-defaults file, the functionality is enabled by default. The default X
resource for this functionality is:
OVw*enableTransparency:True
A transparent symbol is included in the visual cues portion of the display

legend dialog box.
Executable Symbol Appearance
Typically, an executable symbol is distinguished from an explodable
symbol by having a box around it. This visual cue is optional and can be
disabled. Disabling the visual cue for an executable symbol is useful for
applications that create and display a new submap when a particular
executable symbol is double-clicked. For an end user, this behavior does
not need to be distinguished from an explodable symbol.
Map editing (cut/paste and drag/drop) has no affect on executable symbol
appearance. The moved symbol appears as it was before it was moved. If
it had the visual cue, then it has the visual cue after it is moved. If it
didnt have the visual cue, then it doesnt have the visual cue after it is
moved.
Developers can specify via the OVwModifySymbol and
OVwModifySymbols APIs on a per symbol basis whether the visual cue
for executable symbols is visible. The update flag is:
Chapter 7
271

ovwUpdateSymbolExecVisCue

exec_vis_cue
An executable symbol visual cue is disabled only if the user has the X
resource set to True and the developer has specified that the symbol
should not show the executable cue. The default X resource for this
functionality is:
OVw*enableExecCueRemoval:True
Flashing Symbols
To provide developers additional ability to draw attention to specific
symbols OVW provides capability to set a symbol to flashing. A flashing
symbols appearance alternates between two states. The first state has
the normal status color. The second state displays the symbol with the
background color instead of the status color. The alternation of these two
states does not exceed two flashes per second.
Flashing symbols have special behavior during map editing operations.
Dragging a flashing symbol makes a copy of the symbol on the target
submap; it does not remove the symbol from the original submap. A
message is displayed to inform users that a flashing symbol cannot be
moved to another submap.
Cutting a flashing symbol is denied. If a user attempts to cut a flashing
symbol, OVW displays a message explaining that the operation is not
possible.
Developers can specify symbol flashing via the OVwModifySymbol and
OVwModifySymbols APIs. The update flag is:
ovwUpdateSymbolFlashing

flashing
A symbol will be flashing if the developer has specified that the symbol
should be flashing and the user has enabled the functionality in the appdefaults file. If the X resource is not specified in the app-defaults file, the
functionality is enabled by default. The default X resource for this
functionality is:
OVw*enableFlashing:True
272
Chapter 7

Text Annotation for Symbols
Applications can dynamically superimpose text over icon symbols,
connection symbols and symbol alerts. Text annotations could be used to
indicate pertinent operating information about a symbol that changes
frequently, such as the percentage of available bandwidth through a
router. When using text annotation strings, adhere to the guidelines in
the HP OpenView Application Style Guide.
A text annotation string is centered on its symbol and is displayed on top
of all other visual features of the symbol. Text annotation of a connection
symbol is always displayed horizontally.
A text annotation is scaled with the symbol. However, the text
annotation is displayed only if the scale radius is sufficient for displaying
an icon for the symbol.
The maximum number of characters per line is 12. Lines with more that
12 characters do not automatically wrap to a new line; rather, the
additional characters will be truncated. You can force a line to wrap by
embedding a \n in the text. For example:
"This line\nwill wrap"
Produces the following output:

This line
will wrap
The maximum number of lines of text annotation is 2. If you provide

more than 2 lines of text, when the annotation is displayed; OVW will
display an error message and truncate the text annotation to 2 lines.
You can specify annotation text via the OVwCreateSymbols() API (see
Creating Multiple Symbols with a Single Call on page 254) or the
OVwModifySymbol and OVwModifySymbols APIs.
char *text_annotation
The update flag is:

ovwUpdateTextAnnotationText
The default behavior for text annotation is defined by setting the

following X resources :
Chapter 7
273

displayTextAnnotationBackground
With a value of TRUE displays a text background for
the text annotation string or with a value of FALSE the
text appears directly over the symbol.
textAnnotationBackgroundColor
Defines the fill color for the text background.
textAnnotationColor
Defines the color of the text annotation string.
On the Windows NT operating system, the default behavior is set in the
following key in the Windows registry:
\HEY_LOCAL_MACHINE\SOFTWARE\Hewlett-Packard\OpenView\
Network Node Manager\OVw\Map TextAnno
The following values can be defined:
displayTextAnnotationBackground
TextAnnotationBackgroundColor
textAnnotationColor
tATxt
tAMaxL
tAMaxC
tACentered
Connection Symbol Appearance
For all connection symbols with a width of greater than three pixels, you
can control the appearance of the connection symbol so that it appears
empty, partially filled, or completely filled. By default the connection
symbol will appear completely filled (that is, percent fill equal to 100%).
You can dynamically change connection symbol fill to a value between 0%
and 100%.
NOTE
If you use partially-filled connection symbols in your application, adhere

to the guidelines in the HP OpenView Application Style Guide.
274
Chapter 7

In creating the appearance of a partially filled symbol, you can
dynamically control the following elements:
the percent of connection symbol fill from 0% to 100%
the primary status
Primary status is used to control the color used to present the borders
of the symbol and the amount of the connection that is filled; by
default this is black (normal status).
the secondary status
Secondary status is used to present the unfilled portion of the
connection symbol; by default this is transparent. The transparent
appearance is the normal status color for the secondary status. In
setting the color for the secondary status, developers can only specify
the state associated with the secondary status. This state is then
translated into the appropriate color based on the status.
If the connection symbol has 0% fill, it will appear as two parallel lines in
the primary color with the area between the lines transparent, showing
the underlying background color. If a connection symbol has 100% fill it
will appear as a single line or patterned line presented in the primary
color. If a connection symbol has a percentage fill between these values
(that is, uses partially filled connection symbols) and it is of sufficient
width to display the differences the connection symbol will appear to
have two different horizontally aligned areas, one for each of the status
colors.
Developers can specify the percent fill and secondary status color for a
symbol or symbols via the OVwCreateSymbols() API (see Creating
Multiple Symbols with a Single Call on page 254) or the
OVwModifySymbol and OVwModifySymbols APIs. The update flags are:
ovwUpdateSymbolPercentFull
ovwUpdateSymbolSecondaryStatus
The fields in the OVwSymbolInfo structure is:

percent_full
secondary_status
Changing a Symbols Type

You can change the type of a symbol at any time.You might change a
symbol type to reflect a change in capabilities in the underlying object.
Chapter 7
275

For example, the HP OpenView Windows IP Map application creates a
computer node symbol when it discovers a node on the network. If the IP
Map application later detects that an additional interface has been
added, IP Map can change the symbol type from a computer node to a
computer gateway.
The OVwSetSymbolType() OVw API routine changes the symbol type. It
has the function prototype:
int OVwSetSymbolType(OVwMapInfo *mapInfo,
OVwSymbolId symbolId,
OVwSymbolType symbolType,
unsigned int flags);
You can use application-defined symbol types or you can use the symbol
types provided with OVW. The header file
\OpenView\include\OV\sym_types.h (Windows NT operating system)
or $OV_HEADER/OV/sym_types.h (UNIX systems), which is
automatically included by \OpenView\include\OV\ovw.h (Windows NT
operating system) or $OV_HEADER/OV/ovw.h (UNIX systems), contains
localized string definitions for symbol types shipped with OVW.
Changing a Symbols Position

You can change the position of a symbol at any time using the
OVwSetSymbolPosition() routine. This routine changes the position of
an existing symbol. It has the function prototype:
int OVwSetSymbolPosition(OVwMapInfo *mapInfo,
OVwSymbolId symbolId,
OVwSymbolPosition *position);
The OVwSymbolPosition data structure is described in the Creating a

Symbol section earlier in this chapter. See that section to learn how to
use the OVwSymbolPosition data structure to define symbol position.
Changing a Symbols Behavior

The OVwSetSymbolBehavior() routine changes the behavior of a symbol
on the open map. By default, symbols are explodable. This routine can
make a symbol explodable or executable.
The OVwSetSymbolBehavior() routine has the function prototype:
int OVwSetSymbolBehavior(OVwMapInfo *mapInfo,
OVwSymbolId symbolId, int behavior,
276
Chapter 7

char *appName, char *actionId,
OVwObjectIdList *targetObjects);
The OVwSetSymbolBehavior() routine has the following arguments:

complete map information. You can use the OVwGetMapInfo() routine
to get the map information.
symbolId is the symbol ID of the symbol whose behavior is being
changed.
behavior is set to ovwSymbolExplodable or ovwSymbolExecutable.
appName is the name of an application registered in an application
registration file.
actionId defines the action to be performed by application appName
when the symbol is executed. actionId must be a valid action
registered in the application registration file. Actions are described in
Chapter 2 , Creating and Using Registration Files.
targetObjects is an optional list of object IDs to be used as the
selection list when the action is performed. If NULL, the object
associated with the executable symbol is itself used as the selection
list.
Regardless of whether a symbol is explodable or executable, many of the
symbol characteristics always apply. A symbol always has a status
source, a status value, a symbol position, an association to an object, and
an optional symbol label. Changing symbol behavior does not affect these
characteristics.
For example, an explodable symbol that receives status by object will
continue to receive status by object, even when changed to an executable
symbol. Also, any associations between an underlying object and child
submaps remain in effect when an explodable symbol is changed to an
executable symbol. Users, however, can no longer navigate to the child
submap through the executable symbol.
NOTE
Use care when changing an explodable symbol to an executable symbol.

If the explodable symbol has a child submap attached, making the
symbol executable might make it difficult for users to access the child
submap in the future. If the child submap is accessible only through a
Chapter 7
277

single explodable symbol and that symbol is made executable, users
must resort to using the OVW user interface submap list box to navigate
to the submap.
You can modify the appearance of an executable symbol to make it look

like an explodable symbol. Refer to Executable Symbol Appearance on
page 271.
The following code segment demonstrates how to make a symbol
executable. Assume that the action ID Show Users action is already
defined in the application registration file for the application User
Admin:
#include <OV/ovw.h>
make_executable(symId)
OVwSymbolId symId;
{
int ret;
char *app_name;
char *action_name = "Show Users";
OVwMapInfo *map;
app_name = OVwGetAppName();
ret = OVwSetSymbolBehavior(map, symId, ovwSymbolExecutable,
app_name, action_name, NULL);
free(app_name);
...
}
Note that the OVwGetAppName() routine retrieves the application name

before calling OVwSetSymbolBehavior().
Changing a Symbols Label

You can change a symbols label with the OVwSetSymbolLabel() routine.
The routine has the function prototype:
int OVwSetSymbolLabel(OVwMapInfo *mapInfo,
OVwSymbolId symbolId, char *label);
The OVwSetSymbolLabel() routine is used only to define the label. Use

the OVwSetSymbolType() routine to control whether the label is
displayed.
278
Chapter 7

NOTE
You should use discretion when using this routine. In most cases, an
application should not change a label that has been modified by the user.
It is usually safe to change the label if the application originally set the
label and the user has not modified it (the label still has the value set by
the application). The OVwGetSymbolInfo() routine, which is described
later, can retrieve the symbol label for a given symbol.
Setting or Clearing Application Interest in a Symbol

OVW maintains a list of all applications interested in each symbol. Any
time an application creates a symbol, the list of interested applications is
initially set to contain the name of the application. Other applications
can add their name to the list of applications interested in that symbol.
There are two reasons for applications to express interest in a symbol:
Symbols can take on a different appearance depending on whether an
application has shown interest in the symbol. If one or more
applications are interested in a symbol, the symbol appears in the
application plane of the submap. If no application is interested, the
symbol appears in the user plane.
Applications can search a submap for all symbols that possess a
certain criteria. (These routines will be described later in this
chapter.) In this case, the search can be filtered to only consider those
symbols in which the application has expressed interest. These
search routines are described later.
An application interested in a symbol created by another application
should call the OVwSetSymbolApp() OVw API routine. This routine adds
the calling application to the list of applications interested in the symbol.
The OVwClearSymbolApps() routine clears the application from this list.
These routines have the function prototypes:
int OVwSetSymbolApp(OVwMapInfo *mapInfo,
int OVwClearSymbolApp(OVwMapInfo *mapInfo,
See the OVwSetSymbolApp(3) reference page if you need more

information on these calls.
Chapter 7
279

Changing Status or Status Source

This section describes how to change the status source and the status
value for a symbol. The symbol colors associated with the various status
values were described earlier in this chapter. Refer to Symbol
Characteristics on page 236 at the beginning of this chapter if you need
to review these concepts.
Changing Status Source
In addition to changing the status of a symbol or object, you can also
change a symbols status source. Status source is defined when the
symbol is created, and is changed at a later time using the
OVwSetSymbolStatusSource() routine. It has the function prototype:
int OVwSetSymbolStatusSource(OVwMapInfo, *mapInfo,
OVwSymbolId symboldId, int statusSource);
The statusSource field can contain any of the three status sources
described earlier in this manual: ovwSymbolStatusSource,
ovwObjectStatusSource, or ovwCompoundStatusSource.
You should change status source only for symbols that you create or for
symbols that users add to submaps that you create. Do not change status
source for symbols created by other applications. Further, if end users
have modified the status source for an application-created symbol, you
should not alter the users preference.
Changing the Status Value
You have two ways to set status:
on the symbol if the status source is ovwSymbolStatusSource
on the object if the status source is ovwObjectStatusSource.
You cannot directly set the status for a symbol that has compound status
source. If the symbol has compound status, you can set symbol or object
status only on the contained symbols or objects. As a result, the
compound status may change. The algorithm for determining how to
propagate compound status is managed internally within OVW.
The OVw API routines that set status values on a symbol or object have
the following function prototypes:
int OVwSetStatusOnSymbol(OVwMapInfo *mapInfo,
OVwSymbolId symbolId, OVwStatusType status);
280
Chapter 7

int OVwSetStatusOnObject(OVwMapInfo *mapInfo,
OVwObjectId objectId,OVwStatusType status);
OVwSetStatusOnSymbol() changes the status on the specified symbol

only if the symbol has status source ovwSymbolStatusSource.
OVwSetStatusOnObject() changes the status of an object in the open
map. This call also sets the object status on all symbols that represent
the object and have status source ovwObjectStatusSource.
Neither symbol nor object status can be set on an object that is
unmanaged.
Two list forms of status routines are also available for setting status on
multiple symbols or objects. They are more efficient than making
multiple individual calls, since OVW compound status propagation is
disabled until the status of all entities in the list are set. They have the
int OVwSetStatusOnSymbols(OVwMapInfo *mapInfo,
OVwSymbolStatusList *symbolList);
int OVwSetStatusOnObjects(OVwMapInfo *mapInfo,
OVwObjectStatusList *objectList);
The symbolList and objectList data structures have the same form as
other common list structures in the OVw API. They contain a count of
the number of elements in the list, and a pointer to the first in a
contiguous array of list entries.
Chapter 7
281

Retrieving Symbol Information

This section describes the various OVw API routines that retrieve
symbol information.
OVwSymbolInfo Data Structure

Before describing the routines that retrieve symbol information, it is first
necessary to describe the OVwSymbolInfo data structure. This data
structure is used by most OVw API routines that retrieve symbol
information. It is somewhat complex, as it must be robust enough to
support both icon and connection symbols.
Many of the elements within the OVwSymbolInfo data structure have
already been presented earlier in this chapter. Symbol position, symbol
variety (icon vs. connection), symbol type, symbol status source and other
symbol characteristics are all present in the OVwSymbolInfo data
structure, and their description will not be repeated here.
The OVwSymbolInfo data structure has the following definition.
typedef struct {
/* symbol ID */
/* submap symbol exist on */
OVwObjectInfo object;
/* object represented by symbol */
char *symbol_label;
/* symbol label */
OVwStatusType symbol_status; /* symbol status */
int status_source;
/* status source; see values above */
OVwPlaneType plane;
/* submap plane symbol is on; values below */
OVwBoolean hidden;
/* whether symbol is hidden on submap */
OVwSymbolType symbol_type;
/* symbol type */
int symbol_variety;
/* ovwIconSymbol, ovwConnSymbol */
union {
OVwSymbolPosition position; /* ovwIconSymbol variety */
struct {
/* ovwConnSymbol variety */
OVwSymbolId endpoint1_id; /* first connection endpoint */
OVwSymbolId endpoint2_id; /* second connection endpoint */
OVwBoolean is_meta_conn;
/* meta-connection? */
} conninfo;
} var_un;
#define icon_position
#define conn_endpoint1
#define conn_endpoint2
282
var_un.position
var_un.conninfo.endpoint1_id
var_un.conninfo.endpoint2_id
Chapter 7

#define conn_is_meta_conn
var_un.conninfo.is_meta_conn
int behavior;
/* ovwSymbolExplodable,
ovwSymbolExecutable */
OVwAppList apps;
/* applications interested in symbol */
OVwSymbolBehavior behavior_info; /* Details of symbol behavior */
char *drop_app_name;
char *drop_action;
OVwBoolean exec_vis_cue; /* whether executable symbol has box around it */
OVwBoolean transparent; /* whether symbol is transparent */
OVwBoolean flashing;
/* whether symbol is flashing */
OVwStatusType secondary_status; /* secondary status of a symbol */
int percent_full;
/* the fill percentage of a symbol */
char *text_annotation; /* text annotation text */
OVwSymAlertType symbol_alert_type; /* symbol alert (s alert) type */
char *symbol_alert_creating_app;
/* application that created the s alert */
char *symbol_alert_action_app;
/* s alert default action - app id */
char *symbol_alert_action;
/* s alert default action - action id */
char *symbol_alert_text;
/* s alert text annotation */
OVwAlertTextAlignment symbol_alert_text_alignment;
/* s alert text align */
#endif
} OVwSymbolInfo;
The OVwSymbolBehavior structure contains information specific to the

symbol behavior. Currently, this is used only for executable symbol
information.
typedef struct {
char *symbol_exec_app;
/* Exec. Sym. -- application */
char *symbol_exec_action;
/* Exec. Sym. -- action */
OVwObjectIdList *symbol_exec_targets;
/* Exec. Sym. -- target objects */
} OVwExecutableSymbolBehavior;
typedef struct {
union {
OVwExecutableSymbolBehavior exec;
/* for ovwSymbolExecutable */
} un;
#define exec_app
un.exec.symbol_exec_app
#define exec_action
un.exec.symbol_exec_action
#define exec_targets
un.exec.symbol_exec_targets
} OVwSymbolBehavior;
Most of the fields have already been used in previously described OVw
API symbol routines.
Two fields in particular in this data structure, however, deserve
comment. The symbol_variety field serves as a tag for the union that
follows it (var_un). If the symbol is an icon, then the position field
contains icon-specific symbol information (the symbol position in this
Chapter 7
283

case). If the symbol is a connection, then the conninfo structure defines
connection-specific symbol information.
The is_meta_conn field in the conninfo union indicates whether a
connection symbol is a simple connection or a meta-connection. A metaconnection is a special connection that represents multiple connections
between the two connected symbols. If the symbol is a meta-connection,
the contained simple connections are found on the child submap of the
object represented by the meta-connection.
With the discussion of the OVwSymbolInfo structure complete, the
routines to retrieve symbol information can be described.
Retrieving Symbol Information with

OVwGetSymbolInfo()
The OVwGetSymbolInfo() OVw API routine is a general purpose routine
that can retrieve complete symbol information for any symbol.
Given a symbol ID for any symbol, this routine returns a pointer to an
OVwSymbolInfo data structure containing complete symbol information.
An associated OVwFreeSymbolInfo() OVw API routine frees memory
allocated by the OVwGetSymbolInfo() routine. They have the function
prototypes:
OVwSymbolInfo *OVwGetSymbolInfo(OVwMapInfo *mapInfo,
void OVwFreeSymbolInfo(OVwSymbolInfo *symbol);
The following code segment demonstrates how to use these routines.

#include <OV/ovw.h>
dump_symbol_info(symbol_id)
{
OVwSymbolInfo *p;
OVwMapInfo *map;
p = OVwGetSymbolInfo(map, symbol_id);
if (p == NULL) {
printf("symbol does not exist on the open map\n");
} else {
printf("The symbol with ID %d has the following
values:\n",symbol_id);
printf(" variety: %s\n",
284
Chapter 7

(p->symbol_variety == ovwIconSymbol) ? "icon":
"connection");
printf(" behavior: %s\n",
(p->behavior == ovwSymbolExecutable) ? "executable":
"explodable");
printf(" type: %s\n label: %s\n", (char *) p->symbol_type,
p->symbol_label);
...
OVwFreeSymbolInfo(p);
}
...
}
Note that the application uses OVwFreeSymbolInfo() to free memory

allocated by the OVwGetSymbolInfo() routine.
Getting Connection Symbol Information

The OVwGetConnSymbol() determines if a connection exists between any
two icon symbols. If such a connection exists, the routine returns a
pointer to an OVwSymbolInfo data structure containing complete
connection symbol information.
The routine has the function prototype:
OVwSymbolInfo *OVwGetConnSymbol(OVwMapInfo *mapInfo,
OVwSymbolId endpoint1, OVwSymbolId endpoint2);
The following code fragment shows how to list the connections of a metaconnection submap.
<OV/ovw.h>
...
int i;
OVwSymbolInfo *syminfo;
OVwSymbolList *symlist;
OVwSymbolId from_id, to_id;
syminfo = OVwGetConnSymbol(map, from_id, to_id);
if (!syminfo) {
printf("No connection!\n");
} else if (!syminfo->var_un.conninfo.is_meta_conn) {
printf("Single connection.\n");
/* symbol represents the object syminfo->object */
} else {
Chapter 7
285

printf("Meta-connection.\n");
/* get symbols on meta-connection submap */
symlist = OVwListSymbols(map,
syminfo->object.child_submap_id,
ovwAllPlanes, NULL);
if (symlist) {
for (i=0; i<symlist->count; i++) {
if (symlist->symbols[i].symbol_variety ==
ovwConnSymbol) {
printf("Connection found.\n");
/* symlist->symborols[i].object is object */
}
}
OVwFreeSymbolList(symlist);
}
}
if (syminfo)
OVwFreeSymbolInfo(syminfo);
...
You may specify the special value ovwSubmapBackbone for endpoint2 if

the layout algorithm of the submap is either bus or ring layout.
Getting a List of Symbols from a Submap

Applications frequently need to determine what symbols are present on a
given submap. The OVwListSymbols() OVw API routine provides this
service. You can retrieve a list of all symbols on the submap, or you can
selectively retrieve a list of only those symbols for which your application
has expressed interest or that are on a specific plane. The
OVwListSymbols() routine has the function prototype:
OVwSymbolList *OVwListSymbols(OVwMapInfo *map,
OVwSubmapId submapId,OVwPlaneType plane,
char *appName);
The plane argument may be ovwAppPlane, ovwUserPlane, or

ovwAllPlanes. The appName argument can be either the application
name or NULL. If appName contains the application name,
OVwListSymbols() will return only those symbols for which the
application has expressed interest. If appName is NULL,
OVwListSymbols() will return a list of all symbols in the specified
plane(s).
286
Chapter 7

When finished, you should call OVwFreeSymbolList() to free the
memory allocated by OVW. The OVwFreeSymbolList routine has the
function prototype:
void OVwFreeSymbolList(OVwSymbolList *symbolList);
Symbol Type Routines

The OVw API provides two routines that operate on symbol types.
The OVwListSymbolTypes() routine retrieves a list of all the currently
registered symbol types. This routine is useful for programmatically
determining which symbol types are available.
The OVwListSymbolTypeCaps()routine returns a list of the capabilities
that would be set if the user added an object to the map using a specific
symbol type.
These routines are not used extensively and are not described here. See
the reference pages if you need more information on these routines.
Chapter 7
287

Retrieving Object Information

Objects are internal representations of logical or physical resources or
entities that exist on a network. Object information is maintained in the
OVW object database and is available to all maps. An object can be
represented by multiple symbols, even by symbols on different maps.
There are, however, some attributes of objects that are not maintained
globally. Some object attributes apply only to the map on which that
object appears. For instance, recall from a previous section in this
chapter that symbols can receive their status from the underlying object
they represent. When applications set status for an object, the status is
set only for the object on the open map. Setting status on that object does
not affect the status of the same object on another map. Object status is
an example of an attribute that is map-specific.
There are a number of other map-specific object attributes as well. These
map-specific object attributes, and the routines that operate on them, are
described in this section.
The OVwObjectInfo Data Structure

The OVwObjectInfo data structure stores map-specific object
information. This data structure is used by OVw API routines that
retrieve map-specific object information. The OVwObjectInfo data
structure has the following definition.
typedef struct {
OVwSubmapId child_submap_id;
int num_symbols;
OVwStatusType object_status;
OVwStatusType compound_status;
int op_scope;
OVwFieldBindList *field_values;
} OVwObjectInfo;
/*
/*
/*
/*
/*
/*
/*
object ID */
child submap of object */
number of symbols on open map */
object-specific status */
compound (propagated) status */
ovwNotApplicable, ovwOpenMapScope,... */
object capability field values */
Note that all of the fields in this structure are map-specific. In other
words, these fields apply only to the object as it relates to the current
map. They do not apply to instances of the object on other maps. Most of
the fields in the data structure are self-explanatory. Two fields, however,
require further description.
288
Chapter 7

The op_scope and field_values fields have special uses that are not
apparent from their names. Both fields are used to provide particular
information to callback routines when specific events occur. The
op_scope field indicates the scope of delete operations. The
field_values field is used to supply certain object fields to an
application callback routine for ovwConfirmCapabilityChange and
ovwConfirmDeleteObjects events.
The\OpenView\include\OV\ovw.h (Windows NT operating system) or
$OV_HEADER/OV/ovw.h (UNIX systems) include file contains the
definition for the OVwObjectInfo data structure, as well as additional
comments about the fields and how they are used.
Retrieving Object Information with

OVwGetObjectInfo()
The OVwGetObjectInfo() OVw API routine retrieves map-specific object
information for any object. Given an object ID, this routine returns a
pointer to an OVwObjectInfo data structure containing complete mapspecific object information. An associated OVwFreeObjectInfo() OVw
API routine frees memory allocated by the OVwGetObjectInfo()
routine. They have the function prototypes:
OVwObjectInfo *OVwGetObjectInfo(OVwMapInfo *mapInfo,
OVwObjectId objectId);
void OVwFreeObjectInfo(OVwObjectInfo *object);
Note that OVwGetObjectInfo() returns only the map-specific

information relating to an object. If you need global object information,
you might need to use the OVwDbGetFieldValues() OVw API routine.
See Chapter 5 , Creating and Using Objects and Fields, for information
about OVw API routines that apply to the global attributes of objects.
Getting Symbol IDs Associated with an Object

The OVwGetSymbolsByObject() OVw API routine is useful for getting a
list of all the symbols that represent a given object on the open map.
For instance, consider the use of a selection list in a callback routine.
When OVW invokes a callback routine, it supplies a copy of the current
selection list. The selection list is in the form of a list of object IDs. You
can use the OVwGetSymbolsByObject() routine to convert the list of
object IDs to a list of all symbols that represent the given object.
Chapter 7
289

The OVwGetSymbolsByObject() routine has the following function
prototype:
OVwSymbolList *OVwGetSymbolsByObject(OVwMapInfo *mapInfo,
It returns a pointer to a standard OVw API list structure, composed of an

integer count of the number of entries in the list and a pointer to the first
in a contiguous array of list entries.
You should free the dynamically-allocated memory with
OVwFreeSymbolList() when you are finished.
For information about the use of OVwGetSymbolsByObject()in transient
submaps, refer to Considerations for Transient Submap Applications
on page 312.
Getting a List of All Objects on a Map

The OVwListObjectsOnMap() OVw API routine is useful for getting a
list of all the objects that are present on the open map. The
OVwListObjectsOnMap() routine has the following function prototype:
OVwObjectList *OVwListObjectsOnMap(OVwMapInfo *mapInfo,
OVwFieldBindList *fieldValues);
The OVwListObjectsOnMap() routine returns a pointer to an

OVwObjectList structure. The OVwObjectList structure is a standard
OVw API list structure, composed of an integer count of the number of
entries in the list and a pointer to the first in a contiguous array of list
entries.
The fieldValues argument is an optional argument that OVW uses to
filter the list of objects returned by the OVwListObjectsOnMap() routine.
If field_values is specified, OVW filters the list of returned objects to
include only those objects that have the specified field values. If
field_values is NULL, OVW returns a list of all objects in the open
map.
Call OVwFreeObjectList() routine to free the dynamically allocated
memory when you are finished.
For information about the use of OVwGetSymbolsByObject()in transient
submaps, refer to Considerations for Transient Submap Applications
on page 312.
290
Chapter 7

Global Attributes Versus Map-Specific Attributes

For the most part, developers do not need to be concerned with whether
an object attribute is global or map-specific. When setting attributes, the
OVw API routines take care of setting the appropriate global or
map-specific object attributes. For example, when calling the
OVwSetStatusOnObjects() routine, OVW automatically sets the mapspecific object attribute. The developer does not need to make the
distinction between the global or map-specific attributes of the object.
When retrieving object attributes, however, the developer must
understand the distinction between global and map-specific attributes. If
the application needs global attribute information, then the developer
should use the OVwDbGetFieldValues() or related routine. Those
routines are described in Chapter 5 , Creating and Using Objects and
Fields. When retrieving map-specific information, the developer should
use the OVwGetObjectInfo() routine or another routine presented in
this section.
Chapter 7
291

Summary
Summary
This chapter described how to use the OVw symbol routines to create,
manipulate, and delete symbols.
The distinction between symbols and objects was reviewed. Important
symbol characteristics were described, including symbol type, variety,
behavior, position, and status. Symbol creation was presented, both for
icon and connection symbols. Examples showed how to use
OVwCreateSymbol() to create an icon symbol with the default position.
Later, sequence and coordinate symbol position were described, as were
the symbol flags.
Various OVw API symbol routines were presented that change symbol
appearance or behavior. These included routines to change symbol
position, symbol label, symbol behavior, symbol type, symbol status, and
symbol status source.
The chapter described how to retrieve symbol information using the
OVwGetSymbolInfo() routine and various other related routines. The
chapter concluded by describing how to retrieve map-specific object
information. Objects have both global and map-specific object attributes.
The map-specific object attributes include object status, the submap ID
for a child submap, and the compound status of the object.
292
Chapter 7
Map Editing and Map Events
293
This chapter introduces the OVw API map editing routines. Map editing
routines support applications in interacting with end users who perform
such operations as adding objects, creating submaps, or deleting
symbols.
You should read this chapter if your application needs to be notified
when users or other applications modify the map, or if your application
supports any of the four map editing operations (that is, you have
registered enroll blocks in your applications application registration
file).
This chapter addresses these topics:
receiving notification of map changes
participating in map changes
cut and paste operations
drag and drop operations (HP-UX and Solaris only)
how to participate in map locates
considerations for transient submaps.
294
Chapter 8

Receiving Notification of Map Changes

Recall from Chapter 4 , Using the HP OpenView Windows API, that
applications can register callback routines that are invoked when specific
OVW events occur. A number of OVW events have already been
described earlier in this manual, including the ovwMapOpen,
ovwMapClose, and ovwEndSession events. There are many other
map-related events that applications might also find interesting. OVW
generates an event anytime the following conditions occur:
The map is opened or closed.
A symbol, object, or submap is created.
A symbol, object, or submap is deleted.
A symbol is moved.
The selection list is changed.
The status value of a symbol or object is changed.
An object capability field is changed.
The user indicates that an object should be managed/unmanaged.
A symbol is hidden or unhidden.
Applications register callback routines using the OVwAddCallback()
routine. (Callback registration was described in detail in Chapter 4 ,
Using the HP OpenView Windows API. Refer to that chapter if you
need to review how to register callback routines). The next section
describes the OVW map editing events that you can register for using the
OVwAddCallback() routine.
Map Editing Events

The \OpenView\include\OV\ovw.h (Windows NT operating system) or
$OV_HEADER/OV/ovw.h (UNIX systems) header file contains a complete
set of definitions for OVW events, as well as the function prototypes for
their respective callback routines. A specific function prototype exists for
each callback routine.
Table 8-1 summarizes the map editing events.
Chapter 8
295

Table 8-1
OVW Events and Callback Routines

Event Type
Event Meaning/Name of Function Prototype for

Corresponding Callback Routine
ovwEndSession
OVW terminated. (*OVwEndSessionCB)(...)
ovwSelectionListChange
The selection list changed.

(*OVwSelectionListChangeCB)(...)
ovwMapOpen
A map was opened. (*OVwMapOpenCB)(...)
ovwMapClose
A map was closed. (*OVwMapCloseCB)(...)
ovwConfirmDeleteSymbols
One or more symbols were deleted from the map.

(*OVwConfirmDeleteSymbolsCB)(...)
ovwConfirmDeleteObjects
One or more objects were deleted from the map.

(*OVwConfirmDeleteObjectsCB)(...)
ovwConfirmDeleteSubmaps
One or more submaps were deleted from the map.

(*OVwConfirmDeleteSubmapsCB)(...)
ovwConfirmCreateSymbols
One or more symbols were created on the map.

(*OVwConfirmCreateSymbolsCB)(...)
ovwConfirmCreateObjects
One or more objects were created on the map.

(*OVwConfirmCreateObjectsCB)(...)
ovwConfirmCreateSubmaps
One or more submaps were created on the map.

(*OVwConfirmCreateSubmapsCB)(...)
ovwConfirmMoveSymbol
A symbol was moved within a submap.

(*OVwConfirmMoveSymbolCB)(...)
ovwConfirmManageObjects
One or more objects became managed on the map.

(*OVwConfirmManageObjectsCB)(...)
ovwConfirmUnmanageObjects
One or more objects became unmanaged on the map.

(*OVwConfirmUnmanageObjectsCB)(...)
ovwConfirmHideSymbols
OVW made one or more symbols hidden.

(*OVwConfirmHideSymbolsCB)(...)
296
Chapter 8

Table 8-1
OVW Events and Callback Routines

Event Type
Event Meaning/Name of Function Prototype for

Corresponding Callback Routine
ovwConfirmUnhideSymbols
OVW made one or more symbols unhidden.

(*OVwConfirmUnhideSymbolsCB)(...)
ovwConfirmSymbolStatusChange
The status of one or more symbols changed.

(*OVwConfirmSymbolStatusChangeCB) (...)
ovwConfirmObjectStatusChange
The object status of one or more objects changed.

(*OVwConfirmObjectStatusChangeCB) (...)
ovwConfirmCompoundStatusChange
The compound status of one or more objects changed.

(*OVwConfirmCompoundStatusChangeCB)
(...)
ovwConfirmCapabilityChange
The capability field of one or more objects changed.

(*OVwConfirmCapabilityChangeCB)(...)
As you can see from the table, the names of the callback routine function
prototypes are derived from the event name. For example, the
ovwConfirmSymbolStatusChange event has the callback routine
(*OVwConfirmSymbolStatusChangeCB)(). This naming convention lets
you easily translate between event types and function prototypes.
The concepts behind most of these events have been presented earlier in
this manual. Object, symbol, and submap creation, deletion, and
modification are described in previous chapters. You can refer to those
chapters if you need to review those operations. There are, however, two
new concepts that have not been described yet hidden symbol events
and unmanaged object events. These are described next.
Hidden Symbol Events

There are some situations in which the user might not want a symbol to
appear in submaps, but, for some reason, the application will not allow
the symbol to be deleted. In this case, the user can hide the symbol using
the hide operation in the OVW user interface. Though the symbol still
exists, it is no longer presented in the OVW user interface. When a
symbol is hidden, OVW sends the ovwConfirmHideSymbols event to all
applications that have
Chapter 8
297

registered a callback routine for that event, and
registered their interest in that particular symbol.
A hidden symbol is not deleted. The symbol still exists and can be
operated upon by applications just as if the symbol were visible.
Applications can still perform all symbol-related operations, such as
modifying symbol attributes or retrieving symbol information. (For
example, an application might not want to consider a hidden symbol
when performing application-specific status propagation, since hidden
symbols should not contribute to compound status.) It is up to an
application to determine whether to consider a hidden symbol when
performing application-specific status propagation. A compound status
state which includes hidden symbols may be confusing to users.
Users can request that a hidden symbol be made visible again. When a
user selects this operation, OVW will send an
ovwConfirmUnhideSymbols event to all registered applications. This
operation is limited to either none or all of the hidden symbols in a
submap or map. Hidden symbols cannot be made visible individually.
Manage/Unmanage Events
Through the OVW user interface, users can control whether an object is
managed. Applications can dynamically manage and unmanage objects
via the OVW API (see Managing Objects on page 313). Symbols
representing unmanaged objects do not receive status updates from
applications. Applications will receive errors if they attempt to change
the status on an unmanaged object or on the symbol that represents the
unmanaged object. An unmanaged object remains unmanaged until it is
explicitly re-managed through the OVW user interface or the
OVwManageObject() or OVwManageObjects() API. The manage and
unmanage operations are disabled during map synchronization.
All symbols representing an unmanaged object have the same status
color to reflect the unmanaged status. By default, unmanaged icon
symbols are off-white in color, and unmanaged connection symbols are
black. See Chapter 7 , Creating and Using Symbols, if you need more
information about status colors and their meaning.
Note that all symbols representing an object on a particular map,
regardless of the symbol status source, are changed to unmanaged status
if the underlying object is unmanaged.
By registering for the ovwConfirmUnmanageEvent, applications can
298
Chapter 8

determine if the object is currently managed on any other maps that
might exist. Applications can examine the op_scope field in the
OVwObjectInfo data structure to see if the object is still managed on any
other maps. (The op_scope value will be ovwAllMapsScope if the object
is being unmanaged on the last map on which it was managed.)
Applications can discontinue monitoring the object in the future if it is no
longer being managed on any map.
An Event Handling Example

The following example shows how an application might define a callback
routine to handle the creation of a symbol by another application.
#include <OV/ovw.h>
void *create_symbol_CB(userData, type, map, symbolList)
void *userData;
OVwEventType type;
OVwSymbolList *symbolList;
{
...
}
main()
{
int ret;
printf("application couldn't connect to OVW\n");
exit(1);
}
ret = OVwAddCallback(ovwConfirmCreateSymbols, NULL,
(OVwCallbackProc) create_symbol_CB, NULL);
if (ret < 0) {
}
OVwMainLoop();
}
This example shows how an application passively awaits notification

that an event has occurred. The application does not control whether the
symbol creation is allowed it is notified that the event occurred. The
next section describes how applications can actively interact with OVW
to control whether certain map editing operations are allowed.
Chapter 8
299

Participating in Map Changes

In many cases, applications must actively participate in a dialog with
OVW to control whether map editing changes are allowed. OVW might
need to consult the application and gain application permission before a
user operation may be allowed.
Map Editing Interactions with OVW

Specifically, OVW attempts to establish a dialog with an application
anytime the user performs one of four OVW map editing operations:
adding a symbol
changing the application configuration for the map
connecting two symbols
modifying an objects attributes.
Whenever a user performs one of these four OVW map editing
operations, the user will be presented with a dialog box. The structure of
the dialog box is defined by the enroll block definitions in the
applications ARF. Here is how the process works:
1. The user sets or changes the value of a field in a dialog box.
2. The user presses the [Verify] button. OVW sends a query event to
the responsible application to verify that the changes are acceptable.
The application must have already registered a callback routine,
called a Query callback routine, which determines if the user
changes are valid.
3. The applications query callback routine checks to see if the dialog box
fields are valid. The application synchronously calls an OVW routine
with a Boolean indication whether the dialog box fields are
acceptable. The application can also return a message that will be
displayed in an Application Message field in the dialog box. The
message field can explain to users why the fields were not accepted.
The OVW routine called by the application is known as a Verify
routine.
4. Depending on the applications response, OVW may enable the [OK]
button to allow the user to proceed. If the application does not accept
300
Chapter 8

the fields, the [OK] button remains disabled. The user should reenter
new values and start the process over. If the application accepts the
fields, OVW enables the [OK] button. At this point, the user can
cancel the operation or press [OK] to proceed.
5. If the user presses [OK] on both the application-specific dialog box
and the main dialog box for the operation, OVW performs the
operation. OVW sends a confirm event to the application, confirming
that the operation was performed. The application callback routine
that handles the confirm event is called the Confirm callback
routine.
This handshaking mechanism between OVW and the application is
known as the Query-Verify-Confirm sequence. There is a separate
Query-Verify-Confirm sequence for each of the four map operations.
NOTE
For this form of map editing to work correctly, an application must have:
1) defined one or more enroll blocks in the ARF, and 2) registered both
Query and Confirm callback routines. If an enroll block does not exist,
OVW cannot construct the application-specific dialog box. If the callback
routines are not registered, OVW cannot communicate with the
application.
The following diagram shows the transactions between OVW and an

application when a symbol is added to a submap. The actual events and
functions necessary to add a symbol are described later. For now, simply
note the series of transactions between OVW and the application
responsible for approving the operation.
Chapter 8
301

Figure 8-1
Query-Verify-Confirm Transactions
User Action
Time
User presses
[Verify] or
dialog box is
enrolled for
automatic
verification.
Responsible Application
OVwQueryAddSymbol event
Other Applications
Application checks if
user-supplied
information is valid.
Application responds to
OVW, setting a lag to
indicate if the valid.
If the fields are

OVwVerifyAdd() call
invalid, the user
can start over. If
the fields are
valid and the
OVwConfirmAddSymbol event
user wants to
Application receives confirmation
that the operation was completed.
proceed, he can
press [OK].
OVW will
complete the
Application receives
operation and
confirmation that the
OVwConfirmCreateSymbol event
send an event to
operation was
the application.
completed.
Query-Verify-Confirm Routines
The following list contains the callback routine and verify routine
function prototypes that apply for each of the four map operations. The
function prototypes are grouped by map operation.
302
Chapter 8

Adding a Symbol
void (*OVwQueryAddSymbolCB)(void *userData, OVwEventType type,
OVwMapInfo *mapInfo, OVwSubmapInfo *submap,
OVwFieldBindList *capabilityFields,
OVwFieldBindList *dialogBoxFields);
int OVwVerifyAdd(OVwMapInfo *mapInfo,
OVwFieldBindList *dialogBoxFields,OVwBoolean verified,
OVwBoolean appPlane, char *errorMsg);
void (*OVwConfirmAddSymbolCB)(void *userData,
OVwSymbolInfo *symbol,
Changing the Application Configuration

void (*OVwQueryAppConfigCB)(void *userData, OVwEventType type,
OVwMapInfo *mapInfo, OVwFieldBindList *configParms);
int OVwVerifyAppConfigChange(OVwMapInfo *mapInfo,
OVwFieldBindList *configParms,OVwBoolean verified,
char *errorMsg);
void (*OVwConfirmAppConfigCB)(void *userData,
OVwFieldBindList *configParams);
Connecting Two Symbols

void (*OVwQueryConnectSymbolsCB)(void *userData, OVwEventType
type,OVwMapInfo *mapInfo, OVwSubmapInfo *submap,
OVwObjectInfo *object1,OVwObjectInfo *object2,
int OVwVerifyConnect(OVwMapInfo *mapInfo,
OVwObjectInfo *object1,
OVwObjectInfo *object2,OVwFieldBindList *dialogBoxFields,
OVwBoolean verified,OVwBoolean appPlane, char *errorMsg);
void (*OVwConfirmConnectSymbolsCB)(void *userData,
OVwSymbolInfo *symbol,
OVwObjectInfo *object1,OVwObjectInfo *object2,
Chapter 8
303

Changing the Object Description
void (*OVwQueryDescribeCB)(void *userData, OVwEventType type,
OVwMapInfo *mapInfo,OVwObjectInfo *object,
int OVwVerifyDescribeChange(OVwMapInfo *mapInfo,
OVwObjectInfo *object,OVwFieldBindList *dialogBoxFields,
OVwBoolean verified, char *errorMsg);
void (*OVwConfirmDescribeCB)(void *userData,
OVwEventType type, OVwMapInfo *mapInfo,
OVwObjectInfo *object,
If your application supports any of these four map operations, you should
register the appropriate enroll blocks in your applications ARF, as well
as registering the appropriate callback routines.
NOTE
If your application registers for any of the query callback routines, your
application must call the associated OVW verify routine as part of the
query callback processing. Users may experience unnecessary delays if
your application does not call the verify routine as part of query event
processing.
See the reference pages if you need more information about these calls.
The following short code segments show how to use the Query-VerifyConfirm routines. This example shows how an application might handle
Describe operations. Assume the following entry is present in the
applications application registration file:
Application "User Management" {
...
Enroll Describe {
if isUser {
Field "User Name" {
EditPolicy NoEdit;
}
Field "Default Shell" {
}
Field "User Information" {
}
}
}
304
Chapter 8

...
}
The next code segment registers callback routines to handle editing

interaction with OVW. Note that the dialog box fields are passed to the
callback routines in OVwFieldBindList data structures, which were
described in Chapter 5 , Creating and Using Objects and Fields. The
fields supplied with the query and confirm events correspond to the fields
enrolled in the application-specific dialog box.
#include <OV/ovw.h>
void *my_Describe_Query_CB(userData, eventType, map, object,
dialogBoxFields)
void *userData;
OVwEventType eventType;
OVwObjectInfo *object;
OVwFieldBindList *dialogBoxFields;{
int ret;
/* Check the validity of the dialog box fields. Depending on */
/* the result, return either success or failure back to OVW. */
if (/* the operation is valid */)
ret = OVwVerifyDescribeChange(map, object, dialogBoxFields,
TRUE, NULL);
else
ret = OVwVerifyDescribeChange(map, object, dialogBoxFields,
FALSE,"operation not valid");
}
void *my_Describe_Confirm_CB(userData, eventType, map, object,
dialogBoxFields)
void *userData;
OVwEventType eventType;
OVwObjectInfo *object;
OVwFieldBindList *dialogBoxFields;
{
/* Operation completed successfully; perform any */
/* application specific operations */
}
main() {
int ret;
Chapter 8
305

printf("error connecting to OVW\n");
exit(1);
}
ret = OVwAddCallback(ovwQueryDescribeChange,
(OVwCallbackProc) my_Describe_Query_CB, NULL);
ret = OVwAddCallback(ovwConfirmDescribeChange,
(OVwCallbackProc) my_Describe_Confirm_CB, NULL);
OVwMainLoop();
}
Choosing Which Confirm Event to Use

If you carefully read previous sections in this chapter, you will note that
applications can receive confirmation of the Add or Connect map-editing
operations in not one, but two ways. Applications can register for the
specific ovwConfirmAddSymbol or ovwConfirmConnectSymbol events
that correspond to the Query-Verify-Confirm routines, or they can
register for the more generic ovwConfirmCreateSymbols event. For
example, an application that wants to receive notification that a symbol
has been added to a submap can register either the
(*OVwConfirmAddSymbolCB() callback routine or the
(*OVwConfirmCreateSymbolsCB)() callback routine. They are invoked
through different events, with different function prototypes and
arguments.
Your choice of which confirm event to use is largely based on:
the way the symbol is created
the arguments that are supplied to the callback routines.
The generic ovwConfirmCreateSymbols event is generated regardless of
how the symbol is created (by the user through the user interface or by
another application through the OVw API). The same event is generated
when either an icon or connection symbol is added. In contrast, the
ovwConfirmAddSymbol and ovwConfirmConnectSymbol events are
generated only when icon and connection symbols are created,
respectively, by the user through the map-editing features of the OVW
user interface.
Another difference is that the ovwConfirmCreateSymbols event can be
associated with the creation of multiple symbols. The
ovwConfirmAddSymbol and ovwConfirmConnectSymbol events are
associated with a single symbol.
306
Chapter 8

The data returned to the callback routines differ between the generic
ovwConfirmCreateSymbols event and the specific
ovwConfirmAddSymbol and ovwConfirmConnectSymbol events. For
example, compare the two function prototypes below:
void (*OVwConfirmAddSymbolCB)(void *userData,
OVwEventType type,
OVwMapInfo *mapInfo, OVwSymbolInfo *symbol,
void (*OVwConfirmCreateSymbolsCB) (void *userData,
OVwSymbolList *symbolList,OVwEventSource source);
Note that the arguments to the (*OVwConfirmAddSymbolCB)() callback

routine provide complete, detailed information about the single symbol
affected by the operation. The callback routine also receives a pointer to
the complete list of object database fields enrolled by the calling
application. On the other hand, the more generic
(*OVwConfirmCreateSymbolsCB() routine contains a pointer to a
symbol list, which the application must traverse to inquire about the
affected symbols. The generic (*OVwConfirmCreateSymbolsCB)()
routine does not provide access to application-specific object database
fields. It is the applications responsibility to get these values if they are
needed.
If you refer back to Figure 8-1, youll note that two different applications
received different events indicating that the operation was completed.
Specifically, the application that approved the user operation received
the ovwConfirmAddSymbols event, while a second application received
the ovwConfirmCreateSymbols event. Each of those two applications
might have been designed to receive the other Confirm event, provided
that the callback routine parameters contain the desired information.
Deleting a Symbol
Symbol deletion through the user interface uses the
Query-Verify-Confirm transaction, though in a slightly different way.
Unlike the dialog boxes presented in the other map operations, the delete
symbol dialog box does not have a [Verify] button. Users can simply
press [OK] to proceed, or [Cancel] to cancel the symbol deletion.
If the user presses [OK], OVW sends the ovwQueryDeleteSymbol event
to all applications registered for the event. The applications then
Chapter 8
307

respond with a Boolean value indicating whether the symbol can be
deleted.
If all of the registered applications approve, the symbol is deleted and
OVW sends the ovwConfirmDeleteSymbol event to all applications
registered for that event.
If one or more applications do not approve, OVW does not delete the
symbol. OVW informs the user that the symbol cannot be deleted. At
that point, the user can choose to hide the symbol.
The symbol deletion Query-Verify-Confirm routines have the following
void (*OVwQueryDeleteSymbolsCB) (void *userData,
OVwSymbolVerifyList *symbolVerifyList,
int OVwVerifyDeleteSymbol(OVwMapInfo *mapInfo,
OVwSymbolVerifyList *symbolVerifyList);
void (*OVwConfirmDeleteSymbolsCB) (void *userData,
OVwSymbolList *symbolList, OVwEventSource source);
If your application creates symbols, you should also consider whether

your application needs to handle symbol deletion. An application should
disallow symbol deletion only if the symbol is required for correct
operation.
308
Chapter 8

Participating in Map Locates In Transient Map Applications
Participating in Map Locates In Transient

Map Applications
This section applies to transient map applications applications that
create submaps on user request.
If your application creates submaps only when the user requests them,
you need to be sure you also help the user locate objects and symbols that
have not yet been placed on the map. OVW provides a simple protocol so
that, in response to user locate requests, you can list symbols and objects
that meet the locate criteria but have not yet been created on the map.
Returning Locate Results

Once a locate callback is triggered in your application, OVW will wait for
your application to return the results of the locate query. This is similar
to the map close callback/acknowledgment protocol in that OVW waits
until it times out for your application to acknowledge the locate request
before continuing.
The OVwReturnLocateResults API is used to return to OVW your
applications response to a user locate query. This single API is used to
return results for all locate queries.
int OVwReturnLocateResults(OVwMapInfo *mapInfo, int requestId,
char *errorMessage, OVwLocateResultList *list);
Your application should call this with an OVwLocateResultList that

contains the objects resulting from users locate query.
OVwLocateResultList is declared as follows:
/*
* Structures for Locate protocol
*/
typedef struct {
OVwObjectId
object_id;
OVwObjectId
submap_parent_id;
/*Located object */
/*Parent obj of submap
where the object exists */
} OVwLocateResultObject;
typedef struct {
int count;
/* number of items on list */
OVwLocateResultObject *results;/* contiguous list of items */
} OVwLocateResultList;
Chapter 8
309

Each callback provides information specific to the kind of locate
operation the user has performed. Table 8-2 shows what information
about the locate query the callback receives and what OVW expects your
application to return. See the Section 3 reference pages for each specific
callback type for more detail on the callback functionality.
Table 8-2
Locate Query Callback Information

Callback
Information Received
Information Returned
OVwAttributeLocateCB
List of all object ids of objects

in the object database
matching the user query.
That subset of objects from

the supplied list which your
application will place on the
map.
OVwSymbolStatusLocateCB
The status value of symbols

for which the user is
searching.
A list of objects which would

have a symbol on the map
matching the queried status.
OVwSymbolTypeLocateCB
The name of the symbol type

of symbols for which the user
is searching.
A list of objects which would

have a symbol on the map of
the specified symbol type.
OVwSymbolLabelLocateCB
The label of the symbol for

which the user is searching.
The list of objects which

would have a symbol on the
map with the specified symbol
label.
Locating Symbols
NNM provides functionality to programmatically locate symbols within
the OVW object database. This functionality duplicates the locate
functionality available from the OVW GUI.
The OVwLocateBySelectionName(), OVwLocateByAttribute(),
OVwLocateBySymbolStatus(), OVwLocateByComment(),
OVwLocateBySymbolType(), and OVwLocateBySymbolLabel() routines
return a list of symbol or object locations that match the search criteria.
The OVwLocateResultSymbol() structure describes the located symbol
or object:
typedef struct {
OVwSymbolID symbol_id;
310
Chapter 8

}
OVwLocateResultSymbol;
The OVwLocateResultObject structure describes the located object and

its parent submap.
typedef struct {
OVwObjectId
object_id;
OVwObjectID
submap_parent_id;
} OVwLocateResultObject;
The OVwLocateResultInfo structure contains a single locate result.This

structure can contain either symbol or object location information. The
type field specifies the type of information contained in the locate result.
typedef struct {
int type;
union {
OVwLocateResultObject object_result;
OVwLocateResultSymbol symbol_result;
} locate;
} OVwLocateResultInfo;
The OVwLocateResultInfoList structure contains a list of locate

results:
typedef struct {
int
count;
OVwLocateResultInfo *results;
} OVwLocateResultInfo
The caller is responsible for freeing the returned list

(OVwLocateResultInfoList). OVwFreeLocateResultInfoList() frees
the list returned by any of these OVwLocate routines.
NOTE
If you want your application to use Locate APIs before ipmap is started,
then the application should register for ovwAttributeLocate events
even if it does nothing in the callback function handling the event.
Chapter 8
311

Considerations for Transient Submap Applications
Considerations for Transient Submap

Applications
An application that creates submaps on demand should consider the
problem of what belongs in a submap when the submap is created (that
is, in response to the ovwConfirmCreateSubmaps event), and should deal
correctly with the submap being destroyed (the
ovwConfirmDeleteSubmaps event). The application should be prepared
to deal with these events over and over, since submaps will be created
and destroyed as often as they are opened and closed in the map.
Applications should be written to understand that a transient submap
does not contain a completely populated map at any one instant in time.
The OVwListSubmaps, OVwGetSymbolsByObject, or
OVwListObjectsOnMap API calls return submaps and objects that
currently exist on the map, not the complete set of submaps and objects
that will ever exist on the map.
Applications should avoid using compound presentation status. They
should manage status themselves on a per-symbol basis. If they must use
compound status, they should minimize the number of levels they
require to be persistent.
312
Chapter 8

Managing Objects
Managing Objects
OVW provides several APIs to let you programmatically manage or
unmanage an object or list of objects on a map. Unlike the object
management functionality available to operators via the user interface,
these calls are not recursive; that is. they do not manage or unmanage
objects contained in the child submap of an object managed via these
calls.
The signatures for OVwManageObject() and OVwManageObjects() are:
int OVwManageObject(OVwMapInfo *mapInfo,
int OVwManageObjects(OVwMapInfo *mapInfo,
OVwObjectManageList *objects);
When calling OVwManageObject() and OVwManageObjects(), you need

to supply the following arguments:
map parameter can be obtained using OVwGetMapInfo, or saved from
the ovwMapOpen event using OVwCopyMapInfo.
objectId specifies the object ID of the object to manage.
objects is a pointer to a list of the object IDs of the objects to
manage.
Use OVwUnmanageObject() and OVwUnmanageObjects() to unmanaged
the managed objects.
Chapter 8
313

Cut and Paste Operations

Applications can receive various events when users perform cut and
paste operations through the OVW user interface. Applications receive
the conventional ovwQueryDeleteSymbols event and
ovwConfirmCreateSymbols events with OVwEventSource set to
ovwEventSourceUserCut and ovwEventSourceUserPaste, respectively.
Because a cut and paste sequence appears to an application as unrelated
symbol delete and symbol add events, the event source provides a hint
that an event may be more complex than a simple delete or add.
When OVW performs the cut operation, it enters into a Query-VerifyConfirm transaction sequence with registered applications with the
event source set to ovwEventSourceUserCut. Depending on how the
applications respond in their verify calls, the symbol may or may not be
deleted. When the symbol is pasted, OVW sends an
ovwConfirmCreateSymbols event with an event source of
ovwEventSourceUserPaste to all applications registered for that event.
The applications can examine the symbol and, if desired, they can move
the symbol from the user plane to the application plane by calling the
OVwSetSymbolApp() OVw API routine.
An application that receives an ovwConfirmDeleteSymbols with the
event source set to ovwEventSourceUserCut will need to buffer
information about the deleted symbol because the information might be
needed later for a subsequent ovwConfirmCreateSymbols with the event
source of ovwEventSourceUserPaste.
Not all applications will need to buffer information about the last symbol
deleted. If your application does not distinguish between the paste and
add operations, you might not need to buffer any information about the
previous deletion. You might be able to treat the paste and add
operations similarly.
If your application treats the paste operation and the add operations
differently, the event source provides the hint that you might need to
buffer information about the last symbol or symbols deleted. For
example, your application could buffer the object ID related to the
symbol, the submap ID of the submap from which the symbol was cut, or
relationships to other symbols. Most applications will want to buffer at
least the object ID. When an ovwConfirmCreateSymbols event arrives
with an event source of ovwEventSourceUserPaste, your application
314
Chapter 8

can compare the object ID in the buffer to the object ID for the event.
Your application can then compare the event request against other
information that might be buffered, such as the previous submap type, to
see if the paste operation is allowed.
NOTE
OVW assigns new symbol IDs to pasted symbols. Symbols in a cut and
paste operation are identical except for their symbol IDs. Be aware that
if the user cuts multiple symbols that have the same underlying object,
you may not be able to distinguish the symbols in the paste operation
without some other contextual information such as the submap ID or
other unique application identifier.
Chapter 8
315

Applications
Customizing Drag and Drop Operations for

HP-UX and Solaris Applications
In HP OpenView Windows drag and drop has two main purposes: map
editing and action execution. The particular drag and drop behavior may
be determined by OVW or by applications. The drag and drop behavior
provided by OVW is limited to map editing and action execution.
Applications can offer any behavior the application developer wants to
provide.
Editing occurs when one or more symbols are moved within a submap
or to another submap, or when one or more symbols are dropped onto
an explodable symbol within a child submap. In the latter case, the
default behavior, which is provided by OVW, is to place the dragged
symbol(s) on the child submap of the explodable symbols.
Note that a successful drop does not guarantee that the symbols will
be allowed on an application plane of a submap.
Application control of drag and drop is primarily of interest for
helping users accomplish application-specific tasks that may include
editing. For example, an application might control drops such that
symbols are propagated to a deeper level of the submap hierarchy
based on the symbol type of the dragged symbol.
Action execution occurs when the drop is onto an executable symbol.
The dragged symbol(s) is the parameter for the action associated with
the executable symbol.
Applications can customize drag and drop behavior by controlling the
behavior of drop targetsthe symbol or submap that is the target of
the dragged symbol(s). Customization is accomplished through a
combination of registration file specification and API calls. As part of
registering control of the drop target, the application defines a drop
action by registering which drop operations it will permit and by
applying a selection rule to specify the symbol types for the drop action.
Via the APIs the application assigns the drop action to a drop target and
registers to receive a callback when a drop occurs on the drop target.
When the end user drops a symbol onto an application-controlled drop
target, the applications drop callback is invoked. This callback performs
the customized drop action. Applications must verify the drop and report
316
Chapter 8

Applications
to OVW whether the drop succeeded.Refer to the HP OpenView
Application Style Guide for usage guidelines.
Drag and Drop Behavior

Drag and Drop Events
Drag and drop move operations generate events identical to cut and
paste when the end user drags an icon from one submap to another (See
Cut and Paste Operations on page 314). In this way applications can
register for the delete and create events and achieve the same behavior
for both cut/paste and drag and drop operations. The most important
difference between drag and drop and cut and paste is that the delete
and create for drag and drop is one atomic operation. In other words,
both events are guaranteed to be generated in a successful drag move
operation. Drag move within a submap generates no events.
Drag and Drop and the Clipboard
Drag and drop move and copy operations modify the clipboard just as
cut/copy/paste operations do. Each successful drag operation copies the
drag source symbols onto the clipboard and then copies them to the
destination location on the new submap. The source symbol is removed
from its point of origination in the drag move operation. If the drag
operation fails, the clipboard remains unmodified. The clipboard is not
modified for drag move operations within a window.
Drag Sources
OVW-Provided Drag Source Behavior A drag source may be one or
more symbols from a single submap. A single symbol is dragged by
clicking the middle mouse button on a symbol and moving the mouse
cursor. The mouse cursor changes to the drag cursor (which is provided
by the cursor size bitmap for the chosen symbol. Refer to Creating and
Using Registration Files on page 39.
Multiple symbols are dragged by clicking on one of a selection of symbols
on a submap with the middle mouse button and moving the mouse
cursor. When multiple symbols are dragged, all of the dragged symbols
must be valid for the drop target. If any are invalid the drop will be
rejected.
Remember that symbol selection for drag sources is limited to a single
submap.
Chapter 8
317

Applications
Application Control of Drag Sources Applications are not able to
customize the behavior of drag sources.
Drop Targets
OVW-Provided Drop Target Behavior A drop target may be a
submap or one or more symbols. It is
a submap when the drop is onto the submap or the symbol itself
a single symbol when the drop is onto an unselected symbol or when
only one target symbol is selected
multiple symbols when the drop is onto any one of the selected
symbols within that submap
During a given drag and drop operation, if any of the dragged symbols
are invalid for the current drop target (under the drag cursor) or if the
dragged symbol is invalid for any of the multiple drop targets, then a
drop will not be permitted.
Moving one or more symbols within the same submap that are already on
results in a special case move operation that ignores any application
registration of the submap as a drop target.
When dropping a symbol onto multiple drop targets, the drop must be
valid on each of the symbols for the drop to be valid. Drops onto multiple
targets behave as if the symbols were dropped onto each individual drop
target. This means that behavior for a drop on multiple targets may be a
combination of application-controlled behavior for some drop targets and
default behavior for others. Any one drop target has no knowledge of
drops onto other targets.
Application Control of Drop Targets Applications can customize the
behavior of symbols and submaps as drop targets.
An application controls a drop target by registering a DropAction in an
application registration file, registering for a callback that notifies the
application when a drop is made on a drop target, and associating the
DropAction with the drop target. If an application controls a drop target,
the application is responsible for all of the behavior of the drop operation;
there is no longer any default behavior provided by OVW except the
operation to move a symbol within a submap.
318
Chapter 8

Applications
Drop Operations
OVW-Provided Drop Operations The drop operation is either move
or copy.
In the explicitly specified operations, if the drop operation is not allowed
by a drop target, then the drop is invalid. If the drop is onto multiple
symbols, then copy is the only permitted operation (even if each of the
drop targets supports the move operation, an explicit drop move onto
multiple symbols will be invalid).
The default operation is based on the drop targets permitted operations.
If both move and copy are permitted, move is the default. Executable
symbols permit only copy operations.
Application Control of Drop Operations Applications register drop
operations in the DropAction block of the application registration file.
Only those operations explicitly defined in the DropAction block are
permitted for any drop target associated with the DropAction.
Two operations are possible: move and copy, which are specified in the
registration file as OpMove and OpCopy.
Any drop action associated with drop target that is an executable symbol
overrides the user-defined action for that executable symbol.
Help
OVW-Provided Help The end user can get help by pressing the F1 key
during the drag operation. This causes OVW to post a dialog box
describing whether dropping on the current location is allowed and also
provides information about the drop action.
If a drop is potentially valid, the help dialog box will explain what the
result of the drop would be.
Application Control of Help An application must provide help text
for any drop targets that it controls. If a drop would be invalid, the help
dialog box should explain why, based on OVWs rules (that is, disallowed
drops or selection rule blocking).
Customization Steps
The following steps, which are discussed in detail throughout the
remainder of this section, explain how to customize drop target behavior.
Chapter 8
319

Applications
1. Define a drop action in an application registration file.
A drop action describes the configuration data that defines whether
the operation is a move or a copy. This step is described in Creating
and Using Registration Files on page 39. Drop action configuration
includes
The drop operation(s) that are permitted when a drop occurs
(OpMove and OpCopy).
A selection rule to filter what types of dragged symbols may be
dropped on targets that have the drop action.
Brief help text to provide information to the end user about the
drop target while the dragged symbol is over it.
2. Assign a drop action to a drop target (symbol/submap). This
assignment is done using the OVW API. This step makes the symbol
or submap a drop target. See Assigning a Drop Action To a Drop
Target on page 320.
3. Associate a drop action with an application callback using the OVW
API. This callback implements the semantic behavior for a successful
drop, and is also responsible for invoking OVwVerifyDrop() to return
the result. This callback will be invoked when the end user performs
a drop onto a target associated with the given drop action. This is
described in Associating a Drop Action with an Application Callback
on page 321. If the behavior cannot be carried out for any reason, an
error message must reported to the user via the OVwVerifyDrop()
API.
Assigning a Drop Action To a Drop Target

An application uses API calls to assign a drop action to a drop target.
Only one drop action can be associated to a given symbol or submap. The
steps for assigning a drop action to a drop target are the same whether
the drop target is a symbol or a submap; only the data structure that is
modified is different. The OVwSymbolInfo and OVwSubmapInfo data
structures each contain two fields that must be modified when a drop
action is assigned:
char *drop_action
char *drop_app_name
To modify the drop_action and drop_app_name fields, call

OVwGetSymbolInfo() to get the OVwSymbolInfo data structure (or
320
Chapter 8

Applications
OVwGetSubmapInfo() to get the OVwSubmapInfo data structure). Then,
set the drop_action field to point to the name of the DropAction defined
in the application registration file. Set the drop_app_name field to the
name of the application as defined in the registration file. Save these
changes by calling OVwModifySymbol() or OVwModifySymbols() (or
OVwModifySubmap() and OVwModifySubmaps() ).
The update flag for the OVwSymbolInfo data structure is:
ovwUpdateSymbolDropAction
The update flag for the OVwSubmapInfo data structure is:

ovwUpdateSubmapDropAction
Associating a Drop Action with an Application

Callback
OVwAddDropCallback() associates a callback with a particular drop
action defined in an application registration file. This configures OVW to
invoke the callback function when the drop action event occurs (that is,
when the end user performs a drop on the registered drop target). The
function signature is:
int OVwAddDropCallback(char *drop_action,
OVwDropCallbackProc drop_cb, void *user_data);
drop_action is a string that refers to the name of the DropAction

defined in the application registration file. Each DropAction defined
in an application registration file can have only a single callback
associated with it.
drop_cb is the applications callback routine that controls the drop
behavior.
user_data is a pointer to whatever user data that the application
would like the callback to see at runtime.
The association between a DropAction and a callback may be severed by
calling the API function OVwRemoveDropCallback(), which looks like
this:
int OVwRemoveDropCallback(char *drop_action);
Application Drop Callback Invocation

The drop callback is invoked when OVW recognizes that a drop is
Chapter 8
321

Applications
occurring onto a registered drop target. Its purpose is to provide the
applications drop behavior for the drop target. This behavior includes
handling all aspects of the drop including possible
semantic effects, such as adding a user to a host
presentation changes, such as removal of the original symbol on a
move operation
external data changes, such editing the password file when a user is
added to a host.
The callback is also required to call OVwVerifyDrop(). This callback
routine has the following signature:
void (*OVwDropCallbackProc) (void *userData,
char *dropActionID,
OVwSymbolIdList *dragged_symbols,
OVwSubmapId dropsite_submap,
OVwSymbolId dropsite_symbol, OVwDropOp operation,
OVwMapInfo *mapInfo, int drop_id);
The parameters in the DropCallback signature include:

user_data is the application-specific data that was passed into
OVwAddDropCallback().
drop_actionID is a pointer to the DropAction that is defined in the
application registration file.
dragged_symbols is a list of the symbols that were dropped onto the
drop target. It is guaranteed that all of these symbols satisfy the
SelectionRule criteria that were specified in the applications
DropAction registration.
dropsite_submap specifies the submap id where the dragged symbols
are dropped. Symbols may be dropped onto only one submap per drag
and drop operation. If the dragged symbols are dropped on a symbol,
the value of this parameter will be 0.
droptarget_symbol specifies the ID of the symbol that was used as
the drop target. If the dragged symbols were dropped on a submap,
the value of this parameter will be 0.
operation identifies the drop operation: OVwDropMove or
OVwDropCopy.
mapInfo identifies the OVW map that the drop occurred in.
322
Chapter 8

Applications
drop_id identifies this particular drop callback invocation. It is used
to identify the invocation so that OVW may identify which success
parameters belong to which callback invocations. It is used in the
OVwVerifyDrop() API.
These parameters provide the information that the application needs to
manage the drop behavior. The callback may choose to handle the
individual symbols in the dragged_symbols list separately, handling
some as presentation edits while handling others as semantic edits,
propagating some symbols to other levels in the submap hierarchy, and
so on. Before the callback returns, it must call OVwVerifyDrop(). This is
required so OVW will know whether the drop succeeded. Also, if the drop
failed, the application must return an error message to tell the user what
went wrong.
OVwVerifyDrop() has the following signature:
OVwVerifyDrop(char *drop_id, OVwBoolean success,
char *error_msg);
The arguments to OVwVerifyDrop() are as follows:

drop_id identifies the particular drop callback invocation that is
returning results. This allows OVW to relate the results to a
particular drop handler.
success is a flag that indicates whether the drop completed
successfully. If it is false, the application must include an error string
in error_msg to provide user feedback.
error_msg is a string that will be displayed in an error dialog if the
drop fails. It should provide clear feedback so the user will
understand the cause of the failure.
Chapter 8
323

Summary
Summary
This chapter described OVW map editing. Applications that need to be
notified of map changes can register callback routines using the
OVwAddCallback() routine. Table 8-1 listed some of the possible map
editing events.
Applications that support symbol deletion, or any of the four OVW map
editing operations (Add, Connect, Configure, and Describe), must also
register callback routines to interact with OVW to control whether the
user changes are allowed. The interaction between OVW and the
application follows a Query-Verify-Confirm process. OVW invokes an
application callback routine that checks the proposed values. The
application responds with a Boolean value indicating whether the values
are acceptable. OVW gives the user the opportunity to cancel the
operation or to proceed. If the user proceeds, OVW makes the changes
and then invokes a second application callback routine to confirm that
the changes were made.
A special dialog between OVW and the application occurs when the user
requests to delete a symbol. OVW queries the application to determine if
the symbol should be deleted. If a user does not want to view a symbol
that cannot be deleted, the user can hide the symbol through the OVW
user interface. Applications can operate on hidden symbols just as if they
were visible.
The OVW user interface cut and paste operations were then described.
To an application, the cut and paste operations appear as unrelated
delete and add events. The application is responsible for buffering any
information relating to the delete event that might be needed later. The
application is also responsible for determining if the add event actually
represents a paste operation.
Customization of drag and drop operations allows HP-UX and Solaris
application developers to assign drop targets and associate actions with
drop operations.
324
Chapter 8
Supporting Management
Consoles
325
Supporting Management Consoles
Distribution of OVW management consoles requires coordination of

several functional components. This chapter addresses the requirements
of applications to operate in the distributed UI environment. It discusses
server file distribution
distributed OVW API
remote application execution (HP-UX and Solaris Only)
OVW object database.
For further information on management consoles, refer to the Guide To
Scalability and Distribution in NNM.
326
Chapter 9

Overview
Overview
The HP OpenView management server supports distributed
management consoles. Management consoles are systems that use the
same object, topology, and map databases as the management server.
Each management console actually runs the OVW user interface and its
related processes, thereby off-loading significant memory and CPU
resources from the management station. As a result, the management
station is able to focus its resources (memory and CPU) on the
management station processes and responsibilities.
By running ovwsetupclient, a user configures a system as a
management console that shares common configuration and data with
the management server. The following universal path names are shared
between client and server:
$OV_BACKGROUNDS
$OV_BITMAPS
$OV_DB
$OV_FIELDS
$OV_HELP
$OV_LRF
$OV_REGISTRATION
$OV_SHARE_CONF
$OV_SHARE_LOG
$OV_SHARE_TMP
$OV_SNMP_MIBS
$OV_SYMBOLS
The only database directly accessed over the shared file system is the
OVW map database. The object and topology databases are accessed
transparently over TCP/IP sockets.
Applications built with OVW 4.X or 5.X libraries can run on
management consoles in this distributed environment. These libraries
handle locating the management server and connecting to the object
database transparently. Applications must also be executable on the
Chapter 9
327

Overview
management console; that is, they must either be installed on the
management console system or made available to the management
console via NFS. Because the OVw API can be distributed, applications
can also be made to run on a single remote system, but started from any
management console or server on the network. The following figure
provides an overview of distributed management consoles.
Figure 9-1
Distributing Applications
OVwSessionID=Juliet:0
Management
Console
Management
Console
OVwSessionID=Romeo:0
ovw
socket
ovw
socket
Management Server
ovwdb
daemon
Shared file
system
Shared file
system
socket
socket
map
database
Shared file
system
object
database
socket
OVW Application
OVwSessionID=Juliet:0
ovw
OVwSessionID=Antonio:0
Management
Console
328
Chapter 9

Server File Distribution
Server File Distribution

HP OpenView Windows permits multiple GUI instances to access OVW
maps in a distributed environment by sharing (via NFS on HP-UX and
Solaris or via file sharing on the Windows NT operating system) the map
database and other shared data and configuration files. Management
consoles can mount these directories so that the GUI running on that
console can access the same map and configuration information as the
server.
OVW Server Identification

When ovwdb is started a file,
\OpenView\databases\openview/ovwdb/ovserver (Windows NT
operating system) or $OV_DB/openview/ovwdb/ovserver (UNIX
systems) is generated to provide the name of the server that OVW is
using. This file provides to the management console the information it
needs to connect to the appropriate object database as well as the map
database. The file contains a simple ASCII hostname. When ovw is run, it
determines the server location from this file. Then, OVW exports the
appropriate environment, OVServer, to permit applications to connect to
the correct object database daemon. By exporting the environment
variable OVServer, with the appropriate setting for the particular host
that runs the object database process, applications started by ovw can
connect to the correct object database daemon; that is, the ovwdb running
on the server providing the map database.
An API, OVServerName(), returns the official name of the management
server to which ovw is a client. For end users, the OVW Help:About
HP OpenView dialog box provides the name of the management server for
the management console.
It is important that OVW and its application are using the same object
database server. To ensure this, the OVwInit() protocol ensures that the
object database connection is consistent with the GUI session. If there is
an inconsistency, the API fails. If the object database connection has not
yet been established, the call to OVwInit() initializes the connection to
the same database daemon the GUI is using.
Chapter 9
329

Communication with Server
Communication with Server

A distributed management console communicates with the management
server via NFS and via a socket to the object database daemon, ovwdb.
The distributed console accesses the map database and configuration
files such as symbol, field, and application registration files, via a shared
file system. On HP-UX and Solaris, ovwsetupclient configures the
distributed console to access the server mount point via symbolic links,
so the file share access should be transparent to any application on the
management console. On the Windows NT operating system, this is done
at installation time.
The distributed console and its applications use a socket connection to
the object database server, ovwdb. This socket connection is created
automatically via OVwInit() and OVwInitSession(), or via
OVwDbInit(). Therefore, an application does not need to do anything
special to communicate with the object database when running on a
distributed management console.
330
Chapter 9

Distributed OVw API
Distributed OVw API

Applications in a distributed environment may have special
requirements. Applications may need to be able to connect to an OVW
session without being called by the session. In addition, some
applications may be required to run on the management server. For
example, an application that is run to configure server processes may
need to run on the server system. Because of these needs, the OVw API
supports distributed OVW applications.
Connecting to a Remote GUI

OVwInitSession() permits an application to connect to a distributed
GUI. The call signature of this API is:
int OVwInitSession (char *appName, char *sessionID)
where the session ID parameter is the character string representation of

the session ID for the GUI under which the application is running.
Because the management console needs to know which GUI session it is
communicating with, each GUI instance is associated with a unique
session ID in the form: hostname:session_port_offset.
This session ID is generated upon ovw start-up and will be passed to
applications that OVW launches, either via environment, via a command
line option, or both. The application can either call OVwInit() which
expects to retrieve the session ID out of the environment, or call
OVwInitSession() which takes the session ID as one of its parameters.
The session ID for a GUI instance is exported to applications as
OVwSessionID.
The Help:About HP OpenView dialog box displays the session ID to
OVW users.
The Application Name

OVwInitSession() includes a parameter for the name of an application
that has started and is connecting to a GUI session. Once the application
connects to an OVW GUI, it tells OVW what application it is
implementing so that OVW can authorize the application and can
Chapter 9
331

Distributed OVw API
associate the connection with the correct registration information (such
as what actions it implements, and so on.)
OVW uses an authorization configuration file,
\OpenView\conf\ovw.auth (Windows NT operating system) or
$OV_CONF/ovw.auth (UNIX systems), that lists which users can run
which OVW applications from which hosts. See the ovw(1) reference page
for more information about this file.
332
Chapter 9

Remote Application Execution (HP-UX and Solaris Only)
Remote Application Execution (HP-UX and

Solaris Only)
OVW permits registration of applications for remote execution.
The grammar for the command statements permits registration of the
host where the command should run and the launcher which will be used
to start the command. Refer to Creating and Using Registration Files
on page 39 for the registration file syntax.
The application command must accept on its command line arguments
the session ID of the OVW session that started it. In order to initialize a
session with ovw, it must pass this to OVwInitSession().
Chapter 9
333

Remote Application Execution (HP-UX and Solaris Only)
334
Chapter 9
10
Developing Internationalized
and Localized Applications
335
Developing Internationalized and Localized Applications
This chapter
introduces the basic concepts of software internationalization and
localization, and explains how they are supported within
HP OpenView Windows.
explains the set of programming techniques application developers
should use to produce internationalized and localized C and C++
applications.
discusses special considerations for C and C++ applications that have
been internationalized or localized in the past.
The HP OpenView Application Style Guide provides additional
guidelines for designing HP OpenView applications for
internationalization and localization.
This chapter does not explain internationalization and localization
information for Web-based applications, Java applications, or applets.
This chapter does not explain general guidelines for designing or
developing internationalized or localize software.For more information
on these subjects refer to these books:
McFarland, Tom; X Windows On The World: Developing
Internationalized Software with X, Motif and CDE, Prentice Hall
PTR, New Jersey, 1996.
ODonnell, Sandra Martin; Programming for the World: A Guide to
Internationalization, Prentice Hall PTR, New Jersey, 1994.
336
Chapter 10

Internationalization
Internationalization
To produce software for multiple countries, the software must be
designed to support cultural and linguistic conventions of those
countries. This typically implies that the software allows a user to
interact with the software in his or her native language (such as,
German or Japanese), processes input and output characters that belong
to the users native language, and follows various linguistic and cultural
conventions and rules that are applicable to the software.
There are various approaches for designing software to meet the various
linguistic and cultural conventions. One approach is to produce a
different binary version of a software per language: one version for
German, one version for French, one version for Japanese, and so on.
This methodology is usually very inefficient. A better approach is to
internationalize the software.
Internationalization is a design technique in which the software has
been sufficiently generalized so that a single binary can support various
linguistic and cultural conventions. Internationalized software uses the
ANSI locale model.
Locale is a collective term for the language of the user, the location or
territory of the user (which determines local customs, such as currency
formats), and the code set in which the users data is represented. The
locale is also a physical data file and/or collection of routines that are
used to initialize an applications language sensitive environment. The
definitions are often used interchangeably since the physical file is an
implementation or instantiation of the language, territory, and code set.
In the locale model, the software user announces their desired
language at application start up. An initialization routine placed in the
software then loads tables and run-time procedures appropriate for that
language. Generic routines in the software then base their behavior on
the tables and run-time procedures. For example, when sorting (or
ordering) a list of names to be displayed to the user, an application might
call strcoll() or wcscoll() functions (for more information on these
commands, refer to string(3C) on HP-UX or Solaris systems). These
routines use the conventions of the users announced language.
Applications that integrate with HP OpenView Windows are expected to
follow this basic internationalization model.
Chapter 10
337

Localization
Localization
Once the software is internationalized, it is possible to produce a
localized version of that software. Localization refers collectively to all
work needed to make a product acceptable and functional for use in a
specific locale. This includes translating all text to be displayed to the
user, translating documentation, and providing fonts and other special
functionality when needed.
For example, the Japanese product is internationalized and its user
interface (menu labels, warnings, and error messages), manuals, and
online help have been translated into Japanese.
Even if software is not localized to a specific countrys language, it is still
important to internationalize the software so that it can process the
users local language data and operate according to the rules and
customs of his/her language.
338
Chapter 10

HP OpenView Windows Internationalization Support
HP OpenView Windows Internationalization

Support
HP OpenView Windows is internationalized and uses the locale model in
all of its non-Web based components. It has components within its user
interface that are sensitive to linguistic and cultural conventions. These
components are called localizable since different locale settings, at runtime, can change the behavior of those areas.
The following strings are localizable:
menu labels, tool bar labels, and tool tips text
map and submap names
map permissions
symbol labels
symbol class and type names
comments (for symbols, objects, and maps)
application names
executable action names
Version, CopyRight, and application description strings in
registration files
drop action help data strings
object selection base names
information, warning, and error messages
bitmaps (for symbols)
background graphics
directory and file paths
trapd.conf specification.
For example, if NNM is executed under the German language
environment, a user may create a new map with a map name that
contains characters such as the o-dieresis letter that is specific to the
code set of a German locale.
Chapter 10
339

HP OpenView Windows Internationalization Support
Not everything within HP OpenView Windows is localizable. The
following strings are restricted to ASCII characters and must be
identical in all language versions of an application.The restrictions, on
the most part, are enforced by the underlying network software layers.
hostnames
user login names
IP address
passwords
network names
printer names
numeric values
ECS circuits
In addition HP OpenView Windows supports:
1. Characters that are represented by at most 2 bytes.
2. Only those locales that are supported by software layers on which HP
OpenView is built, with an exception of ISO 8859-6, -7, -8, and -9
(Arabic, Greek, Hebrew, and Turkish).
340
Chapter 10

String Overloading
String Overloading
Commonly, non-internationalized software uses a single string as both
the internal reference to an object and as the string displayed for that
object. In essence, a single string is overloaded to serve these two
separate purposes. When such software is internationalized, it is
necessary to remove such overloading. The application needs a single,
consistent string name to use when internally referencing an object. This
string not only must be consistent between different language versions of
the application but between the application and all language versions of
NNM. At the same time, localized versions of the software need to
translate the string to be displayed in the language of each locale.
For this reason HP OpenView Windows provides a DisplayString
attribute, described in the following sections. If your software similarly
uses a single string as both an internal reference and as a string
displayed to the user, consider replacing the single string with a
structure, such as:
typedef struct _MyObject{
/* constant name used to identify the object;*/
/* guaranteed to be the same across all locales */
char * internal_name;
/* localizable name, displayed to the user */
char * display_name;
} My Object, *MyObjectPtr;
Chapter 10
341

Applications
Developing Internationalized and Localized

HP OpenView Windows Applications
HP OpenView Windows components provide mechanisms that allow
developers to create a single binary version of an application that works
correctly under the different languages that are supported. Both an
English-only version of the application and localized version of the
application can be integrated and executed by NNM running under a
non-English locale.
The following sections provide design and implementation guidelines to
help you implement an internationalized or localized application.
Application Integration
An application developer needs to ensure that the application can
integrate with HP OpenView Windows even when an end-user is
running OVW under a non-English language.
If a localized version of the applications registration file does not exist
(typically the case if the application has not been localized in general),
the English version of the registration file should be stored under the
\OpenView\registration\C directory (Windows NT operating system)
or under the /etc/opt/OV/share/registration/C (UNIX systems)
directory.
NOTE
In this chapter $OV_REGISTRATION will be used to refer to the directory

containing registration files on either the Windows NT operating system
or on HP-UX and Solaris.
If there is a localized version of the applications registration file, it

should be stored under the $OV_REGISTRATION/<locale name>
directory using the same file name used for the $OV_REGISTRATION/C
directory. When OVW is running under a non-English language, it will
load the language-specific version of the application registration file from
the $OV_REGISTRATION/<locale name> directory, if it exists, and will
ignore the file(s) under the $OV_REGISTRATION/C directory. If the
342
Chapter 10

Applications
language-specific version of the application registration file does not
exist, OVW will load the registration file from $OV_REGISTRATION/C
directory.
Special Consideration for Menu Integration
Applications that integrate with one of the existing top level menus (as
opposed to creating its own top level menu) may reference a MenuBar
name defined in a separate application registration file. Suppose that a
separate application registration file has been localized, and hence, the
MenuBar name has been localized. Unless the application that
references the MenuBar is localized to the same language as the other
application, chances are, the non-localized applications menu items will
not integrate with the specified MenuBar when OVW runs under a
localized language.
For example, suppose an applications menu item was specified to appear
under the Misc menu:
Application "My App"
{
MenuBar <100> "Misc" _i
{
<100> "My menu item" _T f.menu "MY_MENU";
}
{ .... }
Menu "MY_MENU"
}
This application is not localized. There is only one version of this

registration file stored in $OV_REGISTRATION/C. When OVW is running
under a non-English language, and if OVW has been localized to that
non-English language, the Misc menu may not be spelled Misc. As a
result, My menu item will not appear under the localized version of the
Misc menu. Instead the reference to MenuBar Misc (in English) will
cause OVW to create a second Misc menu and will integrate My menu
item under that English Misc menu.
It is debatable as to which MenuBar (localized or non-localized versions)
the non-localized menu item (My menu item) should be integrated with.
If the application has not been localized, perhaps it is clearer to the enduser that such menus appear under an English menu bar name. In any
case, if the developer wants to integrate the menu items of the nonlocalized application (such as My menu item) with the localized menu
bars, the developer will need to supply a partially localized application
Chapter 10
343

Applications
registration file, where the reference to the menu bar is localized. For
example:
Application "My App"
{
MenuBar <100> "XXXXXX"
/* XXXXXX is the localized string for "Misc" from the localized
version of $OV_REGISTRATION/<locale name>/ovw file. */
{
<100> "My menu item" _T f.menu "MY_MENU";
}
Menu "MY_MENU"
{ .... }
}
This new application registration file is partially localized. It references

the localized string XXXXXX, identical to the localized Misc string that
appears in the $OV_REGISTRATION/<locale name>/ovw file. This
application registration file may not have any other localized strings, but
it should be stored under the $OV_REGISTRATION/<locale name>
directory so that My menu item will integrate with the localized version
of Misc menu when end-user runs the application under that localized
language.
Localizing the Registration Files

The registration files provide the strings used for internal reference and
display for user interface components. Chapter 2 , Creating and Using
Registration Files, provides a detailed descriptions and examples of the
components of registration files.
Application Registration Files
OVW application registration files provide the following localizable
strings:
DisplayString for the application name
Copyright strings
Version strings
Description strings
Menu and tool bar label strings and tool tips text
DisplayString of action names
344
Chapter 10

Applications
Comment strings
DropAction HelpStrings
All other application registration file components are restricted to the
characters in ASCII and must be identical in all language versions of the
application registration file. For details on localizing application
registration files refer to Creating and Using Registration Files on
page 39.
Symbol Registration Files
Symbol registration files provide the following localizable components:
DisplayString for symbol class names
DisplayString for symbol type names
Filebase names
All other symbol registration file components are restricted to the
characters in ASCII and must be identical across different language
versions of the file. Symbol alert registration has no localizable
components since these type names are not visible to the end user. Refer
to Creating and Using Registration Files on page 39 for additional
information and examples.
Field Registration Files
In field registration files a DisplayString is provided for localization of
field names. All other field registration file components are restricted to
the characters in ASCII and must be identical in all language versions of
the field registration file.
OVwSymbolType Argument
When an application needs to specify the OVwSymbolType type argument
to call the various OVw APIs, such as OVwCreateSymbol() or
OVwCreateConnSymbol(), it is important to specify the non-localized
name associated with the symbol class and type regardless of the locale
that the application specifies.
For example:
#include <OV/ovw.h>
OVwSymbolId symid;
Chapter 10
345

Applications
OVwMapInfo *map;
ovwSWorkstationComputer, "test", ovwUnknownStatus,
...
Here, ovwSWorkstationComputer is the non-localizable string defined in

\OpenView\header\OV\sym_types.h file (Windows NT operating
system) or $OV_HEADER/OV/sym_types.h (UNIX systems) file.
OVw APIs for Manipulating Application and Action

Registrations
The first parameter to the following OVw APIs is a char *. This
parameter specifies a name of the Action (to create or delete or modify) or
the name of the Application (to create or delete):
int OVwCreateAction (char *actionId,
OVwActionRegInfo *actionInfo);
int OVwDeleteAction (char *actionId);
int OVwSetAction (char *actionId, OVwActionRegInfo
*actionInfo);
OVwActionRegInfo OVwGetAction (char *actionId);
int OVwCreateApp (char *appName, OVwAppRegInfo *appInfo);
int OVwDeleteApp (char *appName);
If an application is calling any one of the above OVw APIs, the

application should always pass the Action name in actionId, not the
localized string. Similarly, it should pass the Application name in
appName, not the localized string.
To provide a localized string for Application and Action names, specify
the strings in the displayString field in the OVwAppRegInfo and
OVwActionRegInfo structs.
The localized strings for copyright, description, version, and DropAction
help text can be specified directly in those fields; there is no
DisplayString associated with copyright, description, versions, and
DropAction HelpString fields.
Because hard-coding localized strings violates internationalization
guidelines, the application should obtain the localized strings at runtime. There are several ways to do this. An XPG3 or XPG4 compliant
system (most UNIX systems) can achieve this by calling functions such
346
Chapter 10

Applications
as catopen() and catgets() (refer to catopen(3C) and catgets(3C)) to
open a message catalog that contains the localized strings. Motif-based
applications may obtain localized strings from the app-defaults resource
files. Visual C++ based applications may obtain localized strings from
resource files or DLLs.
The following sample source code applies these guidelines for an XPG4
compliant application:
#include <OV/ovw.h>
#include <OV/ovw_reg.h>
#include <locale.h>
OVwAppRegInfo *NEWappreginfo;
char *newappname;
nl_catd catd;
setlocale(LC_ALL,""); /* Ignore possible error */
/* Open the message catalog that contains localized */
/* strings for this application.
*/
/* NOTE: this catopen call only works on XPG4 compliant system.
*/
catd = catopen("sampleApp", NL_CAT_LOCALE);
newappname = "sampleApp"; /* this is a non-localized string. */
NEWappreginfo = (OVwAppRegInfo *)
malloc(sizeof(OVwAppRegInfo));
NEWappreginfo->parent_name = NULL;
NEWappreginfo->reg_file = "foo";
NEWappreginfo->command = NULL;
NEWappreginfo->help_directory = NULL;
NEWappreginfo->name_fields = NULL;
/* Obtain the localized strings from the message catalog. */
NEWappreginfo->description = catgets(catd,1,1,
"test application for foo");
NEWappreginfo->copyright = catgets(catd,1,2,
"Hewlett-Packard, Co., 1996");
NEWappreginfo->version = catgets(catd,1,3, "Beta 1.0");
NEWappreginfo->displayString = catgets(catd,1,4,
"Test Application");
if ((OVwLockRegUpdates(FALSE)) < 0)
/* cant lock reg. files. */
exit(1);
else {
if ((OVwCreateApp(newappname, NEWappreginfo)) < 0) {
printf(catgets(catd,1,4,"OVwCreateApp failed (%s)\n"),
Chapter 10
347

Applications
OVwErrorMsg(OVwError()));
exit(1);
}
else
....
If an applications source code does not specify the displayString for

application and action names, or if the application hard-codes the
localized strings for application, action, description, copyright, version,
and drop action help strings (instead of obtaining them from a message
catalog file), the calls to OVw APIs still work, but the application is not
internationalized.
Refer to X/Open documents or your systems reference pages for more
information regarding catopen(3C) and catgets(3C).
OVw APIs for Displaying Application, Action Symbol

Class and Types
When an application needs to display application names, action names,
symbol class and type names, use the following OVw APIs:
OVwFormatSymbolType()
to obtain symbol
OVwGetAction()
to obtain displayString from

OVwActionRegInfo struct
OVwGetApp()
to obtain displayString from

OVwAppRegInfo struct
An application will fail to display localized strings if it displays strings

returned from the following OVw APIs: OVwGetAppName(),
OVwGetSymbolInfo(), OVwListSymbolTypes(), OVwGetFirstAction(),
OVwGetNextAction().
No OVw API returns the displayString specified for the Field block
definition in a Field Registration File.
Refer to OVwFormat(3), OVwAppRegistration(3), and
OVwActionRegistration(3) for more information.
Trapd.conf and SNMP traps

There are internationalization and localization considerations when
developing applications using trapd.conf and when sending SNMP
traps. Refer to the trapd.conf reference page for more information.
348
Chapter 10

Applications
Consistency and Interoperability

An internationalized application should follow the basic
internationalization guidelines as described in this chapter. It should
provide the same level of internationalization support as HP OpenView
Windows. For example, HP OpenView Windows is internationalized,
allowing localization of symbol type names. Therefore, an application
should also be internationalized allowing any newly-defined symbol type
names to be localized. This internationalization consistency improves
usability and allows such applications to exchange data smoothly with
other internationalized applications.
If an application has been properly internationalized, that application
should be able to integrate and operate on top of the localized version of
HP OpenView Windows even if the application is not localized.
If applications are localized to Japanese, we recommend that the
application is localized to the same level as the Japanese HP OpenView
Windows product. This is primarily for ease-of-use for the end users.
Japanese HP OpenView Windows software provides localized user
interface components (menu labels, labels within dialog boxes, warnings
and error messages) and online help texts. Japanese HP OpenView
Windows also ships Japanese manuals for the following types of
documents: end-user, installation, and configuration.
If an internationalized application has been localized to a language for
which HP OpenView Windows is not localized (such as French), that
application will be able to operate on top of the internationalized HP
OpenView Windows. For example, if a user starts up HP OpenView
Windows in French language mode, the user interface will still display
its strings in English, but the strings from the localized application will
be in French. If a user starts up OVW in English language mode, both
the user interface and the localized applications user interface will
display English strings.
Chapter 10
349

Considerations for Previously Localized Applications
Considerations for Previously Localized

Applications
Applications that have been internationalized or localized for HP
OpenView Windows 4.X releases may require additional changes in
order to operate properly under later releases. The following sections
describe the areas in your application that you should examine.
NOTE
Localization of application, symbol, and field registration files that are

shipped as part of HP OpenView Windows is not supported and is not
discussed in this section.
Application Registration Files

To convert an existing application registration file, take the localized
string for Application and Action names and use them for the
DisplayString value.
For example, suppose the application registration file is as follows:
Application "Engenes Programm" {
Description {
"Mein eigenes Programm"
}
MenuBar "Map" {
......
}
}
The revised application registration files should look like this:

Application "My App" {
DisplayString "Engenes Programm";
Description {
"Mein eigenes Programm"
}
MenuBar "Map" {
......
350
Chapter 10

}
}
Symbol Registration Files

If the symbol class and type names (in the applications symbol
registration files) have been localized by translating the words that
appear next to the keywords SymbolClass and SymbolType, those
translated strings will be displayed by HP OpenView Windows. However,
we recommend that the symbol registration files be updated to use
DisplayString statements.
Special Consideration for Japanese HP OpenView Applications
If the application defines a new symbol type that is a subclass of one of
HP OpenView Windows symbol classes, the applications symbol
registration files must reference the non-localized symbol class names
instead.
For example, in a OVW 4.X based application, the following symbol type
might have been defined:
SymbolType "Computer in Japanese":"Custom PC in Japanese"
{
...
}
With 5.X and 6.X releases, the Japanese characters in the SymbolType
field should be replaced with ASCII characters and a DisplayString
statement should be added containing the Japanese characters for
display purposes:
SymbolType "Computer" : "Custom PC"
{
DisplayString "Custom PC in Japanese";
}
Field Registration Files

If the field names in the applications field registration files have been
localized by translating the words that appear next to the keywords
Field, those translated strings will be displayed by HP OpenView
Windows. However, we recommend that the application registration files
be updated to use DisplayString statements.
Chapter 10
351

OVwSymbolType and sym_types.h

Sometimes an application has its own mechanism for obtaining symbol
class and type names to pass as an OVwSymbolType parameter. In these
cases, it is recommended that the application use the non-localized
symbol class and type names to pass as an OVwSymbolType parameter.
For example, when an internationalized (and possibly localized) 4.X
application calls OVwCreateSymbol(), the application probably obtains
the name of the symbol type from a message catalog as shown in the
following example:
/* This only works on UNIX systems. */
#include <OV/ovw.h>
#include <locale.h>
nl_catd catd;
OVwSymbolId symid;
OVwMapInfo *map;
char *mySymbolType;
setlocale(LC_ALL,""); /* Ignore possible error */
/* Open the message catalog that contains localized strings */
/* for this application.
*/
/* NOTE: this catopen call only works on XPG4 compliant system.
*/
catd = catopen("sampleApp", NL_CAT_LOCALE);
/* Obtain the localized version of the symbol type. */
mySymbolType = catgets(catd,1,1,"Computer:Custom PC");
mySymbolType, "test", ovwUnknownStatus,
...
This example still works in the current release. However, we recommend

that the application reference the symbol type names. If catgets was
used, consider removing the reference to the catgets call (a performance
improvement) and substituting the type names (such as,
Computer:Custom PC) for the OVwSymbolType argument.
Special Considerations for Applications that have extended
sym_types.h
If an application has extended the
352
Chapter 10

\OpenView\include\OV\sym_types.h file (Windows NT operating
system) or $OV_HEADER/OV/sym_types.h (UNIX systems) file by adding
application-specific symbol class and type names, replace the file with
the latest version and re-insert the application-specific symbol class and
type names using the non-localized ASCII strings. Do not insert localized
symbol class and type names to sym_types.h.
OVwGetAppName(), OVwGetFirstAction(),
OVwGetNextAction(), OVwGetSymbolInfo(),
OVwListSymbolTypes()
You must modify any application obtaining a localized string for
application, action, or symbol type names with any of the following OVw
APIs OVwGetAppName(), OVwGetFirstAction(), OVwGetNextAction(),
OVwGetSymbolInfo(), OVwListSymbolTypes(). To make the required
modifications do the following:
To obtain the localized strings for application names, replace
OVwGetAppName() calls with a reference to the displayString field
of OVwAppRegInfo struct. This struct can be obtained via
OVwGetApp().
To obtain the localized strings for action names, replace
OVwGetAppName() calls and OVwGetNextAction() calls with a
reference to the displayString field of OVwActionRegInfo struct. This
struct can be obtained via OVwGetAction().
To obtain the localized strings for symbol type names, replace
OVwListSymbolTypes() and OVwGetSymbolInfo() calls with
OVwFormatSymbolType().
Japanese Default Map Name and Storage Location

The name of the Japanese default map is stored as
\OpenView\databases\openview\mapdb\default file (Windows NT
operating system) or $OV_DB/openview/mapdb/default (UNIX
systems). The directory name current that was translated into
Japanese in 4.X releases, is now the English word current. This allows
users to access the same default map under English, Japanese or other
languages.
When 5.X or 6.X release is installed on top of a 4.X release, the
installation process automatically renames the Japanese word for
Chapter 10
353

current into an English word current. If a map called default in
Japanese exists, that too will be renamed to the English word default.
Location of oid_to_sym File

The location of the oid_to_sym file has changed. In 4.X releases, it was
in \OpenView\conf\$LANG\oid_to_sym (Windows NT operating system)
or $OV_CONF/$LANG/oid_to_sym (UNIX systems), now it is in
\OpenView\conf\oid_to_sym (Windows NT operating system) or
$OV_CONF/oid_to_sym (UNIX systems). This is because symbol type
names are not localized.
If in a 4.X or earlier release, an application has modified $OV_CONF/
$LANG/oid_to_sym, perhaps to add new oid-to-sym mappings, you must
move those customizations to the $OV_CONF/oid_to_sym file. (On the
Windows NT operating systems move customizations from
\OpenView\conf\$LANG\oid_to_sym to
\OpenView\conf\oid_to_sym.) When moving the customizations, use
the non-localized ASCII strings for the symbol type names.
354
Chapter 10

Warnings for Non-Internationalized Applications
Warnings for Non-Internationalized

Applications
NOTE
Test your applications internationalization support by running HP

OpenView Windows under a non-US ASCII environment and determine
whether it behaves correctly.
In general, we recommend that you not attempt to integrate noninternationalized applications with HP OpenView Windows and other
internationalized applications. If an application is a map-writer
application and is highly integrated with HP OpenView Windows, the
application can potentially corrupt the internationalized data generated
by HP OpenView Windows, by other internationalized applications, and
by the end user. For example, HP OpenView Windows can create an
object with a selection name that contains European and/or Asian
language characters. If a non-internationalized application operates on
selection names, the application may corrupt the name.
English Windows NT operating system applications are expected to run
on non-English versions of the Windows NT operating system.
On UNIX systems, if you want to integrate a non-internationalized
application with HP OpenView Windows and other internationalized
applications, consider the following:
Determine whether the non-internationalized application operates on
any potentially localized data generated by HP OpenView Windows
or other internationalized applications. If so, the application can be
supported only when HP OpenView Windows and other applications
are all running under the C localethat is, under English.
Determine whether the non-internationalized application operates on
any localized data generated by itself or by an end-user. For example,
if an application is running under a European and/or Asian locale, the
date and time format (generated by the underlying system functions)
may be different from the C locale format. A non-internationalized
application may not know how to display or read those formats
correctly. On UNIX systems, the workaround is to customize the
application to start up using the C locale at all times. For example, in
Chapter 10
355

Warnings for Non-Internationalized Applications
an application registration file, modify the Command line to specify the
C locale as the following example shows:
Command "env LANG=C /usr/perf/bin/pv $(OVwSelections}";
This type of workaround keeps the application from accepting

localized data from the end user, and from inadvertently generating
localized data as its output.
356
Chapter 10

Summary
Summary
An application should be internationalized even if it is not localized.
An application should maintain a level of indirection whenever
accessing localizable data internally from within the application code.
That is, use message catalogs or resource files to obtain the
localizable data for internal use.
Use a DisplayString statement in configuration files, application
registration files, symbol registration files, and field registration files
to specify localized strings for Application, Action, SymbolClass,
SymbolType, and Field names.
Use displayString field in OVwAppRegInfo and OVwActionRegInfo
structs to specify localized strings for Application and Action
names, when calling OVwCreateApp() and OVwCreateAction().
Use OVwGetApp(), OVwGetAction(), and OVwFormatSymbolType() to
obtain the localized strings of Application, Action, and SymbolType
names.
Chapter 10
357

Summary
358
Chapter 10
11
Integrating Your Application

with the HP OpenView Web
359
Integrating Your Application with the HP OpenView Web
This chapter provides an overview of the use model for the HP OpenView
Web applications, lists the integration points available to administrators
and developers, and describes the OVwww API for accessing web session
information. Because the integration points are available in registration
files, details for integrating applications with the HP OpenView Web
Launcher and the Network Presenter are in Managing Your Networks.
The HP OpenView Application Style Guide explains the guidelines for
designing applications for integration with the HP OpenView Web
Launcher.
As an application developer, you need to
understand the use model for the HP OpenView Web Launcher and
the web applications
understand the security model for the Launcher and web applications
understand what a Launcher session is
know what APIs are available to you to access session information.
360
Chapter 11

Model of Operation
Model of Operation
User Model
The HP OpenView web applications provide access to NNM management
information from a remote client system that is running a web browser.
The applications run on the management station, but can be accessed
from anywhere. Because these applications can be accessed from
anywhere, a security model is provided to ensure that only authenticated
users log in to an NNM management station.
The HP OpenView Web Launcher is the entry point for users who are
accessing web applications such as the Network Presenter. A user begins
a web session by specifying the ovlaunch.exe URL, or by selecting
Tools->HP OpenView Launcher from the NNM menus. If security is
enabled and configured for the HP OpenView Web, the user must enter
their name and a password before the Launcher is displayed.
Security
The HP OpenView Web provides security in the form of user
authentication and authorization. Security can be globally disabled
through the configuration file \OpenView\www\conf\session.conf on
the Windows NT operating system or
/etc/opt/OV/share/www/conf/session.conf on UNIX systems.
Security is set up via several configuration files:
the user password file:\OpenView\www\etc\htpasswd on the
Windows NT operating system or
/etc/opt/OV/share/www/etc/htpasswd on UNIX systems.
the user roles file: \OpenView\www\etc\htgroup on the Windows NT
operating system or /etc/opt/OV/share/www/etc/htgroup on
UNIX systems.
the session configuration file: \OpenView\www\conf\session.conf
on the Windows NT operating system or
/etc/opt/OV/share/www/conf/sesson.conf on UNIX systems.
Chapter 11
361

Model of Operation
The Web Session Model

A Web UI session is a group of applications associated with a particular
user on a particular display. A session is created when a user logs in to
the Launcher. Associated with each session are a session ID, user name,
user roles, and locale values that are set at session creation time and do
not change. All the applications started directly or indirectly from the
top-level Launcher are part of the session. Applications that are part of a
session can share information such as locale.
Figure 11-1
Services and Files for the Web Components

SNMP
Data
Presenter
Network
Presenter
Web
Launcher
Alarm
Browser
Web Browser
OVW Server
httpd
ovw
ovalarmsrv
ovwdb
CGI Programs
pmd
Map
database
Event
database
locale mapping files
ovsessionmgr.exe
config. files
Object
database
configuration file
background service
application, foreground service

database
If the session times out and the user logs back in with different values,
the application will not be notified of this. The application will continue
running with the old values.
362
Chapter 11

Model of Operation
A web browser instance can have only one web session per HP OpenView
web UI server. To run a different web session, a user must connect to a
different server.
A session ends when:
The user exits or closes the browser or stops the browser process.
The session has been inactive for some (configurable) period of time.
The default timeout is nine hours. This value is configurable in the
\OpenView\www\conf\session.conf file on the Windows NT
operating system or the
/etc/opt/OV/share/www/conf/session.conf file on UNIX systems.
If the session times out, the user will be asked to do another login the
next time an action is requested.
The server is shutdown. This causes all current sessions and ovstop
to be terminated.
The following information is available for each web session.
User login name (if enabled)
Roles (groups) for the logged in user (if user login enabled)
Platform-independent web locale
Platform-independent Java converter
Platform-dependent operating-system locale.
Figure 11-1 shows the interaction of the HP OpenView Web User
Interface (UI) CGI programs with HP OpenView Windows and the HP
OpenView Event subsystem. The background service httpd handles http
requests. This is a web server that is provided on UNIX systems only.
The background service ovalarmsrv provides event information to
Java-based alarm browsers. The background service ovsessionmgr.exe
manages users web sessions.
Table 11-1 lists the NNM Web UI CGI programs. Many of the CGI
programs have parameters, which are listed in the reference page
OvWebURLIntro(5).
Chapter 11
363

Model of Operation
Table 11-1
NNM Web CGI Programs

Program
Description
jovw.exe
Starts Network Presenter.
jovwreg.exe
Called by Network Presenter to parse menu information from

application registration files registered with Network Presenter.
Also parses symbol and enroll information from registration
files registered with OVW.
jovgraph.exe
The graph tool used by SNMP Data Presenter.
snmpviewer.exe
Launches the SNMP Data Presenter, or displays textual or

graphical results of SNMP monitoring operations on a browser.
webappmon.exe
Application encapsulator used by SNMP Data Presenter.
ovlaunchreg.exe
Reads the Web Launcher registration files (WLRFs), passing

input to the Launcher window for display.
ovlaunch.exe
Launches the Launcher and opens the user login screen, when
UserLogin is set.
ovlogin.exe
Processes the user login screen. Should not be called as a

standalone URL.
ovsessioninfo.exe
Collects session information from the ongoing session.
ovalarm.exe
Launches the Alarm Browser user interface.
ovwebdata.exe
Tool for accessing NNM data stores via read-only http

queries.
OvWebHelp.exe
The NNM 6.0 Help CGIs.
printsession.exe
Browser-callable URL to present user session information.
364
Chapter 11

Application Configuration and Integration

The Launcher provides top-level user-interface integration of HP
OpenView Web user interfaces. Table 11-2 lists the integration points.
The Launcher provides:
Integration of web-based applications with the HP OV Web including
URL launching of management functionality.
Login security for HP OpenView Web applications via user login and
user roles
Maintenance of session information shared by all Web UIs
Administrators and developers can also integrate applications into the
Network Presenter just as they can integrate into NNM on UNIX
systems or the Windows NT operating system. Web integration tasks can
be done by administrators because the integration points are located in
text files.
To integrate a web application, you may:
Provide a Web Launcher application registration file (WLRF) that
defines how the application will be executed from the Launcher. This
information is provided in Managing Your Networks with NNM.
Implement security by editing configuration files to set up user login,
user role assignments, session configuration, auditing.
Add languages to locales.installed.
Modify some appearance parameters.
Use the session API to get information about the web session. This
information is provided in this chapter.
Chapter 11
365

The following table shows the integration points that are available to
administrators and to developers.
Table 11-2
OV Web Launcher Configuration and Integration Points
Configuration or
Integration Point
File
authentication
UNIX systems
Definition: /etc/opt/OV/www/etc/htpasswd
On/off :/etc/opt/OV/share/www/conf/session.conf
Windows NT operating system
Definition: \OpenView\www\etc\htpasswd
On/off: \OpenView\www\conf\session.conf
authorization
UNIX systems
Definition: /etc/opt/OV/www/etc/htgroup
On/off: /etc/opt/OV/share/www/conf/session.conf
Definition: \OpenView\www\etc\htgroup
auditing
UNIX systems
Definition: /var/opt/OV/www/logs/launcher/access_log
Definition: /var/opt/OV/www/logs/launcher/login_log
On/off: /etc/opt/OV/share/www/conf/session.conf
Definition: \OpenView\www\logs\launcher\login_log
Definition: \OpenView\www\logs\launcher\access_log
366
Chapter 11

Table 11-2
OV Web Launcher Configuration and Integration Points
Configuration or
Integration Point
File
session timeout
UNIX systems
/etc/opt/OV/share/www/conf/session.conf
\OpenView\www\conf\session.conf
locale mapping
UNIX systems
/opt/OV/bin/ovchange_locale_mapping
Not available
installed locale
UNIX systems
/etc/opt/OV/share/www/conf/locales.installed
\OpenView\www\conf\locales.installed
parameter
configuration
UNIX systems
/opt/OV/www/htdocs/$LANG/nnm/launcher/browser.html
\OpenView\www\htdocs\$LANG\nnm\launcher\browser.html
application
integration into the
Launcher
UNIX systems
/etc/opt/OV/share/www/registration/launcher/<LANG>
\OpenView\www\registration\launcher\<LANG>
application
integration into
Network Presenter
UNIX systems
/etc/opt/OV/share/www/registration/jovw/<LANG>
\OpenView\www\registration\jovw\<LANG>
Chapter 11
367

Using Browser Windows

The WLRF action block allows a named window to be specified as the
target for the URL. By targeting a named browser window, a new
browser window is brought up only if there is no current instance of the
named browser window. If there is an instance of the named browser
window, this window is reused.
NNM has defined a standard set of browser window names and
recommends their use when possible. Using the standard browser
window names reduces browser window proliferation. Developers can
define other named browser windows. The NNM predefined browsers
are:
OvWwwAlarm
OvWwwHelpWindow
ECS_Event_Configuration
OvWwwNetworkPresenter
Configuration
Performance
SNMP_Data_Presenter.
When the target browser is not named, the Launcher uses the current
browser window for the selected action.
When the target browser window is specified by "" in the WLRF, the
Launcher creates a new browser window for each requested action.
Java applets that display their user interfaces in Java frames instead of
a browser window must use a browser window as the context for
invoking the applet. The recommended solution is to display an
undecorated browser window (with Type limited) as an application
announcement window. Refer to application registration file
documentation for more information on browser window style.
Using OVwww APIs to Access Session Information

The NNM Developer Toolkit provides API functions for integrating C
and Java applications with a Launcher session. Each API set includes
functions for connecting to the Launcher session, verifying the legality of
the current session, and getting session information.
368
Chapter 11

The session APIs are provided in a Java class and in a set of CGI APIs.
For C and C++ programs, the include file ovweb.h defines the structures
used in the OVwww API. When compiling, link with the ovwww and ov
libraries in that order. For Java programs, the package hp.ov.session
defines the classes and interfaces used in the class Session.
A web application that wants to receive session information must
connect to the Launcher session. If user login is enabled, a session is
valid if the user is logged in. If user login is not enabled, all sessions are
valid.
Connecting to a Session and Accessing Session Information with
the Java Session Class
The Session constructor verifies that there is a valid session and
initializes the session information.
Session.isSessionValid() returns true if login is enabled and the
user is logged in to a Launcher session or if login is disabled.
Session.isSessionValid() returns false if login is enabled and the
user is not logged into a Launcher session.
Connecting to a Session and Accessing Session Information with
the C APIs
The OVwww API functions are part of the library libovwww. Access them
using the -lovwww option to cc, CC, or ld. When linking with the ovw
library, you also need to link with the library libov. The libraries should
be linked in the following order:
cc ... -I$OV_HEADER -L$OV_LIB -lovwww -lov
OVwwwInit() initializes the OVwww API library. It must be called before

any other function in the OVwww API library. OVwwwInit checks
whether there is a valid session, sets the LANG environment variable
based on the OS locale name for the session (UNIX systems only) and
calls setlocale(). The parameter secured specifies whether a login
screen should be presented to the user if there is not currently a valid
session. OVwwwInit() returns 0 if user login is not enabled or on
successful connection to the Launcher session if user login is enabled.
OVwwwInit() returns -1 on failure. OVwwwInit() has the function
prototype:
int OVwwwInit(boolean secured);
Chapter 11
369

OVwwwGetSessionID()returns the ID for the current session in the form
hostname:number; its function prototype is:
char *OVwwwGetSessionID()
OVwwwIsSessionValid() returns TRUE if login is enabled and the user

is logged in to a Launcher session or if login is disabled.
OVwwwIsSessionValid() returns FALSE if login is enabled and the user
is not logged in to a Launcher session. Its function prototype is:
boolean OVwwwIsSessionValid()
Accessing User Information

Java Session.isLoginEnabled() returns TRUE when the Launcher
requires user login before use and FALSE when Launcher use is
unrestricted.
Session.getUser() returns a string containing the users login name or
null if user login is disabled.
Session.getRoles() returns a string containing a blank-separated list
of roles for the current user or null if user login is disabled.
C APIs OVwwwGetUser() returns a string containing the login name of a
user for the current web UI session if login is enabled. If login is not
enabled, it returns NULL. It has the function prototype:
char *OVwwwGetUser()
OVwwwGetRoles() returns a string containing a blank-separated list of

roles for the user for the current web UI session or NULL if user login is
disabled. It has the function prototype:
char *OVwwwGetRoles()
OVwwwIsLoginEnabled()checks in
/etc/opt/OV/share/www/conf/session.conf on UNIX systems or
\OpenView\www\conf\session.conf on the Windows NT operating
system to determine whether user login is enabled. It returns TRUE
when the Launcher requires user login before use and FALSE when
Launcher use is unrestricted. It has the function prototype:
boolean OVwwwIsLoginEnabled()
OVwwwUserHasRole() checks /etc/opt/OV/share/www/etc/htgroup on

UNIX systems or \OpenView\www\etc\htgroup on the Windows NT
operating system to determine whether a user has particular role. It
370
Chapter 11

returns TRUE when the current user has the specified role. It returns
FALSE when the current user does not have the specified role or user
login is disabled. The function prototype is:
boolean OVwwwUserHasRole(const char *role)
Accessing Codeset Information

Java programs may need to access text data in files. If the Java program
is the only program accessing the text data in a file, or if the text data is
all ASCII, the application can use any Java routine to read and write
Unicode 2.0 characters to that file.
However, if the Java program is sharing non-ASCII data with non-Java
programs (such as C or C++), and the platforms on which these other
programs run does not support Unicode, the text data may need to be
converted to and from Unicode. Similarly, if your Java program must
deal with non-ASCII, legacy data from a pre-Java version, you will either
need to convert that data into Unicode as part of a migration strategy, or
plan to convert to and from Unicode as your program accesses that
legacy data.
Non-ASCII data can be stored in a variety of ways. If it is not stored in
Unicode, it is probably stored in one of the many national or regional
standard coded character sets used by non-Java applications. Examples
include ISO 8859.1, ISO 8859.2, Shift-JIS (Japanese), and Japanese
EUC.
In JDK 1.1, Java introduced two new classes to help in converting
between Unicode and other coded character sets: InputStreamReader
and OutputStreamWriter. InputStreamReader and
OutputStreamWriter convert between a byte stream and Unicode 2.0. In
the constructor for these classes, you can provide an optional string,
identifying the name of the converter to be used when reading/writing
the byte stream. If the optional stream is not used, the default converter
is used. The default converters for these classes is defined by a property
on the virtual machine. When using the default converter, you have to
leave it to chance that the coded character set of your data matches the
code set of the default converter. To avoid the use of the default converter,
use the following APIs to obtain the name of the converter to use:
Java Session.getJavaConverter() returns a string containing the
character encoding for the current Launcher session. Use the returned
string for converting characters to Unicode with the InputStreamReader
class for the current Launcher session, as in InputStreamReader
Chapter 11
371

(InputStream, JavaConverter). Session.getJavaConverter()
returns NULL if the session is not valid.
C OVwwwGetJavaConverter() returns a string containing the character
encoding for the current Launcher session. Use the returned string for
converting characters to Unicode with the InputStreamReader class for
the current Launcher session, as in InputStreamReader
(InputStream,JavaConverter). OVwwwGetJavaConverter() returns
NULL if the session is not valid. Its function prototype is:
char *OVwwwGetJavaConverter()
Accessing Locale Information

Locale names are not consistent across platforms nor between Java and
non-Java programs and browsers. In most cases, locales specify three
components: language, territory, and codeset.
Web locale names and HTTP. They have the form language_country.
The country portion is optional. Some common web locale names are
shown here.
en
en_US
en_GB
ja
ja_JP
The default web locale is en for English.
Operating-system (OS) locale names are used on the file system and
are platform dependent. For instance, in HP-UX, they have the form
language_territory.codeset. They are often used to set the LC_
environment variables, and used to name some subdirectories on the
file system where locale-specific files are stored.
Java locale names are used by Java programs. They have the form
language_country but may not be the same as the web and OS locale
names. They identify the display language for the Java session.
Java Session.getWEbLocale() returns a string containing the
platform-dependent web locale for the current Launcher session.
Session.getWebLocale() returns en-US if the session is not valid
372
Chapter 11

C OVwwwGetOSLocale() returns a string containing the
platform-dependent OS locale for the current Launcher session. Its
function prototype is:
char *OVwwwGetOSLocale()
OVwwwGetJWebLocale()returns a string containing the

platform-independent web locale specified in the files in
/etc/opt/OV/www/conf/ on UNIX systems or in \OpenView\www\conf\
on the Windows NT operating system. It returns en-US if the session is
not valid. The function prototype for OVwwwGetJavaConverter() is:
char *OVwwwGetWebLocale()
Chapter 11
373

374
Chapter 11
Integrating with Logging and

Tracing
93
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.
94
Chapter 5

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 5
95

Windows NT Operating System

On the Windows NT operating system, 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 NT operating system
documentation for details on using the Event Viewer.
Figure 5-1
Windows NT Event Viewer
96
Chapter 5

The OVuTL Application Programming Interface
The OVuTL Application Programming

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

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 NT operating system).
OVuTrace()
Enters a trace message in the trace file. By default this is $NETFMT_TRC_FILE

(HP-UX and Solaris) or Event Viewer (Windows NT operating system).
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 5
97

The OVuTL Application Programming Interface
98
Chapter 5
Integrating with Process

Management
99
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 NNMs 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.
100
Chapter 6

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 6-1. This daemon:
handles requests from the administrative commands noted above
starts and stops processes as required
pauses and resumes processes which access NNMs 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.
NOTE
On the Windows NT operating system, ovspmd is a service. Refer to

your Windows NT operating system documentation for details on
services.
Chapter 6
101

Figure 6-1
Process Management
Administrative Commands:
LRF
ovstart, ovstop, ovpause,
ovaddobj
command
ovresume, ovstatus
Requests
Responses
ovsuf
ovsmpd
Tracing &
Logging
Subsystem
Well-behaved
Process
Well-behaved
Process
Non-well-behaved
Process
Daemon
Process
Figure 6-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
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,
102
Chapter 6

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 112.
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.
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
Chapter 6
103

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.
104
Chapter 6

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 6-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 completeand regardless of whether it was
successful or notyou 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()).
3. Your processs 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().
Chapter 6
105

The OVsPMD Application Programming Interface
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.
106
Chapter 6

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 6-2 describes the purpose of each line in an LRF.
Table 6-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.
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
Chapter 6
107

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 NT operating system. 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 6-3
First Line of the LRF

Field
Syntax
Default
1: Name
A character string for the

process name.
None (must be
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 companys name:
IPMgr_A.017.0_MegaCorp_International
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 \OPENVIEW\BIN or
108
Chapter 6

$OV_BIN. Note that if a directory is not specified for the executable,
\OPENVIEW\BIN or $OV_BIN is assumed.
NOTE
You must put a backslash in front of the colon that specifies the drive
specification on the Windows NT operating system. This prevents the
colon in the path from being interpreted as a field terminator. For
example,
IPMgr_A.017.0_MegaCorp_International:C\:\OpenView\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 the

Windows NT operating system. The process executable is located in
C:\OpenView\bin\MEGA\ip_mgr.
IPMgr_A.017.0_MegaCorp_International:C\:\OpenView\bin\MEGA\ip_mgr:
Second Line of the Local Registration File

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

Field
1: Initial Start Flag
Chapter 6
Syntax
A character string;
optional.
Default
OVs_NO_START
109

Table 6-4
Second Line of the LRF&

Field
Syntax
Default
2: Dependencies
A series of character
strings, separated by
commas; optional.
None (that is, can be started

at any time).
3: Arguments
A series of character
strings, separated by
commas; optional.
None (no arguments

required).
4: Behavior
A character string;
optional.
OVs_NON_WELL_BEHAVED
5: Timeout
An integer; optional.
5 seconds.
6: Pause
A character string;
optional.
NOPAUSE
7: Daemon Stop
A character string;
optional
Empty string
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).
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.
110
Chapter 6

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.
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.
Chapter 6
111

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 113.
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,
\OPENVIEW\BIN (Windows NT operating system) or $OV_BIN (UNIX
systems) 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::
112
Chapter 6

Integration with NNM Automated Backup

This section provides information about automated backups 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 6
113

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 6-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
114
Chapter 6

Figure 6-2
Backup
Data Copy
Stage
initiate
backup
Operational
Phase
pause
processes
copy
operational data
to staging area
Analytical
Phase
resume
processes
Data Archive
Stage
copy data to
permanent
archive
Data Restore
Stage
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.
After the operational phase has completed, the analytical phase is run.
Chapter 6
115

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.
116
Chapter 6

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 applications 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.
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.
Chapter 6
117

Script integration consists of providing a backup script and a recovery
script for the applications data. The script may be integrated into the
operational or analytical directory, depending on the relationship of the
applications data to the NNM operational data. If this applies to your
application, refer to Writing Backup Scripts on page 120.
Figure 6-3
Decision Tree for Script Integration
Does the application have

its own data store?
NO
There is no need for the

application to provide
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 applications 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 applications behavior
when the value of the OVwEventSource indicates that the event
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 123.
118
Chapter 6

Figure 6-4
Decision Tree for ovwMapClose Event Integration
Does the application register

for the ovwMapClose event?
NO
ovwMapClose integration is not

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.
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 124.
Chapter 6
119

Figure 6-5
Decision Tree for Background Process Integration
Does the application have a

background process that
registers with ovspmd?
Background process
integration
does not apply.
NO
YES
NO
Does that background
process have dependencies
on other NNM background
processes?
NO
YES
Does the background process

access the applications data
store?
YES
Consider background process

integration. See Integrating Via
Services.
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 6-6 shows, you can add scripts to be
run from any of four points in the ovbackup process.
120
Chapter 6

Figure 6-6
Backup Scripts
ovbackup.ovpl
runs:
Data Copy Stage

Data Archive Stage
initiate
backup
Operational
Phase
pre-pause
scripts
pause
system
copy
operational
data to staging
area
operational
scripts
copy data to
permanent
archive
Data Restore Stage
initiate
restore
resume
system
Analytical
Phase
post-resume
scripts
analytical
scripts
copy
analytical data
to staging area
administrator
runs restore
script
restore
operational
data
restore
analytical
data
The four script points include:

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.
Chapter 6
121

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 NNMs
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 NNMs 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.
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.
122
Chapter 6

Integration via ovwMapClose

As Figure 6-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.
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.
Chapter 6
123

Figure 6-7
API integration with Backup
Data Copy Stage

Integrating Application
Data Archive Stage
initiate
backup
ovwMapClose
pause
system
Acknowledge
and respond
copy data to
permanent
archive
ovwAckMapClose
copy
operational data
to staging area
Place
application in
appropiate state
Data Restore Stage
initiate
restore
ovwMapOpen
resume
system
Resume
communication
with NNM
copy
analytical data
to staging area
restore
operational
data
restore
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
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 107 and to the lrf (4) reference page.
124
Chapter 6

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 6-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 6-8
Backup via Background Services

Data Copy Stage
initiate
backup
pause
processes
OVS_CMD_PAUSE
OVS_RSP_PAUSE_ACK
wellbehaved
process
copy
operational data
to staging area
resume
processes
OVS_CMD_RESUME
OVS_RSP_RESUME_ACK
wellbehaved
process
copy
analytical data
to staging area
Chapter 6
125

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.
126
Chapter 6
Guidelines for Documenting

Map Applications
409
Guidelines for Documenting Map Applications
If your application serves as an integration point for other applications,

you should fully document how your application behaves from a
developer point of view. Though a users guide might be appropriate for
describing how an application behaves in general, a users guide would
not provide the level of detail required for a developer to determine how
to integrate a new application into an existing one.
In order for other developers to be able to integrate their applications
with yours, you need to completely describe the following application
elements:
general map application information
registration files
fields
symbols
submap types
how your application enrolls dialog boxes
dependencies on other applications.
One possible place to document this information is in your applications
reference pages. You can consult the ipmap(1) manpage for an example
of how HP documents the IP Map application.
The guidelines for documenting each of these elements are described
next.
410
Appendix A

General Map Application Information
General Map Application Information

You should document
your application name
a brief description of the purpose of your application
the command flags used to invoke your application, and whether they
can be changed
how users can alter your application configuration (e.g., enable or
disable application functionality).
Appendix A
411

Registration Files
Registration Files
Since OVW places all registration files for all applications under a
common directory structure, it can be difficult to determine which
registration files are associated with each application. If your application
uses registration files, you should document which registration files
belong to your application. Specifically, document which application,
symbol type, or field registration files you use.
412
Appendix A

Fields
Fields
If your application creates fields, you should document each of your fields
and how they are used. You should describe
the purpose of the field
the data type of the field
what values are valid for the field
whether the field has any flags associated with it (e.g., whether it is a
capability)
which fields can be used by other applications and which fields are
private to your application
where fields appear in dialog boxes and the permissions on those
fields (read-only vs. read-write).
This section should describe fields created through the Field Registration
File and fields created programmatically.
Appendix A
413

Symbol Types
Symbol Types
You should document
any symbol types or symbol alert types required by your application
any default capabilities needed and whether they can be changed
whether a symbols behavior can be changed from explodable to
executable and vice-versa.
414
Appendix A

Submaps
Submaps
You should fully describe the submap hierarchy used by your application.
Describe the different types of submaps, their purpose, and their
relationship to each other.
You must provide enough detail so that other developers can
programmatically distinguish the submaps created by your application.
One way to do this is to define different values for each of the types of
submaps that your application creates. You can use these values for the
type argument when you create a submap. You can then expose the
submap type values to other developers.
You should describe whether your submaps are shared or exclusive.
Your application might allow only certain types of symbols to be present
on particular submaps. If this is the case, you should document which
symbol types are acceptable for each submap type.
Map applications control whether symbols added to a submap remain on
the user plane or are moved to the application plane. To move a symbol
from the user plane to the application plane, map applications might
require that the objects contain particular fields. (For example, the HP IP
Map application requires that objects representing computers contain
the isNode field.). If your application requires that objects added to
submaps contain particular fields, you should document those
requirements.
Appendix A
415

Dialog Boxes
Dialog Boxes
You should completely describe the purpose of each map-editing dialog
box used by your application. (These are dialog boxes defined through
enroll blocks in the Application Registration File). Based on a description
of how your application uses OVW-generated dialog boxes, other
developers can determine if they should register callback routines to be
invoked when the dialog box operation is confirmed.
If your application depends on one or more fields for verification in a
dialog box, you should document those fields here. Applications should
not share read-write access to fields if another application verifies the
fields in dialog boxes.
416
Appendix A

Dependencies on other Map Applications

If your application is dependent on another OVW application for correct
operation, you should describe those dependencies in this section. For
instance, if your application assumes that the HP IP Map application is
present, your documentation should state this. You should also describe
what will happen if those dependencies are not met.
Appendix A
417

418
Appendix A
An Example Application
419
This chapter contains a complete example that demonstrates many of

the key concepts presented throughout this manual.
The example application determines if an object is an nfs server. If the
object is an nfs server, the application constructs a submap showing the
nfs clients connected to the server. This example demonstrates many HP
OpenView Windows application programming concepts, including object
database access, submap creation, and symbol manipulation.
The example is also available electronically as
\OpenView\prog_samples\ovw_examples\app7\seven.c on the
Windows NT operating system or as
$OV_PROG_SAMPLES/ovw_examples/app7/seven.c on UNIX systems.
420
Appendix B
Example
Example
#include
#include
#include
#include
#include
#include
#include
<stdio.h>
<unistd.h>
<string.h>
<stdlib.h>
<ctype.h>
<sys/types.h>
<OV/ovw.h>
#define
#define
#define
#define
#define
#define
False 0
True 1
CHUNK 10
TYPE_MALLOC(x) (x *) malloc (sizeof (x)) /* easier mallocing */
GIF_FILE "/usr/OV/prg_samples/ovw_examples/app7/bears.gif"
USE_FILE 1 /* creates and uses the TESTDATA file. Change to 0
to turn off the use of TESTDATA.
*/
#define TESTDATA "/tmp/app7data"
#define
#define
#define
#define
MsgNfsOn "The nfs map functionality will be enabled for this map"
MsgNfsOff "The nfs map functionality will NOT be enabled for this map"
MsgNfsErr "The NFSMap Enabled field must be set to True or False"
MsgVerDesc "Editing not allowed for this field. Press Cancel"
OVwMapInfo
static OVwBoolean
*map;
enabledForThisMap;
/*------------------------------------+--------------------------------------*/
/*------------------------------- MAKE_STR ----------------------------------*/
/* This short little routine just makes the space for a string and fills it */
/* in.
*/
/*------------------------------------+--------------------------------------*/
char *make_str (char *s)
{
char *new_str;
if (new_str = (char *) malloc(strlen(s)+1))
(void) strcpy(new_str, s);
return new_str;
}
/*------------------------------------+--------------------------------------*/
/*------------------------------ PRINTOVWERR --------------------------------*/
Appendix B
421
Example
/* This short little routine just prints the ovw error and error msg
*/
/*------------------------------------+--------------------------------------*/
void printOvwErr (char *ovwCall)
{
int err;
err = OVwError();
printf ("%s failed: error %d %s\n", ovwCall, err, OVwErrorMsg (err));
}
/*------------------------------------+--------------------------------------*/
/*------------------------------ CONCAT_STR ---------------------------------*/
/* This routine concatenates two strings together.
*/
/*------------------------------------+--------------------------------------*/
char *concat_str (char *str1, char *str2)
{
int
len1;
char *newname;
len1 = strlen (str1);
if ((newname = (char *) malloc (len1 + strlen (str2) + 1)) != NULL) {
strcpy (newname, str1);
strcpy (&newname[len1], str2);
}
return (newname);}
/*------------------------------------+--------------------------------------*/
/*------------------------------ BUILD_LIST ---------------------------------*/
/* This routine builds a list to be put into the database. It is passed
*/
/* the command to execute, it executes the command and then builds a list
*/
/* appropriate for input to the OVw database.
*/
/*------------------------------------+--------------------------------------*/
OVwListFieldValue *build_list (char *cmd)
{
int
max;
char
*cr;
char
response[1024];
FILE
*cmd_file;
OVwListFieldValue *list;
OVwListFieldEntry *temp;
list = TYPE_MALLOC (OVwListFieldValue);
list->count = 0;
422
Appendix B
Example
list->list
max
= NULL;
= 0;
#if USE_FILE
if ((cmd_file = fopen(cmd, "r")) == NULL) {
printf("error condition - couldn't fopen %s - check errno\n", cmd);
exit (1);
}
#else
if ((cmd_file = popen(cmd, "r")) == NULL) {
printf("error condition - couldn't popen %s - check errno\n", cmd);
exit (1);
}
#endif
while (fgets(response, 1024, cmd_file)) {
if (cr = strchr(response, '\n'))
*cr = '\0';
/* get rid of CR */
/* here we build the actual list to return */

if (list->count == max) { /* array is full, so make more room */
max += CHUNK; /* increase size of space */
if (list->list) /* need additional space */
list->list = (OVwListFieldEntry *) realloc(list->list, max *
sizeof(OVwListFieldEntry));
else /* this is our first chunk */
list->list = (OVwListFieldEntry *) malloc(max *
sizeof(OVwListFieldEntry));
}
temp = &(list->list[list->count]);
temp->un.string_val = make_str(response);
temp->selected = False;
list->count++;
/* keep track of count */
}
#if USE_FILE
(void) fclose(cmd_file);
#else
(void) pclose(cmd_file);
#endif
return (list);
}
/*------------------------------------+--------------------------------------*/
Appendix B
423
Example
/*------------------------------ SHOWMOUNT ----------------------------------*/
/* This routine creates the showmount command to be executed. It is passed */
/* to build_list which actually executes the command and builds the list.
*/
/* The list is returned to here and then it is returned again to the calling */
/* routine.
*/
/*------------------------------------+--------------------------------------*/
OVwListFieldValue *showmount(char *hostname)
{
char
cmd[100];
#if USE_FILE
return (build_list (TESTDATA));
#else
sprintf(cmd, "/usr/etc/showmount -a %s", hostname);
return (build_list (cmd));
#endif
}
/*------------------------------------+--------------------------------------*/
/*-------------------------------- RPCINFO ----------------------------------*/
/* This routine determines if the host is capable of being an nfs server
*/
/* by doing an rpcinfo. It looks to see if an nfs daemon is running.
*/
/* return: -1 on error; 0 if nfs not running; > 0 if nfs running
*/
/* If the supplied test data is being used, it immediately returns 1
*/
/* implying that the system is a server.
*/
/*------------------------------------+--------------------------------------*/
int rpcinfo (char *hostname)
{
FILE *rpcinfo_file;
char cmd[1024];
char response[1024];
int
count = -1;
#if USE_FILE
return (1);
#else
sprintf(cmd, "/usr/etc/rpcinfo -p %s | grep nfs | wc -l", hostname);
if ((rpcinfo_file = popen(cmd, "r")) == NULL) {
fprintf(stderr, "error condition - rpcinfo - check errno\n");
}
else {
424
Appendix B
Example
if (fgets(response, 1024, rpcinfo_file))
sscanf(response, "%d", &count);
else
printf ("errno is %d\n", errno);
}
return (count);
#endif
}
/*------------------------------------+--------------------------------------*/
/*--------------------------------- ISNFS -----------------------------------*/
/* This routine is given the object id of the system of interest. However, it*/
/* needs the textual name of the object so the OVwDbObjectIdToSelectionName */
/* is used. It would be ideal to obtain the "hostname" but that field is
*/
/* set by the IPMap application. Since this is an application to illustrate */
/* the use of the OVw product, there is no guarantee that the IPMap
*/
/* application will be running on your system.
*/
/*
*/
/* Once the hostname has been obtained, determine if the host is running any */
/* nfs daemons. This is done by calling the rpcinfo routine. If it is an
*/
/* nfs server, set the "isNfsServer" field for this object to be true. Then */
/* call the showmount routine to obtain the information about which systems */
/* this system serves. Then save that information in the database. This
*/
/* step is done to illustrate the use of the OVwDbSetFieldValue routine.
*/
/* The nfs submap could have been created directly from this information.
*/
/*------------------------------------+--------------------------------------*/
int isNfs (OVwObjectId objId)
{
int
server;
int
ret;
int
count;
char
*host;
OVwFieldValue
fieldValue;
/* If you are using real data, be sure that the selection name is a valid */
/* host on the network
*/
if ((host = OVwDbObjectIdToSelectionName (objId)) == NULL) {
printOvwErr ("OVwDbObjectIdToSelectionName");
}
if ((count = rpcinfo(host)) == -1) {
printf ("error: rpcinfo routine returned a count of -1\n");
server = False;
}
Appendix B
425
Example
else if (count)
server = True;
else {
server= False;
printf ("rpcinfo failed:host not configured or unknown host\n");
}
if ((ret = OVwDbSetFieldBooleanValue (objId,
OVwDbFieldNameToFieldId("isNfsServer"),
server)) < 0)
printOvwErr ("OVwDbSetFieldBooleanValue");
if (server) {
fieldValue.is_list = True;
fieldValue.field_type = ovwStringField;
fieldValue.modified = False;
fieldValue.un.list_val = showmount(host);
if ((ret = OVwDbSetFieldValue (objId,
OVwDbFieldNameToFieldId("serves"),
&fieldValue)) < 0)
printOvwErr ("OVwDbSetFieldValue");
}
return (server);
}
/*------------------------------------+--------------------------------------*/
/*----------------------------- CREATENFSMAP---------------------------------*/
/* This routine creates the submap for the nfs component symbol. This submap */
/* is displayed by ovw when the nfs component is double-clicked by the user. */
/* This routine works with the object id and the textual name for that
*/
/* object. Therefore, the first thing it does is to obtain the selection
*/
/* name for the object. The textual name is used as part of the label
*/
/* for the submap.
Then set the background graphic for this submap.
*/
/*
*/
/* The star configuration is used for this submap to display the server/
*/
/* client relationship. The first symbol put on the map is for the object
*/
/* that is the nfs server.
It is placed at the star center position of the */
/* submap. Next obtain from the database the list of clients for this
*/
/* nfs server. This information was put in the database in the "isNfs"
*/
/* routine. Now cycle through the client information placing the points
*/
/* onto the star and connecting the point to the star center. Each point
*/
/* represents a client system.
*/
/*
*/
/* This routine also sets the status of the object representing the most
*/
/* client systems on the submap. Although, this is not a particularly valid */
426
Appendix B
Example
/* use of the status of an object, it is done to illustrate the use of
*/
/* setting the status of symbols/objects.
*/
/*------------------------------------+--------------------------------------*/
void createNfsmap (OVwObjectInfo *compObjInfo, OVwObjectInfo *sysObjInfo)
{
int
i;
int
ret;
char
*host;
char
*pointhost;
char
*submapname;
OVwSubmapId
submapId;
OVwSymbolId
symbolId;
OVwSymbolId
star;
OVwSymbolId
connId;
OVwSymbolInfo
*connSym;
OVwSymbolInfo
*syminfo;
OVwSymbolPosition
*pos;
OVwSymbolPosition
*center_pos;
OVwObjectId
tmpobjid;
OVwObjectInfo
maxObjInfo;
OVwObjectInfo
*objInfo;
OVwFieldValue
*points;
OVwFieldBinding
conn;
maxObjInfo.num_symbols = 0;
host = OVwDbObjectIdToSelectionName (sysObjInfo->object_id);
submapname = concat_str (host, " Nfs Submap");
if ((submapId = OVwCreateSubmap (map, compObjInfo->object_id,
ovwSharedSubmap,
ovwNoSubmapType, submapname,
ovwStarLayout, 0))
== ovwNullSubmapId) {
printOvwErr ("OVwCreateSubmap");
return;
}
if ((ret = OVwSetBackgroundGraphic (map, submapId, GIF_FILE)) != 0)
printOvwErr ("OVwSetBackgroundGraphic");
/* add the center of the star which is the host of interest to the submap */
center_pos=TYPE_MALLOC (OVwSymbolPosition);
center_pos->placement=ovwStarCenterPosition;
if ((star = OVwCreateSymbol (map, submapId, sysObjInfo->object_id,
Appendix B
427
Example
"Computer:Workstation", host,
ovwUnknownStatus,
ovwSymbolStatusSource,
center_pos, ovwNoSymbolFlags))
== ovwNullSymbolId) {
printOvwErr ("OVwCreateSymbolByHostname");
return;
}
/* Now add the systems off of the center of the star to make the points
/* of the star. Need to add the connections also.
*/
*/
if ((points = OVwDbGetFieldValue (sysObjInfo->object_id,

OVwDbFieldNameToFieldId ("serves")))
== NULL) {
printOvwErr ("OVwDbGetFieldValue");
}
else if (points->un.list_val->count == 0)
OVwDbFreeFieldValue (points);
else {
pos=TYPE_MALLOC (OVwSymbolPosition);
pos->placement=ovwNoPosition;
conn.field_id =OVwDbFieldNameToFieldId (ovwNselectionName);
conn.field_val = TYPE_MALLOC (OVwFieldValue);
conn.field_val->is_list = False;
conn.field_val->field_type = ovwStringField;
conn.field_val->field_string_val = make_str ("simple line");
for (i = 0; i < points->un.list_val->count; i++) {
pointhost = points->un.list_val->list[i].un.string_val;
if ((symbolId = OVwCreateSymbolByHostname (map, submapId, pointhost,
"Computer:Workstation",
pointhost, ovwUnknownStatus,
ovwObjectStatusSource,
pos, ovwNoSymbolFlags))
printOvwErr ("OVwCreateSymbolByHostname");
}
else {
/* This section of code determines which client symbols occur
/* most often on this submap.
syminfo = NULL;
if ((syminfo = OVwGetSymbolInfo (map, symbolId)) == NULL) {
printOvwErr ("OVwGetSymbolInfo");
}
else {
428
*/
*/
Appendix B
Example
tmpobjid = syminfo->object.object_id;
OVwFreeSymbolInfo (syminfo);
if ((objInfo = OVwGetObjectInfo (map, tmpobjid)) == NULL)
printOvwErr ("OVwGetObjectInfo");
else {
if (objInfo->num_symbols > maxObjInfo.num_symbols)
maxObjInfo = *objInfo;
OVwFreeObjectInfo(objInfo);
}
}
/* now create the connection between the end point and the star center */
if ((connId = OVwCreateConnSymbolByName (map, &conn, star, symbolId,
NULL, "", ovwUnknownStatus,
ovwSymbolStatusSource,
ovwNoSymbolFlags))
printOvwErr ("OVwCreateConnSymbolByName");
}
else {
/* this just shows an example of using the OVwGetConnSymbol call
*/
if ((connSym = OVwGetConnSymbol (map, star, symbolId)) == NULL)
printOvwErr ("OVwGetConnSymbol");
OVwFreeSymbolInfo (connSym);
}
}
}
if ((ret = OVwSetStatusOnObject (map, maxObjInfo.object_id,
ovwCriticalStatus)) !=0)
printOvwErr ("OVwSetStatusOnObject");
OVwDbFreeFieldValue (points);
}
}
/*------------------------------------+--------------------------------------*/
/*----------------------------- ENDSESSIONCB---------------------------------*/
/* This routine handles the endSession event from ovw. This event occurs
*/
/* when the OVw session is existing. Regardless, of the reason for OVw
*/
/* exiting, an OVwDone is performed to disconnect the application from OVw. */
/*------------------------------------+--------------------------------------*/
static void endSessionCB (void *userData, OVwEventType type,
OVwBoolean normalEnd)
{
#if USE_FILE
unlink (TESTDATA);
Appendix B
429
Example
#endif
OVwDone();
if (normalEnd == True) {
exit (0);
}
else {
exit(1);
}
}
/*------------------------------------+--------------------------------------*/
/*---------------------------- COMPONENTSYMBOL ------------------------------*/
/* This routine creates an nfs component symbol on the child submap of an
*/
/* object. By the time this routine is called, it has been determined that */
/* an nfs component symbol should exist for the object. It will only
*/
/* create one, however, if one does not already exist. A by-product of
*/
/* the OVwCreateComponentSymbolByName routine is that it will create a
*/
/* child submap for the object if one does not already exist.
*/
/*
*/
/* If the component symbol is created successfully, the createNfsmap routine */
/* is called to create the child submap of the nfs component symbol. That
*/
/* map will contain a graphical representation of the relationships between */
/* the nfs server and its clients.
*/
/*------------------------------------+--------------------------------------*/
void *componentSymbol (OVwObjectInfo *objInfo, OVwMapInfo *map)
{
int
ret;
int
i;
int
j;
int
k;
OVwSymbolId
nfsSym;
OVwSymbolList
*symbolList;
OVwSymbolInfo
*syminfo;
symbolList = NULL;
/* add a component symbol for nfs if one doesn't exist */
if (objInfo->child_submap_id != 0) {
symbolList = OVwListSymbols(map, objInfo->child_submap_id,
ovwAppPlane, OVwGetAppName() );
}
if ((symbolList->count == 0) || (objInfo->child_submap_id == 0)) {
if ((nfsSym = OVwCreateComponentSymbolByName (map,
objInfo->object_id, NULL,
430
Appendix B
Example
"Server:Nfs", "Nfs",
ovwUnknownStatus,
ovwObjectStatusSource,
NULL, ovwNoSymbolFlags))
== ovwNullSymbolId)
printOvwErr ("OVwCreateComponentSymbolByName");
else {
syminfo = OVwGetSymbolInfo (map, nfsSym);
createNfsmap(&(syminfo->object), objInfo);
OVwFreeSymbolInfo(syminfo);
}
}
}
/*------------------------------------+--------------------------------------*/
/*------------------------------- MAKEFIELD ---------------------------------*/
/* This routine is used to make one of the field bindings in a field bind
*/
/* list.
*/
/*------------------------------------+--------------------------------------*/
void makefield (OVwFieldBinding *fieldBind, OVwFieldId id,
OVwBoolean islist, int fieldType, int val)
{
fieldBind->field_id = id;
fieldBind->field_val = TYPE_MALLOC (OVwFieldValue);
fieldBind->field_val->is_list = islist;
fieldBind->field_val->field_type= fieldType;
if (fieldType == ovwBooleanField)
fieldBind->field_val->field_bool_val = val;
else if (fieldType == ovwEnumField)
fieldBind->field_val->field_enum_val = val;
}
/*------------------------------------+--------------------------------------*/
/*--------------------------- MAKEFIELDBINDLIST------------------------------*/
/* This routine makes a field bind list. It is used by routines that need
*/
/* to create a list of items on which to filter the list of objects on a map.*/
/* It currently operates on field values that are booleans. In particular,
*/
/* it creates a filter based on the "isNode" field. As currently coded,
*/
/* it could also be used to create a capability list for other field
*/
/* values that are booleans since the field name and value are parameters
*/
/* to the routine.
*/
/*------------------------------------+--------------------------------------*/
OVwFieldBindList *makeFieldBindList (char *fieldname, int val)
Appendix B
431
Example
{
int
numFields;
OVwFieldBindList *fbl;
OVwFieldBinding *afield;
numFields = 1;
fbl = TYPE_MALLOC (OVwFieldBindList);
fbl->count = numFields;
fbl->fields = (OVwFieldBinding *) malloc
(numFields * sizeof (OVwFieldBinding));
afield = fbl->fields;
makefield (afield, OVwDbFieldNameToFieldId (fieldname),
False, ovwBooleanField, val);
return (fbl);
}
/*------------------------------------+--------------------------------------*/
/*------------------------------ MAPCLOSECB ---------------------------------*/
/* This routine is invoked when OVw issues a map close event. This could be */
/* initiated by the user creating a new map or opening an existing map.
*/
/* This application has an application configuration parameter that is
*/
/* specified at map creation time. What happens at the closing of the map
*/
/* depends on whether the map is configured with this application. If the
*/
/* map is configured with this application and this map is being closed,
*/
/* this application is no longer interested in knowing about objects
*/
/* being added to the map. Therefore, remove the callback related to the
*/
/* event "ovwConfirmCreateObjects". The callback was added in the
*/
/* mapOpenCB routine.
*/
/*------------------------------------+--------------------------------------*/
void *mapCloseCB (void *userData, int event, OVwMapInfo *closeMap,
time_t closing_time)
{
OVwFieldBindList *capabilities;
if (enabledForThisMap) {
capabilities = makeFieldBindList("isNode", True);
OVwRemoveCallback (ovwConfirmCreateObjects, capabilities);
}
OVwAckMapClose (map, closing_time);
}
,/*------------------------------------+--------------------------------------*/
/*------------------------------- MAKE_NFS ----------------------------------*/
/* This routine cycles through the list of objects it is given and calls
*/
432
Appendix B
Example
/* the routine that determines if the system is a server. If it is a server,*/
/* then it calls the routine that creates the nfs component symbol on the
*/
/* object's submap.
*/
/*------------------------------------+--------------------------------------*/
void make_nfs (OVwObjectList *objlist)
{
int
i;
int
server;
OVwObjectInfo *loop;
for (i=0, loop = objlist->objects; i <objlist->count; i++, loop++) {
server = isNfs (loop->object_id);
if (server)
componentSymbol(loop, map);
}
}
/*------------------------------------+--------------------------------------*/
/*------------------------------ CREATEOBJCB --------------------------------*/
/* This routine is the callback to handle the event caused by the addition
*/
/* of an object to the map. It is given the list of objects added to the
*/
/* map. Since there is already a routine that handles a list of objects
*/
/* that already exist on the map, just call that routine.
*/
/*------------------------------------+--------------------------------------*/
void createObjCB (void *userData, OVwEventType type, OVwMapInfo *map,
OVwObjectList *objectList)
{
make_nfs (objectList);
}
/*------------------------------------+--------------------------------------*/
/*------------------------------- MAPOPENCB ---------------------------------*/
/* This routine is the callback for the map open event.
The first thing
*/
/* is does is invoke the OVwBeginMapSync command which causes the
*/
/* "Synchronizing" phrase to appear on the OVw submap. The name of the
*/
/* opened map and all of its accompanying information is saved in the global */
/* variable "map" since the opened map is used throughout this application. */
/* The routine OVwCopyMapInfo conveniently saves all of the inform for us.
*/
/*
*/
/* The parameter "configParams" contains the information about how this
*/
/* map has been configured. We cycle through the items in that list to
*/
/* determine if this map has been configured to discover nfs information.
*/
/* In particular we are looking to see if the field "NFSMap Enabled" is set */
/* to true. If it is, then we also want to make sure that we discover the
*/
/* nfs information about objects that are later added to the map and not just*/
Appendix B
433
Example
/* objects that exist on the map when it was opened. If this application
*/
/* is not configured for this map, we end synchronizing and return. We
*/
/* also specifiy a global variable that indicates the configuration for this */
/* map so we can do what is necessary when this map is closed.
*/
/*
*/
/* If this map is configured for nfs discovery, then we find all the objects */
/* on the map that have the field "isNode" set to true.
We are using the
*/
/* field "isNode" here but in fact we would prefer to also use the field
*/
/* "isIP" to filter on the applicable objects. However, the field "isIP"
*/
/* is set by the IPMap application which is not guaranteed to be running
*/
/* on your system when you try out this application. Just filtering on
*/
/* the "isNode" field is very vague and will in all likelihood not get you
*/
/* the objects that really meet the criteria for this application. However, */
/* the purpose of this application, is to illustrate the use of many of
*/
/* the calls available with this product and to illustrate some of the
*/
/* data structures.
*/
/*
*/
/* This sample application does not periodically update the database with
*/
/* the most recent information while a map is opened. Nor does it update
*/
/* the information for existing objects when a map is reopened.
*/
/*------------------------------------+--------------------------------------*/
void *mapOpenCB (void *userData, int event, OVwMapInfo *openedMap,
OVwFieldBindList *configParams)
{
int
i;
int
ret;
OVwObjectList
*objlist;
OVwFieldBinding *field;
OVwFieldBindList *capabilities;
OVwFieldBindList *filterList;
if ((ret = OVwBeginMapSync (openedMap)) < 0 ) {
printOvwErr ("OVwBeginMapSync");
return;
}
map = OVwCopyMapInfo (openedMap);
for (i = 0, field=configParams->fields; i<configParams->count; i++, field++) {
if (field->field_id == OVwDbFieldNameToFieldId ("NFSMap Enabled")) {
if (field->field_val->field_bool_val == True) {
capabilities = makeFieldBindList("isNode", True);
if ((ret = OVwAddCallback (ovwConfirmCreateObjects, capabilities,
(OVwCallbackProc) createObjCB, NULL )) < 0)
printOvwErr ("OVwAddCallback");
enabledForThisMap = True;
434
Appendix B
Example
}
else {
OVwEndMapSync(map);
enabledForThisMap = False;
return;
}
}
}
filterList = makeFieldBindList("isNode", True);
if ((objlist = OVwListObjectsOnMap (map, filterList)) != NULL) {
make_nfs (objlist);
}
OVwEndMapSync (map);
}
/*------------------------------------+--------------------------------------*/
/*---------------------------- CONFIGCHANGECB -------------------------------*/
/* The user has the option of specifying whether the discovery of nfs
*/
/* information should be enabled for a new map.
By default it is enabled. */
/* This routine is invoked when the ovwQueryAppConfigChange event is
*/
/* generated by OVw in response to the user choosing this application in the */
/* "Configurable Applications" section of the "New Map" window.
*/
/*
*/
/* This routine generates appropriate feedback to the user based on whether */
/* the user selected "True" or "False".
This is done by sending OVw an
*/
/* OVwVerifyAppConfigChange command with the appropriate response.
*/
/*------------------------------------+--------------------------------------*/
void configChangeCB ( void *userData, OVwEventType type, OVwMapInfo *map,
OVwFieldBindList *configParams)
{
int
i;
int
ret;
char
*errorMsg;
OVwBoolean
verified;
OVwFieldBinding *field;
verified = False;
errorMsg=make_str("");
for (i = 0, field=configParams->fields; i<configParams->count; i++, field++) {
if (field->field_id == OVwDbFieldNameToFieldId ("NFSMap Enabled")) {
if (field->field_val->field_bool_val == True) {
verified = True;
errorMsg = make_str (MsgNfsOn);
Appendix B
435
Example
} else if (field->field_val->field_bool_val == False) {
verified = True;
errorMsg = make_str (MsgNfsOff);
} else
errorMsg=make_str (MsgNfsErr);
}
}
if ((ret = OVwVerifyAppConfigChange (map, configParams, verified, errorMsg))
< 0)
printOvwErr ("OVwVerifyAppConfigChange");
}
/*------------------------------------+--------------------------------------*/
/*----------------------------- QUERYDESCCB ---------------------------------*/
/* This query callback must exist for the "serves" field info to appear
*/
/* in the describe dialog box for an object even though the field has a no
*/
/* edit policy. That policy was specified in the application registration
*/
/* file. Since the field is no edit, we always want to deny any changes to
*/
/* the information related to the "serves" field that is presented in the
*/
/* object's describe box.
*/
/*------------------------------------+--------------------------------------*/
void queryDescCB (void *userData, OVwEventType type, OVwMapInfo *map,
OVwObjectInfo *object, OVwFieldBindList *dialogBoxFields)
{
OVwVerifyDescribeChange (map, object, dialogBoxFields, False, MsgVerDesc);
}
/*------------------------------------+--------------------------------------*/
/*--------------------------------- MAIN ------------------------------------*/
/* This application registers for the following OVw events: ovwEndSession, */
/* ovwMapOpen, ovwMapClose, ovwQueryAppConfigChange, and
*/
/* ovwQueryDescribeChange. Since ovw does not issue a map open callback when*/
/* ovw is first brought up, we need a way to execute this application against*/
/* the first map. This is done by obtaining the configuration parameters for*/
/* this map and then invoking the mapOpenCB as if ovw was doing it itself.
*/
/*------------------------------------+--------------------------------------*/
void main (int argc, char *argv[])
{
FILE
*fp;
OVwMapInfo
*firstMap;
OVwFieldBindList *configParams;
436
Appendix B
Example
setbuf (stdout, NULL);
setbuf (stderr, NULL);
#if USE_FILE
if ((fp = fopen(TESTDATA, "w")) == NULL) {
fprintf (stderr, "Could not create test data file.
exit (1);
}
fprintf (fp, "sys1:/usr/spool/notes\n");
fprintf (fp, "sys2:/dist/man\n");
fprintf (fp, "sys2:/dist/man\n");
fprintf (fp, "sys3:/users");
fprintf (fp, "sys3:/disc\n");
fprintf (fp, "sys4:/usr\n");
fprintf (fp, "sys5:/usr/man\n");
fprintf (fp, "sys5:/usr/spool/notes\n");
fprintf (fp, "sys5:/dist\n");
fclose (fp);
#endif
Exiting\n");
OVwInit();
OVwAddCallback
OVwAddCallback
OVwAddCallback
OVwAddCallback
(ovwEndSession, NULL, (OVwCallbackProc) endSessionCB, NULL);

(ovwMapOpen, NULL, (OVwCallbackProc) mapOpenCB, NULL);
(ovwMapClose, NULL, (OVwCallbackProc) mapCloseCB, NULL);
(ovwQueryAppConfigChange, NULL,
(OVwCallbackProc) configChangeCB, NULL);
OVwAddCallback (ovwQueryDescribeChange, NULL,
(OVwCallbackProc) queryDescCB, NULL);
firstMap = OVwGetMapInfo();
configParams = OVwGetAppConfigValues (firstMap, OVwGetAppName());
mapOpenCB (NULL, ovwMapOpen, firstMap, configParams);
OVwDbFreeFieldBindList (configParams);
OVwFreeMapInfo (firstMap);
OVwMainLoop ();
}
Appendix B
437
Example
438
Appendix B
Using the OVw API Reference

Pages
439
Using the OVw API Reference Pages

Introductory Reference Pages
Introductory Reference Pages

These reference pages contain a wealth of important information for
HP OpenView Windows application developers. You can expect to consult
these reference pages throughout HP OpenView Windows application
development.
OVwApiIntro(5)

overview of the OVw API. It describes
important HP OpenView Windows
programming concepts, and should be
read by all developers.
OVwEventIntro(5)
This reference page describes each

OVW event, as well as when and why
it is generated.
OVwRegIntro(5)

OpenView Windows registration files
(application, symbol type, and field
registration files). The reference page
also contains the registration file
grammar.
440
Appendix C

Printing Reference Pages

NNM reference pages on Windows NT operating system are available
from the Help pulldown on the NNM menu bar:
On Solaris systems, consult your system documentation for
information on accessing reference pages online or printing them.
On HP-UX systems, the following procedure is just one suggestion for
displaying or printing reference pages. This procedure does require that
you have reference pages installed locally on your system. (If your
network provides reference pages remotely instead (e.g., from a central
server), then check with your system administrator on how to access
them.)
1. Determine what syntax and options the man command is using. At a
command-line prompt, type
strings /usr/bin/man | grep col
You should receive a message similar to the following:
tbl -TX %s |neqn|nroff -h -man|col -x > %s
tbl -TX %s |neqn|nroff -man|col -x|%s
2. Determine where on your system the reference page files are kept.
Type
echo $MANPATH
You should see a list with one or more directories. Multiple directories
will be separated by colons (i.e., /usr/local/man:/usr/man). It is
recommended that you check the contents of each directory to make
sure it actually has reference page files in it.
3. Use the command syntax shown in Step 1 in one of two ways:
Specify the qualified path of the directory containing reference
page files as the %s value in the command.
Example: you know that the bggen(1) reference page is stored in
the
/usr/man/man1 directory on your system, but you are not
currently in that directory. To display this reference page online,
type the following command:
tbl -TX /usr/man/man1/bggen.1 |neqn|nroff -man|col|more
Appendix C
441

Example: to send the bggen(1) commands reference page to a file
for printing instead, type the following:
tbl -TX /usr/man/man1/bggen.1 |neqn|nroff -man|col >
/filename
cd to the directory on your system that contains reference page
files. Then specify just the command name and number as the %s
value.
Example: you are in the /usr/man/man1 directory. Display the
bggen(1) commands reference page online by typing
tbl -TX bggen.1 |neqn|nroff -man|col| more
Example: to send this reference page to a file for printing instead,
type the following:
tbl -TX bggen.1 |neqn|nroff -man|col > /filename
442
Appendix C

Run-Time Routines By Category

Table C-1 shows various groupings of OVw API routines, sorted by
related behavior. This organization lets you see how the library routines
are related without having to consult each of the individual See Also
sections.
Table C-1
OVw API Manpages Grouped by Category
Help Routines
Callback Registration
OVwAddHelpCallback(3)
OVwAddActionCallback(3)
OVwShowHelp(3)
OVwAddAlertCallback(3)
OVwAddCallback(3)
OVwAddDropCallback(3)
OVwConfirmDeleteSymbolAlert(3)
Appendix C
443

Table C-1
Event Processing
Submap Routines
OVwAddInput(3)
OVwAckUserSubmapCreate(3)
OVwFileDescriptor(3)
OVwAddSubmapContext(3)
OVwMainLoop(3)
OVwCreateSubmap(3)
OVwPeekOVwEvent(3)
OVwCreateSubmaps(3)
OVwPending(3)
OVwDisplaySubmap(3)
OVwProcessEvent(3)
OVwGetSubmapInfo(3)
OVwXtAddInput(3)
OVwListSubmaps(3)
OVwXtMainLoop(3)
OVwLoadSubmap(3)
OVwLoadSubmaps(3)
Process Management
OVwUnloadSubmap(3)
OVwDbInit(3)
OVwUnloadSubmaps(3)
OVwDone(3)
OVwModifySubmaps(3)
OVwEndSessionCB(3)
OVwSetBackgroundGraphic(3)
OVwInit(3)
OVwSubmapChangeCB(3)
OVwSessionId(3)
OVwSetSubmapName(3)
OVwSubmapOpenCB(3)
OVwSubmapCloseCB(3)
OVwUserSubmapCreateCB(3)
Error Handling
OVwError(3)
OVwErrorMsg(3)
OVwIsIdNull(3)
444
Appendix C

Table C-1
Symbol Routines
Object Database Routines
OVwCreateSymbolAlert(3)
OVwDbAppendEnumConstants(3)
OVwCreateSymbols(3)
OVwDbCreateField(3)
OVwGetConnSymbol(3)
OVwDbCreateObject(3)
OVwGetSymbolInfo(3)
OVwDbDeleteObject(3)
OVwGetSymbolsByObject(3)
OVwDbFieldNameToFieldId(3)
OVwListSymbols(3)
OVwDbGetEnumConstants(3)
OVwListSymbolTypes(3)
OVwDbGetFieldInfo(3)
OVwModifySymbol(3)
OVwDbGetFieldValue(3)
OVwSetSymbolApp(3)
OVwDbGetFieldValues(3)
OVwSetSymbolBehavior(3)
OVwDbGetFieldValuesByObjects(3)
OVwSetSymbolLabel(3)
OVwDbGetUniqObjectName(3)
OVwSetSymbolPosition(3)
OVwDbHostnameToObjectId(3)
OVwSetSymbolStatusSource(3)
OVwDbInit(3)
OVwSetSymbolType(3)
OVwDbListFields(3)
OVwSymbolChangeCB(3)
OVwDbListObjectsByFieldValue(3)
Map-Specific Object Routines
OVwDbNameToObjectId(3)
OVwGetObjectInfo(3)
OVwDbSelectionNameToObjectId(3)
OVwDbSetEnumConstants(3)
OVwHighlightObject(3)
OVwDbSetFieldValue(3)
OVwListObjectsOnMap(3)
OVwDbSetSelectionName(3)
OVwLocateBySelectionName(3)
OVwDbUnsetFieldValue(3)
OVwLocateByAttribute(3)
OVwLocateByComment(3)
OVwLocateBySymbolStatus(3)
OVwLocateBySymbolType(3)
OVwLocateBySymbolLabel(3)
Appendix C
445

Table C-1
Map-Specific Object Routines

OVwManageObject(3)
OVwSelectObjects(3)
OVwSetStatusOnObject(3)
Miscellaneous
Map Routines and Map Events
OVwAlertMsg(3)
OVServerName(3)
OVwAPILevel(3)
OVwAckMapClose(3)
OVwCheckAction(3)
OVwBeginMapSync(3)
OVwCheckInternalFunction(3)
OVwGetMapInfo(3)
OVwFormat(3)
OVwMapCloseCB(3)
OVwGetSelections(3)
OVwMapOpenCB(3)
OVwPrintMapInfo(3)
OVwReturnLocateResults(3)
OVwSelectListChangeCB(3)
OVwSymbolLabelLocateCB(3)
OVwSymbolStatusLocateCB(3)
OVwSymbolTypeLocateCB(3)
OVwAttributeLocateCB(3)
446
Appendix C

Table C-1
Map Editing and Map Change Events
Dynamic Menu Registration
OVwConfirmCapabilityChangeCB(3)
OVwActionRegistration(3)
OVwConfirmCreateObjectsCB(3)
OVwAddMenuItem(3)
OVwConfirmCreateSubmapCB(3)
OVwAddMenuItemFunction(3)
OVwConfirmCreateSymbolsCB(3)
OVwAddToolbarButton(3)
OVwConfirmDeleteObjectsCB(3)
OVwAddToolbarButtonFunction(3)
OVwConfirmDeleteSubmapsCB(3)
OVwAppRegistration(3)
OVwConfirmHideSymbolsCB(3)
OVwFindMenuItem(3)
OVwConfirmManageObjectsCB(3)
OVwGetFirstAction(3)
OVwConfirmMoveSymbolCB(3)
OVwGetFirstMenuItem(3)
OVwConfirmObjectStatusCB(3)
OVwGetFirstMenuItemFunction(3)
OVwVerifyAdd(3)
OVwGetFirstRegContext(3)
OVwVerifyAppConfigChange(3)
OVwGetFirstToolbarButton(3)
OVwVerifyConnect(3)
OVwGetFirstToolbarButtonFunction(3)
OVwVerifyDeleteSymbol(3)
OVwGetMenuItemPath(3)
OVwVerifyDescribeChange(3)
OVwGetMenuPathSeparator(3)
OVwVerifyDrop(3)
OVwGetRegContext(3)
OVwLockRegUpdates(3)
Application Information
OVwMenuRegistration(3)
OVwGetAppConfigValues(3)
OVwMenuItemRegistration(3)
OVwGetAppName(3)
OVwRenameRegContext(3)
OVwSaveRegUpdates(3)
OVwToolbarButtonRegistration(3)
Status
Appendix C
447

Run-Time Routines By Name

Table C-2 presents a listing of the OVw API routines, sorted
alphabetically. The left column contains a list of all OVw API routines,
and the right column lists the manpages that contain each of the
functions. Table C-2 is useful for finding reference pages that apply to
particular OVw API routines.
Table C-2
Function to Reference Page Mapping
Alphabetical List of Functions or Callback

Names
Reference Page
OVServerName
OVServerName(3)
OVisOnOVServer
OVServerName(3)
OVwAPILevel
OVwAPILevel(3)
OVwAckMapClose
OVwAckMapClose(3)
OVwAckUserSubmapCreate
OVwAckUserSubmapCreate(3)
OVwAddActionCallback
OVwAddAlertCallback
OVwAddCallback
OVwAddCallback(3)
OVwAddDropCallback
OVwAddHelpCallback
OVwAddInput
OVwAddInput(3)
OVwAddMenuItem
OVwAddMenuItem(3)
OVwAddMenuItemFunction
OVwAddPopupMenuItemFunction
OVwAddPulldownMenuItemFunction
OVwAddSubmapContext
OVwAddToolbarButton
448
Appendix C

Table C-2

Names
Reference Page
OVwAddToolbarButtonFunction
OVwAlertCallbackProc
OVwAlertMsg
OVwAlertMsg(3)
OVwAttributeLocateCB
OVwAttributeLocateCB(3)
OVwBeginMapSync
OVwBeginMapSync(3)
OVwCheckAction
OVwCheckAction(3)
OVwCheckInternalFunction
OVwClearBackgroundGraphic
OVwClearSymbolApp
OVwSetSymbolApp(3)
OVwCloseSubmap
OVwDisplaySubmap(3)
OVwConfirmAddSymbolCB
OVwVerifyAdd(3)
OVwConfirmAppConfigCB
OVwConfirmCapabilityChangeCB
OVwConfirmCapabilityChangeCB(3)
OVwConfirmCompoundStatusCB
OVwConfirmConnectSymbolsCB
OVwVerifyConnect(3)
OVwConfirmCreateObjectsCB
OVwConfirmCreateObjectsCB(3)
OVwConfirmCreateSubmapsCB
OVwConfirmCreateSubmapsCB(3)
OVwConfirmCreateSymbolsCB
OVwConfirmCreateSymbolsCB(3)
OVwConfirmDeleteObjectsCB
OVwConfirmDeleteObjectsCB(3)
OVwConfirmDeleteSubmapsCB
OVwConfirmDeleteSubmapsCB(3)
OVwConfirmDeleteSymbolAlertCB
OVwConfirmDeleteSymbolAlertCB(3)
OVwConfirmDeleteSymbolsCB
Appendix C
449

Table C-2

Names
Reference Page
OVwConfirmDescribeCB
OVwConfirmHideSymbolsCB
OVwConfirmManageObjectsCB
OVwConfirmMoveSymbolCB
OVwConfirmMoveSymbolCB(3)
OVwConfirmObjectStatusCB
OVwConfirmSymbolStatusCB
OVwConfirmUnhideSymbolsCB
OVwConfirmUnmanageObjectsCB
OVwCopyMapInfo
OVwGetMapInfo(3)
OVwCreateAction
OVwCreateApp
OVwCreateComponentSymbol
OVwCreateSymbol(3)
OVwCreateComponentSymbolByName
OVwCreateSymbol(3)
OVwCreateConnSymbol
OVwCreateSymbol(3)
OVwCreateConnSymbolByName
OVwCreateSymbol(3)
OVwCreateMenu
OVwCreateMenuItem
OVwCreateSubmap
OVwCreateSubmap(3)
OVwCreateSubmaps
OVwCreateSubmaps(3)
OVwCreateSymbol
OVwCreateSymbol(3)
OVwCreateSymbolAlert
OVwCreateSymbolByHostname
OVwCreateSymbol(3)
450
Appendix C

Table C-2

Names
Reference Page
OVwCreateSymbolByName
OVwCreateSymbol(3)
OVwCreateSymbolBySelectionName
OVwCreateSymbol(3)
OVwCreateSymbols
OVwCreateSymbol(3)
OVwCreateToolbarButton
OVwDbAppendEnumConstants
OVwDbAppendEnumConstants(3)
OVwDbCreateField
OVwDbCreateField(3)
OVwDbCreateObject
OVwDbCreateObjectByHostname
OVwDbCreateObjectBySelectionName
OVwDbDeleteField
OVwDbCreateField(3)
OVwDbDeleteObject
OVwDbDeleteObject(3)
OVwDbDone
OVwDbInit(3)
OVwDbFieldIdToFieldName
OVwDbFieldNameToFieldId
OVwDbFreeEnumConstants
OVwDbFreeFieldBindList
OVwDbFreeFieldInfo
OVwDbFreeFieldList
OVwDbListFields(3)
OVwDbFreeFieldValue
OVwDbFreeObjectFieldList
OVwDbFreeObjectIdList
OVwDbGetCapabilityFieldValues
Appendix C
451

Table C-2

Names
Reference Page
OVwDbGetEnumConstants
OVwDbGetEnumName
OVwDbGetEnumValue
OVwDbGetFieldBooleanValue
OVwDbGetFieldEnumByName
OVwDbGetFieldEnumByValue
OVwDbGetFieldInfo
OVwDbGetFieldIntegerValue
OVwDbGetFieldStringValue
OVwDbGetFieldValue
OVwDbGetFieldValues
OVwDbGetFieldValuesByObjects
OVwDbGetNameFieldValues
OVwDbGetUniqObjectName
OVwDbGetUniqObjectName(3)
OVwDbHostnameToObjectId
OVwDbInit
OVwDbInit(3)
OVwDbListFields
OVwDbListFields(3)
OVwDbListObjectsByFieldValue
OVwDbListObjectsByFieldValues
OVwDbNameToObjectId
OVwDbNameToObjectId(3)
OVwDbObjectIdToHostname
OVwDbObjectIdToSelectionName
452
Appendix C

Table C-2

Names
Reference Page
OVwDbSelectionNameToObjectId
OVwDbSetEnumConstants
OVwDbSetEnumConstants(3)
OVwDbSetFieldBooleanValue
OVwDbSetFieldEnumByName
OVwDbSetFieldEnumByValue
OVwDbSetFieldIntegerValue
OVwDbSetFieldStringValue
OVwDbSetFieldValue
OVwDbSetHostname
OVwDbSetSelectionName
OVwDbUnsetFieldValue
OVwDbUnsetFieldValues
OVwDeleteAction
OVwDeleteApp
OVwDeleteMenu
OVwDeleteMenuItem
OVwDeleteSubmap
OVwCreateSubmap(3)
OVwDeleteSymbol
OVwCreateSymbol(3)
OVwDeleteSymbolAlert
OVwDeleteSymbols
OVwCreateSymbol(3)
OVwDeleteToolbarButton
OVwDisplaySubmap
OVwDisplaySubmap(3)
Appendix C
453

Table C-2

Names
Reference Page
OVwDoAction
OVwCheckAction(3)
OVwDoInternalFunction
OVwDone
OVwDone(3)
OVwEndMapSync
OVwBeginMapSync(3)
OVwEndSessionCB
OVwEndSessionCB(3)
OVwError
OVwError(3)
OVwErrorMsg
OVwErrorMsg(3)
OVwFileDescriptor
OVwFileDescriptor(3)
OVwFindMenuItem
OVwFindMenuItem(3)
OVwFormatBehavior
OVwFormat(3)
OVwFormatBoolean
OVwFormat(3)
OVwFormatFieldDataType
OVwFormat(3)
OVwFormatFieldFlags
OVwFormat(3)
OVwFormatFieldId
OVwFormat(3)
OVwFormatLayoutStyle
OVwFormat(3)
OVwFormatMapPermissions
OVwFormat(3)
OVwFormatObjectId
OVwFormat(3)
OVwFormatOpScope
OVwFormat(3)
OVwFormatPlacementType
OVwFormat(3)
OVwFormatPlaneType
OVwFormat(3)
OVwFormatStatusSource
OVwFormat(3)
OVwFormatStatusType
OVwFormat(3)
454
Appendix C

Table C-2

Names
Reference Page
OVwFormatSubmapId
OVwFormat(3)
OVwFormatSubmapPolicy
OVwFormat(3)
OVwFormatSymbolId
OVwFormat(3)
OVwFormatSymbolPosition
OVwFormat(3)
OVwFormatSymbolType
OVwFormat(3)
OVwFormatSymbolVariety
OVwFormat(3)
OVwFormatTime
OVwFormat(3)
OVwFreeActionRegInfo
OVwFreeAppRegInfo
OVwFreeMapInfo
OVwGetMapInfo(3)
OVwFreeMenuItemRegInfo
OVwFreeObjectInfo
OVwGetObjectInfo(3)
OVwFreeObjectList
OVwFreeLocateResultInfoList
OVwLocate(3)
OVwFreeSubmapInfo
OVwGetSubmapInfo(3)
OVwFreeSubmapList
OVwListSubmaps(3)
OVwFreeSubmapLoadAckList
OVwLoadSubmap(3)
OVwFreeSymbolInfo
OVwGetSymbolInfo(3)
OVwFreeSymbolList
OVwListSymbols(3)
OVwFreeToolbarButtonRegInfo
OVwGetAction
OVwGetApp
Appendix C
455

Table C-2

Names
Reference Page
OVwGetAppConfigValues
OVwGetAppName
OVwGetAppName(3)
OVwGetConnSymbol
OVwGetConnSymbol(3)
OVwGetFirstAction
OVwGetFirstButtonFunction
OVwGetFirstButtonFunction(3)
OVwGetFirstMenuItem
OVwGetFirstMenuItemFunction
OVwGetFirstPopupMenuItem
OVwGetFirstPopupMenuItemFunction
OVwGetFirstPulldownMenuItem
OVwGetFirstPulldownMenuItemFunction
OVwGetFirstRegContext
OVwGetFirstToolbarButton
OVwGetMapInfo
OVwGetMapInfo(3)
OVwGetMenuItem
OVwGetMenuItemMenu
OVwGetMenuItemPath
OVwGetMenuPathSeparator
OVwGetNextAction
OVwGetNextButtonFunction
OVwGetFirstButtonFunction(3)
OVwGetNextMenuItem
OVwGetNextMenuItemFunction
456
Appendix C

Table C-2

Names
Reference Page
OVwGetNextPopupMenuItem
OVwGetNextPopupMenuItemFunction
OVwGetNextPulldownMenuItem
OVwGetNextPulldownMenuItemFunction
OVwGetNextRegContext
OVwGetNextToolbarButton
OVwGetObjectInfo
OVwGetObjectInfo(3)
OVwGetRegContext
OVwGetRegContext(3)
OVwGetSelections
OVwGetSelections(3)
OVwGetSubmapInfo
OVwGetSubmapInfo(3)
OVwGetSymbolInfo
OVwGetSymbolInfo(3)
OVwGetSymbolsByObject
OVwHelpCallbackProc
OVwHighlightObject
OVwHighlightObjects
OVwInit
OVwInit(3)
OVwInitSession
OVwInit(3)
OVwIsIdEqual
OVwIsIdNull(3)
OVwIsIdNull
OVwIsIdNull(3)
OVwListObjectsOnMap
OVwListSubmaps
OVwListSubmaps(3)
OVwListSymbolTypeCaps
Appendix C
457

Table C-2

Names
Reference Page
OVwListSymbolTypes
OVwListSymbols
OVwListSymbols(3)
OVwLoadSubmap
OVwLoadSubmap(3)
OVwLoadSubmaps
OVwLoadSubmap(3)
OVwLocateByAttribute
OVwLocate(3)
OVwLocateByComment
OVwLocate(3)
OVwLocateBySelectionName
OVwLocate(3)
OVwLocateBySymbolLabel
OVwLocate(3)
OVwLocateBySymbolStatus
OVwLocate(3)
OVwLocateBySymbolType
OVwLocate(3)
OVwLockRegUpdates
OVwMainLoop
OVwMainLoop(3)
OVwManageObject
OVwManageObject(3)
OVwManageObjects
OVwManageObject(3)
OVwMapCloseCB
OVwMapCloseCB(3)
OVwMapOpenCB
OVwMapOpenCB(3)
OVwMenuItemRegistration
OVwMenuRegistration
OVwModifySubmap
OVwModifySubmaps(3)
OVwModifySubmaps
OVwModifySubmaps(3)
OVwModifySymbol
OVwModifySymbols(3)
OVwModifySymbols
OVwModifySymbols(3)
458
Appendix C

Table C-2

Names
Reference Page
OVwPeekInputEvent
OVwPeekOVwEvent(3)
OVwPeekOVwEvent
OVwPeekOVwEvent(3)
OVwPending
OVwPending(3)
OVwPrintFieldInfo
OVwPrint(3)
OVwPrintFieldList
OVwPrint(3)
OVwPrintMapInfo
OVwPrint(3)
OVwPrintObjectInfo
OVwPrint(3)
OVwPrintObjectList
OVwPrint(3)
OVwPrintSubmapInfo
OVwPrint(3)
OVwPrintSubmapList
OVwPrint(3)
OVwPrintSymbolIdList
OVwPrint(3)
OVwPrintSymbolInfo
OVwPrint(3)
OVwPrintSymbolList
OVwPrint(3)
OVwPrintSymbolTypeList
OVwPrint(3)
OVwProcessEvent
OVwProcessEvent(3)
OVwQueryAddSymbolCB
OVwVerifyAdd(3)
OVwQueryAppConfigCB
OVwQueryConnectSymbolsCB
OVwVerifyConnect(3)
OVwQueryDeleteSymbolsCB
OVwQueryDescribeCB
OVwRemoveActionCallback
OVwRemoveAlertCallback
Appendix C
459

Table C-2

Names
Reference Page
OVwRemoveCallback
OVwAddCallback(3)
OVwRemoveDropCallback
OVwRemoveHelpCallback
OVwRemoveInput
OVwAddInput(3)
OVwRemoveMenuItem
OVwAddMenuItem(3)
OVwRemoveMenuItemFunction
OVwRemovePopupMenuItemFunction
OVwRemovePulldownMenuItemFunction
OVwRemoveSubmapContext
OVwRemoveToolbarButton
OVwRemoveToolbarButtonFunction
OVwRenameRegContext
OVwRenameRegContext(3)
OVwReturnLocateResults
OVwReturnLocateResults(3)
OVwSaveRegUpdates
OVwSelectListChangeCB
OVwSelectListChangeCB(3)
OVwSelectObject
OVwSelectObject(3)
OVwSelectObjects
OVwSelectObject(3)
OVwSessionId
OVwSessionId(3)
OVwSetAction
OVwSetApp
OVwSetAppConfigValues
OVwSetBackgroundGraphic
460
Appendix C

Table C-2

Names
Reference Page
OVwSetMenuItem
OVwSetMenuPathSeparator
OVwSetRegContext
OVwGetRegContext(3)
OVwSetStatusOnObject
OVwSetStatusOnObjects
OVwSetStatusOnSymbol
OVwSetStatusOnSymbols
OVwSetSubmapName
OVwSetSubmapName(3)
OVwSetSymbolAlertText
OVwSetSymbolApp
OVwSetSymbolApp(3)
OVwSetSymbolBehavior
OVwSetSymbolBehavior(3)
OVwSetSymbolLabel
OVwSetSymbolLabel(3)
OVwSetSymbolPosition
OVwSetSymbolPosition(3)
OVwSetSymbolStatusSource
OVwSetSymbolStatusSource(3)
OVwSetSymbolType
OVwSetSymbolType(3)
OVwSetToolbarButton
OVwShowHelp
OVwShowHelp(3)
OVwSubmapChangeCB
OVwSubmapChangeCB(3)
OVwSubmapCloseCB
OVwSubmapCloseCB(3)
OVwSubmapOpenCB
OVwSubmapOpenCB(3)
OVwSymbolChangeCB
OVwSymbolChangeCB(3)
OVwSymbolLabelLocateCB
OVwSymbolLabelLocateCB(3)
Appendix C
461

Table C-2

Names
Reference Page
OVwSymbolStatusLocateCB
OVwSymbolStatusLocateCB(3)
OVwSymbolTypeLocateCB
OVwSymbolTypeLocateCB(3)
OVwUndoRegUpdates
OVwUnloadSubmap
OVwLoadSubmap(3)
OVwUnloadSubmaps
OVwLoadSubmap(3)
OVwUnlockRegUpdates
OVwUnmanageObject
OVwManageObject(3)
OVwUnmanageObjects
OVwManageObject(3)
OVwUserSubmapCreateCB
OVwUserSubmapCreateCB(3)
OVwVerifyAdd
OVwVerifyAdd(3)
OVwVerifyAppConfigChange
OVwVerifyConnect
OVwVerifyConnect(3)
OVwVerifyDeleteSymbol
OVwVerifyDescribeChange
OVwVerifyDrop
OVwVerifyDrop(3)
OVwXtAddInput
OVwXtAddInput(3)
OVwXtAppAddInput
OVwXtAddInput(3)
OVwXtAppMainLoop
OVwXtMainLoop(3)
OVwXtMainLoop
OVwXtMainLoop(3)
462
Appendix C
Index
Symbols
$LANG, 42
$OV_FIELDS/$LANG, 118
$OV_HELP/$LANG, 56
$OV_SYMBOLS/$LANG, 100
(*OVwConfirmDeleteSymbolsC
B)(), 307
(*OVwMapCloseCB)(), 228
(*OVwQueryDeleteSymbolsCB)(
), 307
A
acknowledgment timer
map close, 227
action events
callback routines, 149
description, 148
example, 149
adding
a symbol, 303
agents
daemon, 385, 393
non-well-behaved, 393
well-behaved, 384
alerts
See status
See symbol alert
AllContexts, 67
API version
controlling, 32
application
connecting to remote GUI, 331
application callbacks
associating with a DropAction,
321
removing association with
DropAction, 321
application configuration
changing the application
configuration, 303
map editing, 303
application development
Index
connecting to ovw, 145

disconnecting from ovw, 145
getting application name, 157
performing X event processing,
153
processing events, 151
programmatic access to help,
162
registering for event
notification, 146
testing IDs, 156
application integration
control of drag sources, 317
control of drop targets, 317
participation in map changes,
300
using IP Map as example, 231
application registration files,
4590
application block, 51
command block, 53
copyright block, 52
description block, 52
drop action registration, 83
DropAction block, 83
Enroll block, 85
HelpDirectory statement, 56,
70
MenuBar block, 59
NameField statement, 57
processing, 43
version statement, 52
applications
checking map status, 226
compiling, 32
connecting to OpenView
Windows, 145
definition in ARF, 51
integration tips, 231
retrieving configuration
information, 219
searching for symbols, 279
setting configuration
programmatically, 220
setting interest in a symbol,
279
starting after map open, 226
attributes
map-specific, 288
automatic layout
overriding, 250
B
background graphics, 229
clearing, 229
modifying for a submap, 214
setting, 229
background, sending your
process into, 388
base symbols, 243
behavior
changing for a symbol, 276
symbols, 238
Bus layout algorithm, 200
C
callback routines
example, 147
for map change events, 295
capabilities
merging default fields of
symbol type with fields of
object, 249
cg92_used, 33
changing
attributes of submaps, 214
object description, 304
status colors, 241
submap name, 215
text annotation dynamically
for symbol alert, 267
checking
event queue during map
synchronization, 226
463
Index
child submaps, 196

clearing
closing
submaps, 210
colors
changing status colors, 241
commands
global, 53
process flags, 54
compiler errors
cg92_used, 33
compiling, 32
Solaris applications, 33
compound status, 242
in on-demand map
applications, 312
see status
configuration
configuration, 303
retrieving information about,
219
setting application
configuration
connecting two symbols, map
editing, 303
connection symbol
appearance, 274
connection symbols, 100
creating, 252
filled, 274
overlay graphics, 111
primary status, 275
secondary status, 275
status, 274
connections
example listing connections
within meta-connection
submap, 285
multiple, 253
464
representing multiple
connections, 197
container symbols
meta-connections, 253
context, 65
context expressions, 66
convenience routines
OVwDb, 188
conventions
typographical, 21
coordinate position, 239
setting, 251
copying
flashing symbols, 272
symbol alerts, 243
copyright blocks, 52
creating
a symbol based on object name,
248
a symbol based on parent
object, 248
advantages/disadvantages
using
OVwCreateSymbols(), 259
combinations of icon and
example creating multiple
symbols with
multiple symbols with a single
call, 254
object database fields, 170
objects, 176
submaps, deciding when to,
209
symbol alerts, 266
symbols, 246
text annotation dynamically
for symbol alert, 267
critical status, 240
CursorSize, 110
customization
drag and drop operations, 319

cut and paste operations, 314
cutting
transparent symbols, 270
D
data structures
definitions, 169
implementation of list data
structures, 178
OVwEnumConstants, 172
OVwFieldBinding, 179
OVwFieldBindList, 185
OVwFieldInfo, 173
OVwFieldValue, 176
OVwListFieldEntry, 176
OVwListFieldValue, 176
OVwLocateResultList, 309
OVwLocateResultObject, 309
OVwMapInfo, 218
OVwObjectIdList, 158
OVwObjectInfo, 288
OVwObjectList, 290
OVwSubmapInfo, 220
OVwSubmapList, 213, 222
OVwSymbolCreateInfo, 254
OVwSymbolCreateList, 254
OVwSymbolInfo, 282
OVwSymbolPosition, 249
data types
object database fields, 168
DefaultCapabilities, 108, 113
DefaultLayout, 107, 113
DefaultStatusSource, 107, 113
defining
enumeration values, 172
deleting
guidelines for deleting
symbols, 259
guidelines for deleting symbols
and objects, 260
Index
Index
submaps, 217
symbol alerts, 267
symbols, 259, 307
description blocks, 52
dialog box, adding help
, 88
disabled status, 240
disconnecting from ovw, 145
displaying
graphical map of managed
environment, 229
highlighted objects, 161
submaps, 208
displayTextAnnotationBackgrou
nd, 273
distribution, 325
drag and drop
drop action registration, 83
operations, 84
drag and drop operations, 316
323
application callback
invocation, 321
assigning a DropAction to a
drop target, 320
associating a DropAction with
an application callback,
321
behavior, 317
customization steps, 319
help for, 319
removing association between
DropAction and
application callback, 321
verifying success of drop
operation, 323
drag source
behavior, 317
dragging
transparent symbols, 270, 272
drop actions
help text, 84
Index
operations, 84
registration, 83
selection rule, 84
drop operations
behavior, 319
drop targets
assigning DropAction to, 320
behavior, 317
drop_action, 320
drop_app_name, 320
DropAction
assigning to a drop target, 320
associating with an application
callback, 321
removing association with
application callback, 321
E
enableExecCueRemoval, 272
enableFlashing, 272
enroll block, 85
fields, 89
rules, 86
enumerated types
defiing, 172
enumeration types
retrieving information, 174
error handling
return code, 155
string associated with an error,
155
errors
cg92_used, 33
value definitions, 155
event handling
example, 299
event processing, 151
special needs, 153
event queue
checking during map
events, 146
advanced event queue

management, 154
capability field of object
changed, 295
checking for, 152
checking the queue, 154
compound status changed, 295
confirming appropriate confirm
event, 306
defined, 146
file descriptor, 152
hidden symbol, 297, 298
hidden symbol events, 297
manage/unmanage object, 298
manage/unmanage object
events, 298
map changes, 295299
map closed, 295
map editing, 295
map opened, 295
object status changed, 295
one or more objects become
managed on map, 295
one or more objects become
unmanaged on map, 295
one or more objects created on
map, 295
one or more objects deleted
from map, 295
one or more submaps created
on map, 295
one or more submaps deleted
from map, 295
one or more symbols created on
map, 295
one or more symbols delected
from the map, 295
one or more symbols hidden,
295
one or more symbols unhidden,
295
OVW terminated, 295
ovwMapOpen, 224
465
Index
ovwSelectionListChange, 159
selection list changes, 295
status of symbol changed, 295
symbol moved within map, 295
example
modifying submap attributes,
215
example applications, 153
examples
action event registration, 149
callback routine, 147
changing symbol behavior, 278
checking for file descriptor
input, 152
creating a symbol, 247
creating an object containing a
name field, 180
creating multiple symbols with
error handling, 155
event handling, 299
getting contents of selection
list, 158
listing connections of a metaconnection submap, 285
placing symbols by coordinate
position, 251
retrieving a list of submaps,
222
retrieving field value
information, 183
symbol alert callback
registration, 262
symbol pop-up menu
registration, 72
using OVwCreateSubmap(),
207
using OVwFieldBindList data
structure, 186
using OVwGetSelections(), 158
exclusive submaps, 197, 202
exec_vis_cue, 272
executable symbols, 238
466
appearance, 271
explodable symbols, 196, 238
expressions
context, 66
F
field data types
defining enumeration values,
172
field IDs
testing, 156
field information
managing, 168
field registration files, 118
capability flag, 119
combining flags, 123
examples, 121
field block, 118
field type, 119
general flag, 119
list flag, 119
locate flag, 119
name flag, 119
processing, 43
fields
convenience routines to
retrieve and set values,
184
converting field IDs to field
names, 171
converting field names to field
IDs, 171
creating, 170
data types, 168
defined, 168
enumeration, 172
getting values, 183
identifier, 171
name versus identifier, 171
passing values as arguments,
185
retrieving, 173
retrieving information about

enumeration, 174
retrieving values, 183
returning information based on
flag settings, 174
returning information for a
single field, 174
setting a value, 184
unsetting a value, 190
value definition, 176
file descriptor input events, 152
filebase, 110
flashing, 272
copying, 272
cutting, 272
dragging, 272
map editing, 272
moving, 272
freeing memory
OVwFreeSubmapList(), 223
FRF, 118
function prototypes
complete list, 169
G
geometry
submap, definition, 203
submap, setting, 216
submaps, 204
graphics
background of managed
environment, 229
H
header files
ovw_obj.h, 169, 171
ovw_string.h, 184
help
application-specific, 136
dialog box specific, 135
main menu bar, 132
Index
Index
on drag and drop operations,

319
programmatic access, 162
text for drop actions, 84
text viewing facility, 129
help buttons, adding, 88
help directory, 56
Help menu, adding items, 69
help, adding to dialog box, 88
help, adding to Help menu, 69
hiding
symbol alerts, 243
highlighting objects, 161
home submaps, 197
HP OpenView Windows
dialog boxes generated by, 84
object database, 168
programming model, 144
I
icon size recommendation
symbol subclasss, 111
icon symbols, 100
integration
with logging, 377
with process management, 383
with tracing, 377
IP hostname
predefined name field, 175
ISO 10164 status severity levels,
241
L
labels
changing symbol labels, 278
symbol, 237
layout algorithms, 200
constraints, 239
defined, 238
overriding, 239
Index
placing symbols on background

graphic, 229
listing
all objects on a map, 290
open submaps, 223
registered symbols types, 287
symbols on submap, 286
locate results
returning for on-demand map
applications, 309
locating objects on transient
submaps, 309
logging
and OVuTL API, 377
description of, 377
severity levels, 377
LRF, 383
agent name and location, 390
and ovstart, ovstop, ovstatus,
and mp_bind(), 390
and Process Management, 389
contents of, 389
general syntax, 389
line 1 syntax, 390
line 2 syntax, 391
M
major status, 240
management console, 327
managing
objects programmatically, 313
managing status
on-demand map applications,
312
map applications
on-demand, 309
transient, 309
map databases
controlling size, 202
map editing
adding a symbol, 84, 300
changing application
configuration, 84, 300
configuration, 303
choosing confirm event, 306
connecting symbols, 84, 300
connecting two symbols, 303
events, 295
interactions, 300
modifying object attributes,
84, 300
query-verify-confirm sequence,
301
map edits
map synchronization
checking for important events,
226
maps
application configuration, 219
application participation in
map changes, 300, 308
callback routines for map
change events, 295
close request, 227
defined, 195
getting information, 218
map change events, 295299
map close acknowledgment
timer, 227
map editing events, 295
open, 195
processing a map close event,
227
processing map open request,
224
synchronization routines, 225
memory management
implementation of data
structures, 178
467
Index
memory use
Windows NT, 33
MenuBar blocks, 59
menus
mnemonic, 62
registration of symbol alert
menus, 73
registration of symbol alerts,
73
structure of pull-down, 58
meta-connection submaps
example listing connections,
285
submap, 198
migrating
applications, 32
minor/marginal status, 240
modifying
attributes of submaps, 214
submap name, 215
submaps, 214
moving
multiple connections, 253
Multiple Connections layout
algorithm, 200
N
name field, 119
NameField statement, 57
nettl, 377
NNM
retrieving version information,
33
No Layout layout algorithm, 200
no position, 239
NoGeneric, 67
normal status, 240
notifications
map changes, 295299
468
O
object databases
convenience routines, 188
developer access, 168
field data types, 168
persistence, 168
object IDs
testing, 156
object information
managing, 168
objects
adding field, 184
as status sources, 241
capabilities, 86
changing description, 304
changing selection list via
APIs, 160
creating, 176, 179
creating by hostname, 182
creating by selection name,
182
defined, 169
definition, 236
deleting, 190
generating unique name, 181
generating unique selection
name, 181
getting the selection list, 158
global attributes vs. mapspecific attributes, 291
highlighting, 161
listing all on a map, 290
locating on transient submaps,
309
manage/unmanage object
events, 298
managing programmatically,
313
map-specific attributes, 289
OVwDbCreateObject(), 179
parent, 196
291
selecting via API, 160

selection name, 179
unique ID, 179
unmanaging
on-demand map applications
considerations when creating
and destroying submaps,
312
design considerations, 312
location objects and symbols,
309
managing status, 312
ovwConfirmCreateSubmaps,
312
ovwConfirmDeleteSubmaps,
312
OVwGetSymbolsByObject, 312
OVwListObjectsOnMap, 312
OVwListSubmaps, 312
returning locate results, 309
using compound presentation
status, 312
using
OVwGetSymbolsByObject(
), 312
using
OVwListObjectsOnMap(),
312
using OVwListSubmaps(), 312
on-demand programming tips
considerations when creating
and destroying submaps,
312
status management in
transient submaps, 312
on-demand submaps, 202, 209
op_scope, 299
OpCopy, 84
open maps, 195
OpMove, 84
orphaned submaps, 197
ovaddobj, and SUF, 383
Index
Index
overlay
graphics, 111
setting submap overlay, 215
submap windows, 204
OVNNMVersion, 33
OVsDone(), 387
OVServerName, 329
OVsInit(), 387
OVsInitComplete(), 387
ovspmd
diagram, 383
process management daemon,
383
OVsPMD API
functions in, 387
rules for use, 387
OVsReceive(), 387
ovstart, 383
ovstatus, 383
ovstop, 383
OVuLog(), 379
OVuTL API
functions of, 379
tracing and logging, 377
OVuTrace(), 379
OVVersion.h, 33
OVw APIs
groups, 30
ovw events, 146
ovw_errs.h, 155
ovw_obj.h, 169, 171
ovw_string.h, 184
OVwAckMapClose(), 228
OVwActionCallbackProc, 149
OVwAddActionCallback(), 148
OVwAddDropCallback(), 321
OVwAddInput(), 152
OVwAddSubmapContext(), 208
OVwAPILevel, 32
OVwAttributeLocateCB(), 310
OVwClearBackgroundGraphic,
229
OVwClearSymbolApp(), 279
Index
OVwCloseSubmap(), 210
OVwConfirmAddSymbolCB(),
303, 307
OVwConfirmAppConfigCB(),
303
ovwConfirmCapabilityChange,
295
OVwConfirmCapabilityChange
CB(), 295
ovwConfirmCompoundStatusCh
ange, 295
OVwConfirmCompoundStatusC
hangeCB(), 295
OVwConfirmConnectSymbolsC
B(), 303
ovwConfirmCreateObjects, 295
OVwConfirmCreateObjectsCB(),
295
ovwConfirmCreateSubmaps,
295
OVwConfirmCreateSubmapsCB
(), 295
OVwConfirmCreateSymbolCB(),
307
ovwConfirmCreateSymbols, 295
OVwConfirmCreateSymbolsCB(
), 295
ovwConfirmDeleteObjects, 295
OVwConfirmDeleteObjectsCB(),
295
ovwConfirmDeleteSubmaps, 295
OVwConfirmDeleteSubmapsCB(
), 295
OVwConfirmDeleteSymbolAlert
CB(), 267
ovwConfirmDeleteSymbols, 295
OVwConfirmDeleteSymbolsCB()
, 295
OVwConfirmDescribeCB, 304
ovwConfirmHideSymbols, 295,
297
OVwConfirmHideSymbolsCB(),
295
ovwConfirmManageObjects, 295
OVwConfirmManageObjectsCB(
), 295
ovwConfirmMoveSymbols, 295
OVwConfirmMoveSymbolsCB(),
295
ovwConfirmObjectStatusChang
e, 295
OVwConfirmObjectStatusChang
eCB(), 295
ovwConfirmSymbolStatusChang
e, 295
OVwConfirmSymbolStatusChan
geCB(), 295
ovwConfirmUnhideSymbols,
295, 298
OVwConfirmUnhideSymbolsCB
(), 295
ovwConfirmUnmanageEvent,
298
ovwConfirmUnmanageObjects,
295
OVwConfirmUnmanageObjects
CB(), 295
ovwCoordPosition, 249
OVwCreateComponentSymbol(),
248
OVwCreateConnSymbol(), 252
OVwCreateSubmap(), 206
OVwCreateSymbolAlert(), 266
OVwCreateSymbolByName(),
248
OVwCreateSymbols(), 246, 254
OVwDb
convenience routines, 188
OVwDbCreateField(), 171
OVwDbCreateObjectByHostna
me(), 182
OVwDbCreateObjectBySelectio
nName(), 182
OVwDbFieldIdToFieldName(),
171
469
Index
OVwDbFieldNameToFieldId(),
171
OVwDbGetEnumConstants(),
175
OVwDbGetEnumName(), 175
OVwDbGetEnumValue(), 175
OVwDbGetFieldInfo(), 174
OVwDbGetFieldValue(), 183
OVwDbGetFieldValues(), 185
OVwDbSetEnumConstants(),
172
OVwDbSetFieldValue(), 184
OVwDeleteSubmap(), 217
OVwDeleteSymbol(), 259
OVwDeleteSymbolAlert(), 267
OVwDeleteSymbols(), 259
OVwDisplaySubmap(), 209
OVwDone, 145
ovwDoNotDisplayLabel, 249
OVwDropCallbackProc(), 322
ovwEndSession, 295
OVwEndSessionCB(), 295
OVwError(), 155
OVwErrorMsg(), 155
OVwFieldBinding data
structure, 179
OVwFieldInfo data structure,
173
OVwFieldValue data structure,
176
OVwFileDescriptor(), 153
OVwFreeObjectInfo(), 289
OVwFreeSubmapList(), 223
OVwFreeSymbolInfo(), 284
OVwFreeSymbolList(), 287
OVwGetAppConfigValues(), 219
OVwGetAppName(), 157
OVwGetConnSymbol(), 285
OVwGetMapInfo(), 218
OVwGetObjectInfo(), 289
OVwGetSymbolInfo(), 284
OVwGetSymbolsByObject(), 290
470
in on-demand map
applications, 312
OVwHighlightObject(), 161
OVwHighlightObjects(), 161
OVwInit, 145
OVwInitSession, 145
OVwInitSession(), 331
OVwIsIdEqual, 156
OVwIsIdNull, 156
OVwListFieldEntry, 176
OVwListFieldValue, 176
OVwListObjectsOnMap(), 290
in on-demand map
applications, 312
OVwListOpenSubmaps(), 223
OVwListSubmaps(), 221
in on-demand map
applications, 312
OVwListSymbols(), 286
OVwListSymbolTypeCaps(), 287
OVwListSymbolTypes(), 287
OVwLocateResultList data
structure, 309
OVwLocateResultObject, 309
OVwMainLoop(), 152
OVwManageObject(), 313
OVwManageObjects(), 313
ovwMapClose, 295
OVwMapCloseCB(), 295
OVwMapInfo data structure,
218
ovwMapOpen, 224, 295
OVwMapOpenCB(), 224, 295
ovwMergeDefaultCapabilities,
249
OVwModifySubmap, 214
OVwModifySubmap(), 214
OVwModifySubmaps, 214
OVwModifySubmaps(), 214
ovwNoLayout, 230
ovwNoPosition, 249
ovwNoSymbolFlags, 248
ovwNselectionName, 184
OVwObjectIdList data
structure, 158
OVwObjectInfo data structure,
288
OVwPeekOVwEvent(), 154
OVwPending(), 154
OVwProcessEvent(), 154
OVwQueryAddSymbolCB(), 303
OVwQueryConnectSymbolsCB()
, 303
OVwQueryDescribeCB(), 304
OVwRemoveDropCallback(),
321
OVwRemoveSubmapContext(),
208
OVwReturnLocateResults(), 309
ovwSelectionListChange, 295
ovwSelectionListChange event,
159
OVwSelectionListChangeCB(),
295
OVwSelectObject(), 160
OVwSelectObjects(), 160
ovwSequencePosition, 249
OVwSessionID, 331
OVwSetAppConfigValues(), 220
OVwSetBackgroundGraphic,
229
OVwSetStatusOnObject, 280
OVwSetStatusOnObjects(), 281
OVwSetStatusOnSymbol(), 280
OVwSetStatusOnSymbols(), 281
OVwSetSymbolAlertText(), 267
OVwSetSymbolApp(), 279
OVwSetSymbolBehavior(), 276
OVwSetSymbolPosition(), 276
OVwSetSymbolStatusSource(),
280
OVwSetSymbolType(), 276
ovwsetupclient, 330
and management consoles, 327
OVwShowHelp(), 162
ovwStarCenterPosition, 249
Index
Index
OVwSubmapInfo data structure,

220
OVwSubmapList data structure,
213, 222
OVwSymbolCreateInfo data
structure, 254
OVwSymbolCreateList data
structure, 254
OVwSymbolInfo data structure,
282
OVwSymbolLabelLocateCB(),
310
OVwSymbolPosition data
structure, 249
OVwSymbolStatusLocateCB(),
310
OVwSymbolTypeLocateCB(),
310
OVwUnmanageObject(), 313
OVwUnmanageObjects(), 313
ovwUpdateSubmapDropAction,
321
ovwUpdateSubmapOverlay, 215
ovwUpdateSubmapWindowHeig
ht, 216
ovwUpdateSubmapWindowWidt
h, 216
ovwUpdateSubmapWindowX,
216
ovwUpdateSubmapWindowY,
216
ovwUpdateSymbolDropAction,
321
ovwUpdateSymbolExecVisCue,
271
ovwUpdateSymbolFlashing, 272
ovwUpdateSymbolPercentFull,
275
ovwUpdateSymbolSecondarySta
tus, 275
ovwUpdateTextAnnotationText,
273
OVwVerifyAdd(), 303
Index
OVwVerifyAppConfigChange(),
303
OVwVerifyConnect(), 303
OVwVerifyDeleteSymbol(), 307
OVwVerifyDescribeChange(),
304
OVwVerifyDrop(), 323
OVwXtMainLoop(), 153
P
page, 410
parent objects, 196
parent submaps, 196
paste and cut operations, 314
percent_full, 275
persistent submaps, 201, 202
symbol alerts, 263
PixmapBaseName, 116
PixmapSize, 116
Point to Point layout algorithm,
200
pop-up menus
registration example, 72
porting
applications, 32
position
changing symbol position, 276
setting for symbol, 249
predefined fields, 175
process flags, 54
process management, 383
ovspmd, 383
OVsPMD API, 387
ovstart, 383
ovstatus, 383
ovstop, 383
processing
map close event, 227
map open requests, 224
programming tips
acknowledging map close

events, 227
using
changing symbol behavior, 277
changing symbol labels, 278
checking event queue during
map synchronization, 226
choosing appropriate confirm
event, 306
deleting symbols, 259
deleting symbols and objects,
260
efficient use of map
information, 219
global attributes vs. mapspecific attributes, 291
guidelines for symbol
placement, 252
IP Map as application
integration example, 231
managing status, 312
map-specific object information
vs. global object
information, 289
placing symbols on background
graphic, 229
specifying selection name, 184
status management in
string constant definitions, 184
symbol alerts in persistent/
using compound presentation
status in on-demand map
applications, 312
pull-down menus
structure, 58
471
Index
R
receiving
map change notifications, 295
registering
map open events, 224
registration
drop action, 83
example pop-up menu, 72
overlay graphics, 111
symbol alert menus, 73
symbol alert types, 115
symbol pop-up menu, 70
registration files
application, 45
creating and using, 41
field, 118
processing, 43
symbol type, 100
types, 27
remote connection, 331
removing
submap context, 208
restricted status, 240
retrieving
information, 219
global object attributes vs.
map-specific attributes,
291
information about a specific
submap, 220
information about open map,
218
list of open submaps, 223
list of registered symbol types,
287
list of submaps, 221
map-specific object
information, 289
object information, 288291
symbol information, 253, 282
??, 284, ??287
reusing
472
submap window, 215

Ring layout algorithm, 200
root submaps, 197
routine
OVwManageObject(), 313
OVwManageObjects(), 313
OVwUnmanageObject(), 313
OVwUnmanageObjects(), 313
routines
(*OVwConfirmAddSymbolCB)(
), 302
(*OVwConfirmAppConfigCB)()
, 302
(*OVwConfirmConnectSymbol
sCB)(), 302
(*OVwConfirmDeleteSymbols
CB)(), 307
(*OVwConfirmDescribeCB)(),
302
(*OVwMapCloseCB)(), 228
(*OVwMapOpenCB)(), 224
(*OVwQueryAddSymbolCB)(),
302
(*OVwQueryAppConfigCB)(),
302
(*OVwQueryConnectSymbols
CB)(), 302
(*OVwQueryDeleteSymbolsCB
)(), 307
(*OVwQueryDescribeCB)(),
302
OVwAckMapClose(), 228
OVwAddActionCallback(), 148
OVwAddCallback(), 146
OVwAddInput(), 152
OVwAddSubmapContext(),
208
OVwBeginMapSync(), 225
OVwClearBackgroundGraphic
(), 229
OVwClearSymbolApp(), 279
OVwCloseSubmap(), 210, 211
OVwCopyMapInfo(), 219
OVwCreateComponentSymbol
(), 248
OVwCreateConnSymbol(), 252
OVwCreateSubmap(), 206
OVwCreateSymbol(), 246
OVwCreateSymbolAlert(), 266
OVwCreateSymbolByName(),
248
OVwDbCreateField(), 171
OVwDbDeleteObject(), 190
OVwDbFieldIdToFieldName(),
172
OVwDbFieldNameToFieldId(),
172
OVwDbGetEnumConstants(),
175
OVwDbGetEnumName(), 175
OVwDbGetEnumValue(), 175
OVwDbGetFieldInfo(), 174
OVwDbGetFieldValue(), 183
OVwDbGetFieldValues(), 185
OVwDbInit(), 168
OVwDbSetEnumConstants(),
172
OVwDbSetFieldValue(), 184
OVwDbUniqObjectName(),
181
OVwDbUnsetFieldValue(), 190
OVwDeleteSubmap(), 217
OVwDeleteSymbol(), 259
OVwDeleteSymbolAlert(), 267
OVwDeleteSymbols(), 259
OVwDisplaySubmap(), 209
OVwDone(), 145
OVwEndMapSync(), 225
OVwError(), 155
OVwErrorMsg(), 155
OVwFileDescriptor(), 154
OVwFreeObjectInfo(), 289
OVwFreeSymbolInfo(), 284
OVwFreeSymbolList(), 287
Index
Index
OVwGetAppConfigValues(),
219
OVwGetAppName(), 157
OVwGetConnSymbol(), 285
OVwGetMapInfo(), 218
OVwGetObjectInfo(), 289
OVwGetSelections(), 158
OVwGetSubmapInfo(), 220
OVwGetSymbolInfo(), 284
OVwGetSymbolsByObject(),
289
OVwHighlightObject(), 161
OVwHighlightObjects(), 161
OVwInit(), 145
OVwIsIdEqual(), 156
OVwIsIdNull(), 156
OVwListFields(), 174
OVwListObjectsOnMap(), 290
OVwListOpenSubmaps(), 223
OVwListSubmaps(), 221
OVwListSymbols(), 286
OVwListSymbolTypeCaps(),
287
OVwListSymbolTypes(), 287
OVwMainLoop(), 152
OVwModifySubmap, 214
OVwModifySubmaps, 214
OVwPeekOVwEvent(), 154
OVwRemoveSubmapContext()
, 208
OVwSelectObject(), 160
OVwSelectObjects(), 160
OVwSetAppConfigValues(),
220
OVwSetBackgroundGraphic(),
229
OVwSetStatusOnObject(), 280
OVwSetStatusOnObjects(),
281
OVwSetStatusOnSymbol(),
280
OVwSetStatusOnSymbols(),
281
Index
OVwSetSubmapName(), 215
OVwSetSymbolAlertText(),
267
OVwSetSymbolApp(), 279
OVwSetSymbolBehavior(), 276
OVwSetSymbolLabel(), 278
OVwSetSymbolPosition(), 276
OVwSetSymbolStatusSource()
, 280
OVwSetSymbolType(), 276
OVwShowHelp(), 162
OVwVerifyAdd(), 302
OVwVerifyAppConfigChange()
, 302
OVwVerifyConnect(), 302
OVwVerifyDeleteSymbol(),
307
OVwVerifyDescribeChange(),
302
OVwXtMainLoop(), 153
XtAddInput(), 153
Row/Column layout algorithm,
200
S
scalability, 202
secondary_status, 275
select(), 387
select(2), 153
selecting
objects via API, 160
selection lists, 158
change notification, 159
changing contents, 160
getting contents, 158
selection rules, 159
selection names, 178
predefined name field, 175
specifying, 184
selection rules
using in OVW programs, 159
SelectionRule
drop actions, 84
sequence position, 239
constraints, 239
setting, 250
server
communication, 330
setting
dynamically, 220
submap context, 208
severity levels
ISO 10164 standard, 241
shared submaps, 201
Solaris
compiling applications, 33
Star Center layout algorithm,
200
star center position, 239
constraints, 239
startup file (SUF), 383
status
changing colors, 241
changing the value, 280
colors, 239
compound, 198, 242
control of status summation
algorithm, 242
eliminating status conflict
between applications, 242
managing status in on-demand
map applications, 312
representing in parent object,
198
sources, 241
status source by object, 241
summation of status for
multiple symbols, 242
symbol, 242
symbol status, 242
symbols, 239
status categories, 240
473
Index
status colors
changing, 241
See also symbol alerts
status conditions, 240
status meaning, 240
status source
changing for a symbol, 280
string constant definitions, 184
submap context
defined, 196
removing, 208
setting, 208
submap geometry
setting, 216
submap IDs
testing, 156
submap overlay
ovwUpdateSubmapOverlay,
215
setting, 215
submap_overlay, 215
submap policies
submap types
submap_overlay, 215
submap_window_height, 216
submap_window_width, 216
submap_window_x, 216
submap_window_y, 216
submaps, 201
background graphic, 229
changing characteristics, 214
changing the name, 215
child, 196
choosing when to create, 209
closing, 210
context, 65
creating, 206
defined, 196
474
deleting, 217
displaying, 208
exclusive, 197, 202
geometry, 204
geometry definition, 203
getting information about
specific submap, 220
hierarchy, 210
home, 197
layout algorithm, 200
layout algorithm, defined, 238
list of symbols on, 286
listing open submaps, 223
meta-connection, 198
modifying, 214
modifying attributes of, 214
modifying name, 215
names, modifying for a
submap, 214
on-demand, 202
organizing hierarchy, 210
orphaned, 197
overlay, 204
overlay defined, 203
parent, 196
persistent, 202
planes, 201
presentation, 203
retrieving a list, 221
root, 197
scalability, 202
setting context, 208
setting geometry, 216
shared, 201
shared vs. exclusive, 201
size and location, 216
size and location of window,
203
targeting menu items for, 65
transient, 202
window reuse, 204
symbol alert types
registration, 115
symbol alerts, 260268

aligning text annotation, 266
and panner display, 243
base symbol, 243
base symbol description, 263
behavior, 261
components, 263
copying, 243
creating, 266
default action, 264
deleting, 267
description, 242
dynamically creating or
changing text annotation,
267
example action and callback
registration, 262
hiding, 243
menu registration, 73
on-demand submaps, 263
popup menu, 265
scaling, 243
See also status
size, 243
specifying text string for text
annotation, 266
text annotation, 264
transient/persistent submaps,
263
use model, 261
symbol classes
default capabilities, 108
default layout, 107
default status source, 107
defining with arcs, 106
defining with line segments,
103
optional specifications, 107
variety, 108
symbol IDs
testing, 156
symbol placement
automatic, 200
Index
Index
example showing use of

coordinate positioning, 251
guidelines, 252
See also layout algorithms
setting coordinate position,
251
setting sequence position, 250
using a grid, 251
symbol pop-up menu
registration, 70
symbol position
data structure, 249
251
symbol subclasses, 100
CursorSize, 110
default capabilities, 113
default layout, 113
default status source, 113
Filebase, 110
icon size recommendation, 111
optional specifications, 113
required specifications, 110
symbol type registration files,
100
defining connection symbol
class, 103
defining icon symbol class, 103
defining subclasses, 109
optional class specifications,
107
processing, 43
symbol class shape guidelines,
105
symbol type, 109
SymbolAlert, 74
SymbolAlertTypeName, 115
symbols, 100
adding, 303
using
Index
affect of copying on symbol

alerts, 243
as base for symbol alerts, 243
as status sources, 242
behavior, 238
changing appearance and
behavior, 269281
changing status values, 280
changing the label, 278
changing the position, 276
changing the status source,
280
changing the type, 276
clearing application interest,
279
connection, 100
connection symbol appearance,
274
connection symbol status, 274
connection, defined, 237
creating, 246??, 246, ??259
creating a symbol based on
object name, 248
creating a symbol based on
parent object, 248
creating connection symbols,
252
creating several with a single
call, 254
default behavior, 238
definition, 236
deleting, 259, 307
disabling executable symbol
visual cue, 272
during map editing, 300
example changing behavior,
278
example creating multiple
symbols with
executable, 238
executable symbol appearance,
271
explodable, 196, 238

filled connection symbols, 274
flags for creating, 248
flashing, 272
guidelines for deleting
symbols, 259
guidelines for deleting symbols
and objects, 260
icon, 100
icon, defined, 237
label, definition, 237
listing on a submap, 286
listing possible object
capabilities, 287
listing registered types, 287
making executable, 276
making explodable, 276
placement guidelines, 252
pop-up menu registration
example, 72
position, 238
primary status of connection
symbols, 275
registration of overlay
graphics, 111
registration of symbol alert
types, 115
representing multiple
connections between, 197
??, 284, ??287
secondary status of connection
symbols, 275
see status
setting application interest,
279
251
setting position, 249
sources of status, 241
475
Index
symbol type routines, 287

transparent, 270
type, 109, 275
type, definition, 237
varietys, 237
synchronizing
maps, 225
T
targeting menu items to
submaps, 65
testing status, 240
text_annotation, 273
textAnnotationBackgroundColor
, 273
textAnnotationColor, 273
TextRegion, 117
timer
map close acknowledgment,
227
tracing
and OVuTL API, 377
description of, 377
Transactions, 302
transient submaps
locating objects, 309
submap geometry, 216
symbol alerts, 263
when to use, 209
effects of map edits, 270
type
symbols, 275
types
symbol, 237
symbol type routines, 287
universal pathnames
over NFS, 327
unknown status, 240
unmanage status, 240
unmanaging
objects programmatically, 313
updating
map synchronization, 225
/usr/OV/help/$LANG, 131
V
varieties, 108
symbol, 237
version information
retrieving programmatically,
33
version statements, 52
visual cues
See also connection symbols
See executable symbols
See flashing symbols
See status
See symbol alerts
See transparent symbols
W
warning status, 240
windows
presentation of submaps, 203
reusing, 215
submap arrangement on
display, 204
Windows NT
memory use, 33
referencing global variables,
33
using non-debug libraries, 33
X
X event processing, 153
xcg92, 33
U
unique object names
generating, 181
476
Index

j1261 90007

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

j1261 90007

Uploaded by

Copyright:

Available Formats

HP OpenView Windows Developers

Manufacturing Part Number: J1261-90007

Copyright 1996 AirMedia, Inc.

1. Developing Applications for HP OpenView Windows

Drop Action Registration for HP-UX and Solaris Applications . . . . . 83

Field Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Customizing the Help Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133

Getting your Application Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Highlighting Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Getting/Setting Object Field Values . . . . . . . . . . . . . . . . . . . . . . . . . . . .183

Changing a Submap Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Opening and Closing Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Integrating your Application with an Existing Map Application . . . . 231

Creating Symbol Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260

Participating in Map Changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Participating in Map Locates In Transient Map Applications . . . . . . 309

Remote Application Execution (HP-UX and Solaris Only) . . . . . . . . . .333

11. Integrating Your Application with the HP OpenView Web

Application Configuration and Integration. . . . . . . . . . . . . . . . . . . . . . 365

Integration with NNM Automated Backup . . . . . . . . . . . . . . . . . . . . .

Integration via ovwMapClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .405

Figure 2-1. Menu Integration Example . . . . . . . . . . . . . . . . . . . . . . . . . .59

Table 2-1. Registration File Locations . . . . . . . . . . . . . . . . . . . . . . . . . . .41

Table 11-2. OV Web Launcher Configuration and Integration Points

What the Font Represents

For book or manual titles, and for manpage

Refer to the OVW Developers Guide.

You must follow these steps.

To specify a variable that you must supply

At the prompt type: rlogin

For glossary terms.

The distinguishing attribute of this

Text and items on the computer screen.

The Root map window ...

The system replies: Press Enter

Use the grep command ...

File and directory names.

Check to see if pmd is running.

Window/dialog box names

In the IP Internet map window...

Text that you must enter.

At the prompt, type: ovstatus.

Buttons on the user interface.

Click [NET]. Click on the [Apply]

A menu name followed by a colon (:)

Your comments on and suggestions for the documentation help us

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

Developing Applications for HP

Developing Applications for HP OpenView Windows

HP OpenView is a family of tools and services for managing local and

Developing Applications for HP OpenView Windows

Applications and the HP OpenView Platform

Developing Applications for HP OpenView Windows

The Basics of Developing Applications

Developing Applications for HP OpenView Windows

The HP OpenView Windows Registration Files

Developing Applications for HP OpenView Windows

The Help System

Developing Applications for HP OpenView Windows

Using the HP OpenView Windows

The OVw API functions are not thread safe.

While developers can implement much of an applications functionality

Developing Applications for HP OpenView Windows