A Guide for Java Developers

HP OpenView Integration Series

Manufacturing Part Number : T2579-90004 October 2006 Copyright 1990-2006 Hewlett-Packard Development Company, L.P.

Legal Notices
Warranty The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. The information contained herein is subject to change without notice. Restricted Rights Legend Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. Copyright Notices Copyright 1990-2006 Hewlett-Packard Development Company, L.P. Contains software from AirMedia, Inc. Copyright 1996 AirMedia, Inc. Trademark Notices Java and all Java based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Microsoft is a U.S. registered trademark of Microsoft Corporation. Windows NT is a U.S. registered trademark of Microsoft Corporation. Windows 2000 is a U.S. registered trademark of Microsoft Corporation. Windows and MS Windows are U.S. registered trademarks of Microsoft Corporation. Netscape and Netscape Navigator are U.S. trademarks of Netscape Communications Corporation Oracle is a registered U.S. trademark of Oracle Corporation, Redwood City, California.

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.

Documentation Updates
This manuals title page contains the following identifying information: Software version number, which indicates the software version Document release date, which changes each time the document is updated Software release date, which indicates the release date of this version of the software

To check for recent updates, or to verify that you are using the most recent edition of a document, go to: http://ovweb.external.hp.com/lpe/doc_serv/ You will also receive updated or new editions if you subscribe to the appropriate product support service. Contact your HP sales representative for details.

Support
You can visit the HP OpenView Support web site at: www.hp.com/managementsoftware/support HP OpenView online support provides an efficient way to access interactive technical support tools. As a valued support customer, you can benefit by using the support site to: Search for knowledge documents of interest Submit and track support cases and enhancement requests Download software patches Manage support contracts Look up HP support contacts Review information about available services Enter into discussions with other software customers Research and register for software training

Most of the support areas require that you register as an HP Passport user and sign in. Many also require a support contract. To find more information about access levels, go to: www.hp.com/managementsoftware/access_level To register for an HP Passport ID, go to: www.managementsoftware.hp.com/passport-registration.html

Contents
1. Developing Applications for HP OpenView Windows
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applications and the HP OpenView Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Basics of Developing Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The HP OpenView Windows Registration Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the HP OpenView Windows Java Programming Interface . . . . . . . . . . . . . . . . . Linking Application Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Developing Applications for the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OVW Generated Dialog Boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Consistent Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 23 24 25 26 27 30 30 32 33 34

2. Using the HP OpenView Windows Java libovw API

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The OVW Programming Model and Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LibOvw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LibOvwException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ICallback and OVwEventAdapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Role of Registration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Outline of a Sample Program for an Applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Outline of a Sample Program for an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connecting Applications to HP OpenView Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . Disconnecting Applications from HP OpenView Windows . . . . . . . . . . . . . . . . . . . . . . Error Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieving a Methods Result Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Converting a Result Code to a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implementing the ICallback Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OVW Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Action Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Handling Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting your Application Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting the Object Selection List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selection Rules and the Selection List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The ovwSelectionListChange Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Selection List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Highlighting Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 37 38 40 40 41 42 45 50 51 52 52 52 54 54 57 61 68 69 70 71 71 73 74

Contents
3. Creating and Using Objects and Fields
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The HP OpenView Windows Object Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Base Methods and their Variants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the FRF versus the API to Create Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Fields Programmatically. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Converting between Field Names and Field IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Enumeration Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieving Field Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Predefined Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Selection Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating Unique Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Objects by Hostname or Selection Name . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting/Setting Object Field Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Field Value Get/Set Invocations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other Ways to Get and Set Single Field Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting All Fields Associated with an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Convenience Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Steps for Deleting an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining when to Delete Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 77 77 77 78 78 79 79 79 80 81 81 82 83 83 83 85 86 87 87 88 89 90 92 92 92 93

4. Creating and Using Submaps

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Map and Submap Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Submaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Symbol Status and Submaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Relationship Between Maps and Submaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Contents
Submap Layout Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submap Planes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Shared vs. Exclusive Submaps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Persistent vs. Transient Submaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submap Presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Submaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Submap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying a Submap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Choosing When to Create a Submap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Organizing your Submap Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Closing a Submap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loading and Unloading Submaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing Submap Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing a Submap Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Submap Overlay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Submap Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting a Submap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Map and Submap Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Map Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Application Configuration Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Submap Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Opening and Closing Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Processing a Map Open Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Processing a Map Close Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Submap Background Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting and Clearing Background Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Symbol Placement and Background Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Image Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integrating your Application with an Existing Map Application . . . . . . . . . . . . . . . . Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 103 104 104 105 108 108 111 112 112 113 114 117 118 118 119 120 121 121 122 123 127 127 131 133 133 134 134 135 136

5. Creating and Using Symbols

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Characteristics of Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Symbols versus Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Symbol Characteristics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Icon Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 139 139 139 149 149

Contents
Creating Connection Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Multiple Symbols with a Single Invocation . . . . . . . . . . . . . . . . . . . . . . . . Deleting Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Symbol Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing Symbol Appearance and Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing a Symbols Appearance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing a Symbols Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing a Symbols Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing a Symbols Behavior. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing a Symbols Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting or Clearing Application Interest in a Symbol . . . . . . . . . . . . . . . . . . . . . . . Changing Status or Status Source. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieving Symbol Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OVwSymbolInfo Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieving Symbol Information with OVwGetSymbolInfo(). . . . . . . . . . . . . . . . . . . Getting Connection Symbol Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting a List of Symbols from a Submap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Symbol Type methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieving Object Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The OVwObjectInfo Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieving Object Information with OVwGetObjectInfo() . . . . . . . . . . . . . . . . . . . . Getting Symbol IDs Associated with an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting a List of All Objects on a Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global Attributes Versus Map-Specific Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 157 159 160 170 170 177 178 178 180 181 182 184 184 184 185 187 187 188 188 189 189 190 190 192

6. Map Editing and Map Events

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiving Notification of Map Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Map Editing Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Hidden Symbol Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Manage/Unmanage Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Participating in Map Changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Map Editing Interactions with OVW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Query-Verify-Confirm methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Choosing Which Confirm Event to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 195 195 197 198 200 200 203 206

10

Contents
Deleting a Symbol. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Participating in Map Locates In Transient Map Applications . . . . . . . . . . . . . . . . . . 209 Returning Locate Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 Locating Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 Considerations for Transient Submap Applications . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Managing Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 Cut and Paste Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 Customizing Drag and Drop Operations for HP-UX, Solaris, and Linux Applications . . 217 Drag and Drop Behavior. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Customization Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 Assigning a Drop Action To a Drop Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 Associating a Drop Action with an Application Callback. . . . . . . . . . . . . . . . . . . . . 222 Application Drop Callback Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

7. Developing Internationalized and Localized Applications

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HP OpenView Windows Internationalization Support . . . . . . . . . . . . . . . . . . . . . . . . String Overloading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Developing Internationalized and Localized HP OpenView Windows Applications . Application Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Localizing the Registration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OVwSymbolType Argument. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Trapd.conf and SNMP traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Consistency and Interoperability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Warnings for Non-Internationalized Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 229 230 232 234 235 235 237 239 239 240 241 243

8. Integrating Your Application with the HP OpenView Web

Model of Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Web Session Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Application Configuration and Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Browser Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 247 247 247 251 254

11

Contents
Using OVwww APIs to Access Session Information . . . . . . . . . . . . . . . . . . . . . . . . . 254

A. Guidelines for Documenting Map Applications

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Map Application Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Registration Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Symbol Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dependencies on other Map Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 263 264 265 266 267 268 269

B. An Example Applet
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 Instructions for Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

C. Using the OVw API Reference Pages

Introductory Reference Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printing Reference Pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Run-Time Routines By Category. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Run-Time Routines By Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 283 285 290

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

12

Tables
Table 3-1. Convenience Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90 Table 4-1. Layout Algorithms for Submaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102 Table 5-1. Forms for Positioning Symbols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142 Table 5-2. HP OpenView Status Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143 Table 5-3. OVW - ISO Equivalents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144 Table 5-4. Symbol Presentation Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147 Table 6-1. OVW Events and ICallback Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . .195 Table 6-2. Locate Query Method Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212 Table 8-1. NNM Web CGI Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249 Table 8-2. OV Web Launcher Configuration and Integration Points . . . . . . . . . . . .252 Table C-1. OVw API Manpages Grouped by Category . . . . . . . . . . . . . . . . . . . . . . . .285 Table C-2. Function to Reference Page Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . .290

13

Tables

14

Figures
Figure 4-1. Relationship between Maps and Submaps . . . . . . . . . . . . . . . . . . . . . . .101 Figure 5-1. Symbol Alert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164 Figure 6-1. Query-Verify-Confirm Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . .202 Figure 8-1. Services and Files for the Web Components . . . . . . . . . . . . . . . . . . . . . .248

15

Figures

16

Conventions
The following typographical conventions are used in this manual. Font Italic What the Font Represents Book or manual titles, and manpage names Emphasis A variable you must supply when entering a command Bold Computer Glossary terms Text and items on the computer screen Command names File and directory names Process names Window/dialog box names Computer Bold
Keycap

Example Refer to the OVW Developers Guide. You must follow these steps. At the prompt type: rlogin your_name where you supply your login name. The distinguishing attribute of this class... The Root map window ... The system replies: Press Enter Use the grep command ... /usr/bin/X11 Check to see if pmd is running. In the IP Internet map window... At the prompt, type: ovstatus. Press Return. Click [NET]. Click the [Apply] button. Select Edit:Find->Objects by Comment

Text you must enter Keyboard keys Buttons on the user interface 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.

[Button] Menu Items

17

18

Contact Information
Technical Support Technical support information can be found on the HP OpenView World Wide Web site at: http://openview.hp.com/ 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://docs.hp.com Or you can fill out the form provided in electronic form with NNM: Windows: install_dir\ReleaseNotes\nnm_doc_reply.txt UNIX: /opt/OV/ReleaseNotes/nnm_doc_reply.txt

Fill out one form per manual and email it to: ovdoc@fc.hp.com If you encounter serious errors in the documentation that impair your ability to use NNM, please contact your support representative so that your feedback can be entered into CHARTS (the HP Change Request Tracking System). Training Information For information on current HP OpenView training available, see the HP OpenView World Wide Web site at: http://openview.hp.com/ Select the support panel to obtain information about scheduled classes, training at customer sites, and class registration.

19

20

Developing Applications for HP OpenView Windows

Chapter 1

21

Developing Applications for HP OpenView Windows Overview

Overview
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: Applications and the HP OpenView Windows platform The basics of developing HP OpenView applications, including using the help system and registration files

22

Chapter 1

Developing Applications for HP OpenView Windows Supported Platforms

Supported Platforms
When a developer uses the Java bindings to OVw (hereafter referred to as Java libovw API) in an applet, one of the following browsers is required: Netscape Communicator. (Refer to the Release Notes, System Configurations, for details on supported versions.) Microsoft Internet Explorer. (Refer to the Release Notes, System Configurations, for details on supported versions.)

Chapter 1

23

Developing Applications for HP OpenView Windows 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.

24

Chapter 1

Developing Applications for HP OpenView Windows The Basics of Developing Applications

The Basics of Developing Applications

Developers construct HP OpenView Windows applications using two types of components: registration files and the OVW programming libraries (the Java libovw API and the Java Web Session management 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 Java libovw API. The Java libovw API gives you much more control over the behavior of OVW applications, at the cost of more programming complexity. In addition to developing applications that run as subprocesses of ovw, developers may create remote applications (implemented as Java applets) that integrate with the HP OpenView Web UI. Such applets require the Java Web Session management API in order to be fully integrated into the HP OpenView Web UI. See Chapter 8, Integrating Your Application with the HP OpenView Web, for further discussion of requirements forWeb UI integration.

Chapter 1

25

Developing Applications for HP OpenView Windows 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: 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. The registration files also provide control over which remote applications may access the ovw session. If a remote application (applet) is not named in a registration file, it is unable to make a connection with the indicated ovw session. 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.

26

Chapter 1

Developing Applications for HP OpenView Windows Using the HP OpenView Windows Java Programming Interface

Using the HP OpenView Windows Java Programming Interface

NOTE All of the API calls and event handlers in the Java libovw API are thread safe. The notifications are invoked under a different thread than the main applet thread. To make use of the thread safe nature of this library, you must make sure that data accessed by your methods while handling notifications is synchronized.

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 with Java bindings (hereafter referred to as Java libovw API). This library runs on any platform whether or not NNM supports it. The only requirement is the availability of a JDK 1.1 compliant Java virtual machine. The Java libovw API is fully distributed. It communicates with the NNM processes via sockets and can run on any machine with an appropriate Java virtual machine. The Java libovw API lets developers access the full breadth of HP OpenView Windows functionality. The Java libovw API might appear intimidating at first, since it contains over 100 API methods. As youll soon see, though, the API methods are organized into groups which make them more manageable. Subsequent chapters present the Java libovw API methods in groups, according to the functionality they provide. Also, the Java libovw API lets you perform the same programming task in different ways. Though you can use the full breadth of the Java libovw API if you want, a basic understanding of a few key methods in each group allows you to implement fairly sophisticated applications.

Chapter 1

27

Developing Applications for HP OpenView Windows Using the HP OpenView Windows Java Programming Interface There are essentially six groups of Java libovw API methods, organized as follows. The first five groups are implemented in the LibOvw class and the notifications are described by ICallback. The notifications must be implemented in a user-defined class that is derived from ICallback or OVwEventAdapter. Application integration There are a small number of methods that integrate your application with the HP OpenView Windows. Every application that uses the Java libovw API needs to use at least some portion of these calls. These methods 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 Java libovw API methods that operate on objects and fields. These methods 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 methods The Java libovw API contains many methods that let you create and modify submaps, as well as retrieve information about maps and submaps. A few Java libovw API methods let you change the background images of submaps. Symbol methods These methods create symbols, alter symbol behavior and appearance, and get information about an object as it exists on a map. User verification There are several Java libovw API methods that allow a program to verify changes that a user attempts to make to maps and objects via the user interface.

28

Chapter 1

Developing Applications for HP OpenView Windows Using the HP OpenView Windows Java Programming Interface ICallback interface/OVwEventAdapter class The Java libovw API uses the notification methods of the ICallback interface to communicate with applications when various events occur. OVwEventAdapter is a class that implements all methods of the ICallback interface with empty methods. One may derive a class directly from OVwEventAdapter as a convenience if only a few methods need to be implemented and no other derivation is required. 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. Note that these reference pages were written for the OVw API for C programs. Most of the information is equally applicable to the Java libovw API for Java programs. OVwApiIntro 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. This reference page provides an introduction to the HP OpenView session API for CGI programs. 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. This reference page provides complete specifications for the HP OpenView Web Launcher registration file including the registration file grammar.

OVwwwIntro

OVwRegIntro

LauncherRegIntro

Chapter 1

29

Developing Applications for HP OpenView Windows Using the HP OpenView Windows Java Programming Interface NetworkPresenterRegIntro This reference page provides complete specifications for the HP OpenView Network Presenter Registration File.

Linking Application Programs

Applications that use the HP OpenView Windows Java programming libraries need to import the appropriate classes or all classes from the libovw package with import hp.ov.libovw.*;. Applets that use the Java Session API should import all classes from the Session package with import hp.ov.session.*;.

NOTE

When methods and parameters are described throughout the text, the class information is included for all cases except when the class is hp.ov.libovw.LibOvw.

Developing Applications for the Web

Developers and administrators can integrate their web-based applications with NNM through integration points in the HP OpenView Web Launcher and the Network Presenter by editing registration and configuration files. These integration points are described in the online manual, Creating and Using Registration Files, and in Chapter 8, Integrating Your Application with the HP OpenView Web. In addition, Java doc files for the Java bindings to libovw APIs are available in: /opt/OV/www/htdocs/C/java_libovw/doc on UNIX systems.

install_dir\www\htdocs\C\java_libovw\doc on Windows systems.

The jar file containing the Java class files is available in: /opt/OV/www/htdocs/classes on UNIX systems.

install_dir\www\htdocs\classes on Windows systems.

30

Chapter 1

Developing Applications for HP OpenView Windows Using the HP OpenView Windows Java Programming Interface Two libraries are included, the optimized library, libovw.jar, and the debuggable library, debug.libovw.jar. Either library is suitable for development purposes, though the optimized version has no debug information and occupies less space.

Chapter 1

31

Developing Applications for HP OpenView Windows 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.

32

Chapter 1

Developing Applications for HP OpenView Windows 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.

Chapter 1

33

Developing Applications for HP OpenView Windows Summary

Summary
Developers need to make use of two major components to implement HP OpenView Windows applications: registration files and the Java libovw API. Applets integrated into the Web UI additionally require the Java session 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. See the online manual, Creating and Using Registration Files, in the Welcome collection. The Java libovw API is required to implement more sophisticated HP OpenView Windows applications. The Java libovw API contains over 100 methods and notifications, which allow you to control all aspects of an applications behavior. The Java libovw API is the subject of much of the rest of this manual. Lastly, 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.

34

Chapter 1

Using the HP OpenView Windows Java libovw API

Chapter 2

35

Using the HP OpenView Windows Java libovw API Overview

Overview
This chapter presents application design concepts and Java libovw API methods that are found, in some form, in almost all OVW applications. This chapter describes 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 the online manual, Creating and Using Registration Files. Concepts and techniques presented in this chapter appear throughout the remainder of this manual. This chapter discusses: the OVW programming model connecting applications to HP OpenView Windows disconnecting applications to HP OpenView Windows error handling implementing the ICallback interface getting your application name getting the object selection list highlighting objects on the map

36

Chapter 2

Using the HP OpenView Windows Java libovw API The OVW Programming Model and Java

The OVW Programming Model and Java

HP provides two Java packages for applications and applet integration with HP OpenView Windowshp.ov.session and hp.ov.libovw. To interact with ovw, applications need to retrieve ovw session IDs and language encoding information directly from ovw through registration files. However, when creating applets and integrating applets into the HP OpenView Launcher or Network Presenter, additional information needs to be retrieved from the Java session management API. The hp.ov.session package is provided to handle HP OpenView session management and is discussed in more detail in Chapter 8, Integrating Your Application with the HP OpenView Web. Sample programs illustrating its use are provided in the following directories: /opt/OV/www/htdocs/C/launcher/javadoc/sample/ TestSession.java on UNIX systems.

install_dir\www\htdocs\C\launcher\javadoc\sample\ TestSession.java on Windows systems.

The hp.ov.libovw package provides a set of classes that allows a Java application or applet to interact with an existing HP OpenView session. Various levels of interaction are possible, ranging from a simple connect/query/disconnect level to a full integration. Full integration includes registration of application-specific menus and actions with OVW and participation of user-initiated OVW query/verify/confirm sequences. The level of integration and actual participation of your applet or application is determined by its use of the APIs provided.

NOTE

If you are already familiar with the C/C++ libovw API, you find a nearly one-to-one correspondence between the functions provided in the C/C++ API and the methods provided in the various classes in the Java libovw API. The main differences between the APIs are in the organization of functionality into classes and the exclusion of some functions which were inappropriate in the Java language and programming paradigm.

Chapter 2

37

Using the HP OpenView Windows Java libovw API The OVW Programming Model and Java The following mainstream classes and interfaces are provided in the Java libovw API (hp.ov.libovw package): LibOvw LibOvwException ICallback OVwEventAdapter

Several other classes are provided in the hp.ov.libovw package, primarily in support of the above-mentioned classes. The additional classes are explained in later discussions directed at specific related functionality. The following discussion focusses on the four high-level classes and describes their purpose and relationship to integration with OVW.

LibOvw
LibOvw is the primary provider of methods for: Managing the connection to and disconnection from the OVW session and database Creating, manipulating, and destroying submaps and symbols Establishing notification for OVW events

To establish a connection with the HP OpenView session, an instance of LibOvw must be created. The lifetime of this session is typically the lifetime of the applet or application. Two constructors are provided for the LibOvw class. Here are their signatures: LibOvw() LibOvw(String encoding)

The first constructor takes no arguments and uses the default encoding when it establishes communications connections with the ovw server process on the management server. This is appropriate only when you know that no localized data is transferred to or from ovw. The second constructor requires a String argument that describes the appropriate encoding to use when connecting to an ovw server process that is operating in a non-English locale and may require transfer of

38

Chapter 2

Using the HP OpenView Windows Java libovw API The OVW Programming Model and Java non-English data to or from the management server. How the argument is retrieved depends on whether the program is implemented as a Java applet or Java application. If the program is implemented as a Java applet integrated into the Web UI, the required argument may be obtained through the Web UI Session Management API as indicated in the sample code below:
import java.applet.Applet; import hp.ov.libovw.*; // access libovw package classes import hp.ov.session.*; // access ovw web session management package classes public class MyApplet extends Applet { ... Session session; try { session = new Session(this); // Session requires an Applet } catch (NoSessionException e) { // handle NoSessionException return; } LibOvw libovw; String encoding = session.getJavaConverter(); if (encoding == null) { libovw = new LibOvw(); } else { libovw = new LibOvw(encoding); }

For further details about the Session API, please see the description found in Chapter 8, Integrating Your Application with the HP OpenView Web. If your program is implemented as a Java application, you need to retrieve the encoding string from the Java runtime environment directly. This can be accomplished as indicated in the following code snippet:
import java.io.InputStreamReader; ... InputStreamReader isreader = new InputStreamReader(System.in); String encoding = isreader.getEncoding(); try { isreader.close(); // closes the reader, not System.in } catch (Exception e) { ; }

Chapter 2

39

Using the HP OpenView Windows Java libovw API The OVW Programming Model and Java
isreader = null; LibOvw libovw; if (encoding == null) { libovw = new LibOvw(); } else { libovw = new LibOvw(encoding); }

The code above creates an InputStreamReader with System.in as its argument, retrieves the readers encoding value, and then closes the reader. Because the InputStreamReader constructor was invoked with no encoding string in its constructor, it should return the default value assigned by the system.

LibOvwException
The Java libovw API uses the Java exception-handling features to pass information back to the calling method in the event an error occurs. This exception handling replaces the error codes returned from methods in the C/C++ API. LibOvwException extends java.lang.RuntimeException and provides information about the type of error encountered when thrown. The error codes are defined as integer values in the LibOvwException class. To catch the exceptions, the relevant operations must be bracketed with try ... catch blocks.

ICallback and OVwEventAdapter

ICallback provides an interface to allow registered objects to be notified when specified events occur in OVW. An object implementing the ICallback interface has methods invoked, as appropriate for the type of OVW event. An adapter class, OVwEventAdapter, implements the ICallback interface and is provided for ease of implementation in the usual cases where class derivation does not preclude its use. OVwEventAdapter simply provides empty definitions for each method provided in the ICallback interface. Objects that implement the ICallback interface may be registered for notification through the LibOvw.OVwAddCallback() method. This method requires two argumentsan event mask and the object (derived

40

Chapter 2

Using the HP OpenView Windows Java libovw API The OVW Programming Model and Java from ICallback) to be registered. This method throws a LibOvwException and the relevant operations must be bracketed with try...catch blocks. The event mask is the result of logically OR-ing together bit masks provided in the OVwEvents class. The event mask indicates the types of OVW events for which the object should be notified. A bit mask is provided in OVwEvents for each of the event types for which notification may occur. ICallback and OVwEventAdapter may also be used to implement application-defined events, action events. Action events are discussed in more detail in Chapter 6, Map Editing and Map Events.

The Role of Registration Files

As mentioned earlier, you may implement a Java libovw program as an applet or an application. The implementation you choose depends upon the intended functionality of your program, whether it needs to be available on the web, and whether or not your program needs the ability to write files (applets may not write files unless they are trusted). Applets and applications both require registration files to integrate with the Web UI and ovw, respectively, but they will end up with different contents and in different locations depending on which integration method you choose. Detailed discussion of registration files is included in the online manual Creating and Using Registration Files. However, a brief synopsis of their use is included here to aid in the discussion of program structure. Any program that attempts to access ovw via the Java libovw API must be registered with ovw. Registration is accomplished by placing a registration file in the locale-specific ovw registration directory. Additional registration files are required if you are attempting to integrate an applet into the ovw Web UI. These will be placed under the locale-specific registration directories for the HP OpenView Launcher and/or the HP OpenView Network Presenter. Each program requires an ovw session ID in order to connect to ovw. A common method of passing session IDs to an application is through the registration file. The session ID may be passed to an applet by way of HTML applet parameters generated by a CGI program or directly through an HTML file. For discussion purposes here, assume that

Chapter 2

41

Using the HP OpenView Windows Java libovw API The OVW Programming Model and Java applications are started with a -session command line argument whose value is provided through the $OVwSessionID ovw variable, and that applets are provided with an OvwSessionId applet parameter.

Outline of a Sample Program for an Applet

An applets registration file only needs to allow access to ovw. It does not need to provide an invocation command or any menu actions. Heres an example for a sample applet MyOvwApplet:
/* ** Application registration file for MyOvwApplet, a sample Java applet ** that tests the Java LibOvw API. */ Application "MyOvwApplet" { Description { "HP OpenView", "Applet to test Java LibOvw API from a web browser" } DisplayString "MyOvwApplet"; Version "MyOvwApplet 1.0"; Copyright { "Copyright (c) 1990-2002 Hewlett-Packard Company", "All rights reserved" } }

The following code illustrates the general form a Java applet takes when integrated with the Web UI:

import java.applet.Applet;

import hp.ov.libovw.*; // access libovw package classes import hp.ov.session.*; // access ovw web session management package classes public class MyOvwApplet extends Applet implements ICallback { Session session; LibOvw libovw;

42

Chapter 2

Using the HP OpenView Windows Java libovw API The OVW Programming Model and Java
public void init() { try { session = new Session(this); } catch (NoSessionException e) { // handle NoSessionException return; } String encoding = session.getJavaConverter(); if (encoding == null) { libovw = new LibOvw(); } else { libovw = new LibOvw(encoding); } // OvwSessionId should be of the form <machine:instanceNumber> String ovwSessionId = getParameter("OvwSessionId"); try { libovw.OVwInitSession("MyOvwApplet", ovwSessionId); } catch (LibOvwException ex) { // handle connection exception, then finish return; } /*** Add to mask all event callbacks we plan on handling. We must implement each of the corresponding methods from ICallback. ***/ long eventMask = OVwEvents.ovwMapCloseMask|OVwEvents.ovwEndSessionMask; int ret; try { ret = libovw.OVwAddCallback(eventMask, this); } catch (LibOvwException ex) { // handle the exception libovw.OVwDone(); libovw = null; return; } /*** perform some initial operations not dependent on callbacks for example: try { OVwMapInfo map = libovw.OVwGetMapInfo(); } catch (LibOvwException ex) { }

Chapter 2

43

Using the HP OpenView Windows Java libovw API The OVW Programming Model and Java
***/ System.out.println("MyOvwApplet: connected"); } /*** Here we implement the portions of ICallback which are associated with the mask passed in to LibOvw.OVwAddCallback above. When ICallback is implemented directly, the entire interface must be implemented. When OVwEventAdapter is used, only those methods of interest to your applet or application need to be provided. ***/ public void OVwMapCloseCB(OVwMapInfo map, int closeTime, int eventSource) { System.out.println("OVwMapCloseCB"); libovw.OVwAckMapClose(map, 0); } public void OVwEndSessionCB(boolean normalEnd) { System.out.println("OVwEndSessionCB"); libovw.OVwDone(); libovw = null; } /*** remaining OVw<something>CB methods ***/ }

In the init() method, all appropriate initialization is performed. This includes web session management, applet parameter retrieval, LibOvw instance creation, connection to the indicated ovw session, registration for events of interest, and initial actions. Since this is an applet, it will continue to run within the Java Virtual Machine and be available to handle callbacks as they arrive. In order to actually launch this applet, one would need to invoke the Java code from a Web browser using an HTML page or, if integrated with the Launcher, a Web Launcher Registration File (WLRF). See the Chapter 8, Integrating Your Application with the HP OpenView Web, for instructions on how to accomplish this, or the online reference page for LauncherRegIntro.

44

Chapter 2

Using the HP OpenView Windows Java libovw API The OVW Programming Model and Java

Outline of a Sample Program for an Application

An application needs a more involved registration file. This registration file includes a command to invoke the application. You can accomplish this through a shared command or a menu item action. You need to ensure that the Java classes are accessible to any commands included in the registration file. You can accomplish this by setting the CLASSPATH variable or by passing the information on the command line. Here is a sample registration file using the menu action approach with command-line classpath information and all supporting classes provided in a single Java archive file:
/* ** Application registration file for MyOvwApp, a Java program intended ** to test the Java LibOvw API as an application running under ovw. */ Application "MyOvwApp" { Description { "HP OpenView", "Application to test Java LibOvw API in localized environments" } DisplayString "MyOvwApp"; Version "MyOvwApp 1.0"; Copyright { "Copyright (c) 1990-2002 Hewlett-Packard Company", "All rights reserved" } MenuBar "Java API" { "MyOvwApp" f.action "ovwApp"; } Action "ovwApp" { Command "xnmappmon -cmd java -cp \"/opt/OV/www/htdocs/classes/myOvwApp.jar\" MyOvwApp -session $OVwSessionID"; } }

xnmappmon is the invoking command because it allows the output of the application to be captured and displayed in a console window.

Chapter 2

45

Using the HP OpenView Windows Java libovw API The OVW Programming Model and Java The actual code for an application might look like this:
import java.io.InputStreamReader; // access InputStreamReader import hp.ov.libovw.*; // access libovw package classes public class MyOvwApp extends OVwEventAdapter { /** * main() provides an entry point for invoking MyOvwApp * as a Java application. Here we get the arguments we * need in application fashion. */ public static void main(String args[]) { String session = getSessionArg(args); String encoding = getDefaultEncoding(); MyOvwApp app = new MyOvwApp(); app.connect("MyOvwApp", session, encoding); app.waitForDisconnect(); } /* MyOvwApp instance variables */ LibOvw libovw; /** * connect accepts the arguments connection class name, session * specification and encoding string, and creates an instance * of LibOvw (using the encoding if appropriate), and initiates * a connection to the indicated session. Once connected, it * registers itself as a handler for some callbacks. */ void connect(String className, String session, String encoding) { if (encoding == null) { libovw = new LibOvw(); } else { libovw = new LibOvw(encoding); } try { libovw.OVwInitSession(className, session); } catch (LibOvwException ex) { stopMe(); return; } // add handler, mask indicates which callbacks are of interest

46

Chapter 2

Using the HP OpenView Windows Java libovw API The OVW Programming Model and Java
long mask = OVwEvents.ovwMapCloseMask|OVwEvents.ovwEndSessionMask; try { libovw.OVwAddCallback(mask, this); } catch (LibOvwException ex) { libovw.OVwDone(); stopMe(); return; } System.out.println("MyOvwApp: connected"); } /** * stopMe resets libovw to set up termination conditions * for waitForDisconnect() */ public void stopMe() { libovw = null; } /** * waitFor causes the current thread to sleep for sec seconds */ void waitFor(int sec) { try { Thread.sleep(sec*1000); } catch (Exception e) { ; } } /** * waitForDisconnect loops while checking the value of * the variable libovw. While libovw is non-null, the * loop causes its thread to sleep for 1 second. Other * mechanisms could be utilized to implement a non-sleeping * wait loop. Left as an exercise for the reader. */ public void waitForDisconnect() { int ticks = 0; while (libovw != null) { System.out.println("tick(" + (ticks++) + ")"); waitFor(1); } } /** * getSessionArg looks for an argument preceded by "-session" and, * upon locating it, performs a simple transformation to remove * extraneous process information, then returns the transformed value.

Chapter 2

47

Using the HP OpenView Windows Java libovw API The OVW Programming Model and Java
*/ static String getSessionArg(String args[]) { String session = "localhost"; for (int a=0; a < args.length; a++) { if (args[a].equalsIgnoreCase("-session") && ((a+1) < args.length)) { session = args[a+1]; break; } } // little known fact: if the PID of the NNM process invoking // an application is non-zero (which can happen when an application // is invoked as a subprocess of ovw), the OVwSessionId will be of // the form "machine:session.PID". Deal with it... int colon = session.indexOf(":"); if (colon > 0) { String colonStr = session.substring(colon); int dotAfterColon = colonStr.indexOf("."); if (dotAfterColon > 0) { session = session.substring(0,colon+dotAfterColon); } } return session; } /* * getDefaultEncoding creates an InputStreamReader with a single * argument, retrieves its encoding value, and then closes the * reader. Because the InputStreamReader was not passed an * encoding string in its constructor, it should return the default * value assigned by the system. */ static String getDefaultEncoding() { InputStreamReader isreader = new InputStreamReader(System.in); String enc = isreader.getEncoding(); try { isreader.close(); } catch (Exception e) { ; } return enc; } /*** Here we implement only those portions of OVwEventAdapter

48

Chapter 2

Using the HP OpenView Windows Java libovw API The OVW Programming Model and Java
which are associated with the mask passed in to LibOvw.OVwAddCallback above. ***/ public void OVwMapCloseCB(OVwMapInfo map, int closeTime, int eventSource) { System.out.println("OVwMapCloseCB"); libovw.OVwAckMapClose(map, 0); } public void OVwEndSessionCB(boolean normalEnd) { System.out.println("OVwEndSessionCB"); libovw.OVwDone(); stopMe(); } }

In the main() method, we retrieve needed arguments from the command line and from the runtime environment. These are passed to app, a new instance of MyOvwApp. app is then requested to connect and wait until it is finished processing callbacks. The class MyOvwApp creates an instance of LibOvw for use during connection to the indicated ovw session and registers for events of interest. Since it is an application, MyOvwApp must be able to keep its main thread alive, otherwise it will not be around to handle callbacks as they arrive. The while loop implemented in waitForDisconnect() handles this, terminating the loop and thus the thread when the connection to ovw ends and the instance variable libovw is reset to null.

Chapter 2

49

Using the HP OpenView Windows Java libovw API Connecting Applications to HP OpenViewWindows

Connecting Applications to HP OpenView Windows

There are three basic steps that your HP OpenView Windows application must perform. It must Implement the ICallback interface (described on page 54). Connect to HP OpenView Windows (described in this section). Disconnect from HP OpenView Windows (see page 51).

To connect your application to HP OpenView, invoke the OVwInitSession() method. The OVwInitSession() method initializes a connection from a specific application to a specific OVW session and ensures that the object database connection is consistent with the GUI session. No other Java libovw API invocations can occur before your application connects to HP OpenView Windows. After the LibOvw.OVwInitSession() invocation has been issued, you are free to issue any other invocations in the Java libovw API. The OVwInitSession() method has two possible signatures. The first signature is the use of OVwInitSession() to initialize communication with ovw and ovwdb using the default object database port of 2447. The second signature is the use of OVwInitSession() to initialize synchronized communication with ovw and ovwdb by using a specific ovwdb port:
public void OVwInitSession(String appName, String sessionID) throws LibOvwException public void OVwInitSession(String appName, String sessionID, int ovwdbPort) throws LibOvwException

50

Chapter 2

Using the HP OpenView Windows Java libovw API Disconnecting Applications from HP OpenView Windows

Disconnecting Applications from HP OpenView Windows

When your application has finished interacting with OVW, you must disconnect from OVW. This is done by invoking the OVwDone() method. The LibOvw.OVwDone() method cleans up internal API classes and closes the connection from the application to OVW. The OVwDone() method that ends a session with OVW has the following signature:
public synchronized void OVwDone()

The OVwDbDone() method that ends a session with ovwdb has the following signature:
public synchronized void OVwDbDone()

Session management APIs are available in the hp.ov.session class. The Java class files are available in the directory: /opt/OV/www/htdocs/classes/hp/ov/session on UNIX.

install_dir\www\htdocs\classes\hp\ov\session on Windows.

The jar file, ovsession.jar, is available in the directory: /opt/OV/www/htdocs/classes on UNIX.

install_dir\www\htdocs\classes on Windows.

Sample files that illustrate how to use the session functionality are available in the directory: /opt/OV/www/samples/sessionlib on UNIX. install_dir\www\samples\sessionlib on Windows.

Chapter 2

51

Using the HP OpenView Windows Java libovw API Error Handling

Error Handling
Retrieving a Methods Result Code
The LibOvw class throws LibOvwExceptions when errors occur. Each LibOvwException contains an integer error code representing the type of error that caused the exception to be thrown. You can request the error code by invoking the LibOvwException.getError()Java libovw API method. You can find the various error codes and their meanings in the Java documents: Go to /opt/OV/www/htdocs/C/java_libovw/index.html, then click hp.ov.libovw.LibOvwException API class (UNIX) Go to install_dir\www\htdocs\C\java_libovw\index.html, then click hp.ov.libovw.LibOvwException API class (Windows)

Converting a Result Code to a String

The Java libovw API also provides a method that converts a LibOvwException into its corresponding text string description. The LibOvwException.toString() method returns a string that describes the error. The following example shows one way to use the getError() and toString() methods:
import hp.ov.libovw.*; class Sample { int connect(String server, int ovwdbPort) { String sessionID = server; LibOvw libovw = new LibOvw(); try { libovw.OVwInitSession("My Application", sessionID); } catch (LibOvwException ex) { int error = ex.getError(); if (error == LibOvwException.OVW_NOT_RUNNING) { System.out.println("OVW is not running!");

52

Chapter 2

Using the HP OpenView Windows Java libovw API Error Handling

} else { System.out.println("Encountered error " + error + "in Sample.connect()"); System.out.println(ex.toString()); } } } }

Chapter 2

53

Using the HP OpenView Windows Java libovw API Implementing the ICallback Interface

Implementing the ICallback Interface

The first major step that every HP OpenView Windows application must perform is to register for events via the OVwAddCallback() or OVwAddActionCallback() methods, then implement the ICallback interface. The OVwEventAdapter class implements the ICallback interface. An application can extend the OVwEventAdapter class to eliminate the need to provide stubs for each callback method. See examples of code that can be used to extend the OVwEventAdapter class in Event Handling Examples on page 61. OVW applications receive notifications indicating that some condition has changed. Notifications are sent when events occur in response to end-user actions (such as adding a symbol to a map) or application actions (such as creating a submap or changing symbol status). The possible OVW event types are defined in the class hp.ov.libovw.OVwEvents. Applications do not receive all notifications automatically. Applications must specifically implement the ICallback interface and register for events in which they are interested. If an event occurs and the receiving object has not registered interest in that particular type of event, the notification is not sent to the application.

OVW Events
HP OpenView Windows defines approximately 50 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 class hp.ov.libovw.OVwEvents. This class provides the values and masks that identify the various libovw events. This class also contains the possible sources of an event. The following list contains a sample of OVW events: ovwEndSessionMask OVw terminated. ovwSelectListChangeMask The selection list changed.

54

Chapter 2

Using the HP OpenView Windows Java libovw API Implementing the ICallback Interface ovwMapOpenMask A map was opened. ovwMapCloseMask A map was closed. ovwQueryAddSymbolMask A user wants to add a symbol to a map. ovwConfirmAddSymbolMask Confirmation that a symbol was added to a map. Use the LibOvw.OVwAddCallback() Java libovw API method to register for events. OVwAddCallback() has the following method signature:
public int OVwAddCallback (long events, ICallback cb) throws LibOvwException

The arguments to OVwAddCallback() are as follows: events is the mask of the events of interest. All possible OVW event types are defined in the class hp.ov.libovw.OVwEvents. These may be logically ORed together to form the mask. cb is the name of the callback handler.

Register for events using the OVwAddCallback() Java libovw API method. Callback methods can, however, have different arguments, depending on the event type. OVW passes different types of information to the callback method 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 method exists for each event type. The method signatures for each of the callback methods are described in the Java doc files found in: /opt/OV/www/htdocs/C/java_libovw/doc (UNIX) install_dir\www\htdocs\C\java_libovw\doc (Windows)

Chapter 2

55

Using the HP OpenView Windows Java libovw API Implementing the ICallback Interface Example for Implementing the OVwAddCallback() Method When the OVwAddCallback() method is implemented, the application or applet can either implement the ICallback interface or extend the OVwEventAdapter class to avoid the implementation of the entire ICallback interface. The following example shows how an applet implementing the ICallback interface connects to OVW and registers for event notification through OVwAddCallback().
import java.applet.Applet; import hp.ov.libovw.*; // access libovw package classes

public class MyDemoApplet extends Applet implements ICallback { LibOvw libovw; public void init() { libovw = new LibOvw(); // OvwSessionId should be of the form <machine:instanceNumber> String ovwSessionId = getParameter("OvwSessionId"); try { libovw.OVwInitSession("MyDemoApplet", ovwSessionId); } catch (LibOvwException ex) { // handle connection exception, then finish return; } /*** Add to mask all event callbacks we plan on handling. We must implement each of the corresponding methods from ICallback. ***/ long eventMask = OVwEvents.ovwMapOpenMask| OVwEvents.ovwMapCloseMask| OVwEvents.ovwEndSessionMask; int ret; try { ret = libovw.OVwAddCallback(eventMask, this); } catch (LibOvwException ex) { // handle the exception libovw.OVwDone(); return; } }

56

Chapter 2

Using the HP OpenView Windows Java libovw API Implementing the ICallback Interface
public void OVwMapOpenCB(OVwMapInfo map, OVwFieldBindList configParams, int eventSource) { System.out.println("Map opened!"); } public void OVwMapCloseCB(OVwMapInfo map, int closeTime, int eventSource) { System.out.println("Map closed!"); libovw.OVwAckMapClose(map, 0); } public void OVwEndSessionCB(boolean normalEnd) { libovw.OVwDone(); } /*** The remaining OVw<something>CB methods would need to be implemented here. ***/ }

Action Events
OVW applications can also register to receive notifications when end users invoke application-provided actions from either OVW menu items or from executable symbols. These are special events we call action events. Use the OVwAddActionCallback() Java libovw API method to register for these action events. OVwAddActionCallback() has the following method signature:
public int OVwAddActionCallback(String actionID, ICallback cb) throws LibOvwException;

The argument list includes: actionID, which is an Action name from the application registration file for which a callback routine is associated. cb, which is the name of the callback handler.

The action event callback method has the method signature:

public void OVwAddActionCB (String actionId, String menuItemId, OVwObjectIdList selected, int argc, StringVectorParm argv, OVwMapInfo mapInfo, int submapId)

Chapter 2

57

Using the HP OpenView Windows Java libovw API Implementing the ICallback Interface The arguments to an action event callback handler are as follows: 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. A null value indicates that the application was invoked by an executable symbol. selected is a copy of the current OVW selection list. Selection lists are described in Selection Rules and the Selection List on page 70. argc and argv contain callback arguments as defined in the CallbackArgs statement in the ARF. mapInfo is an OVwMapInfo class that contains information about the open map. (This is discussed in detail in Getting Map Information on page 121.) submapID is the ID of the submap on which the event occurred. Submaps are described in detail in Chapter 4, Creating and Using Submaps.

The following example shows how to register for action events. Assume the following registration entry is present in the applications registration file and that the program has been placed in /opt/OV/www/htdocs/classes/myActionCB.jar: :
/* ** Application registration file for MyActionCB. */ Application "MyActionCB" { Description { "MyActionCB", "Application to test Java LibOvw API action callback mechanism" } DisplayString "MyActionCB"; Version "MyActionCB 1.0"; Copyright { "Copyright (c) 1990-2002 Hewlett-Packard Company", "All rights reserved" } MenuBar "Java API" { "MyActionCB" f.action "launchActionCB"; } MenuBar "Testing" {

58

Chapter 2

Using the HP OpenView Windows Java libovw API Implementing the ICallback Interface
"Test Menu Item 1" f.action "nopAction1"; "Test Menu Item 2" f.action "nopAction2"; } Action "launchActionCB" { Command "xnmappmon -cmd java -cp "/opt/OV/www/htdocs/classes/myActionCB.jar" MyActionCB $OVwSessionID"; } Action "nopAction1" { Command "/bin/true"; } Action "nopAction2" { Command "/bin/true"; } }

The following example registers an action callback for each of the two no-op actions listed in the previous registration file. The application will simply print out the actionID and menuItemID arguments passed to it in the action callback. A more sophisticated application might take different actions based on the values passed in.
import hp.ov.libovw.*; // access libovw package classes

public class MyActionCB extends OVwEventAdapter { public void OVwAddActionCB(String actionID, String menItemID, OVwObjectIdList selected, int argc, StringVectorParm argv, OVwMapInfo mapInfo, int submapId) { /* do something useful here ... */ System.out.println("MyActionCB.OVwAddActionCB(action="+actionID+", menu="+menItemID); } public static void main(String args[]) { // retrieve appropriate information, pass in to constructor String session = args[0]; int colon = session.indexOf(":"); if (colon > 0) { String colonStr = session.substring(colon); int dotAfterColon = colonStr.indexOf("."); if (dotAfterColon > 0) { session = session.substring(0,colon+dotAfterColon); } }

Chapter 2

59

Using the HP OpenView Windows Java libovw API Implementing the ICallback Interface
MyActionCB cb = new MyActionCB(session); cb.waitForDisconnect(); } LibOvw libovw = new LibOvw(); MyActionCB(String session) { try { libovw.OVwInitSession("MyActionCB", session); } catch (LibOvwException ex) { // handle the exception libovw = null; return; } try { libovw.OVwAddActionCallback("nopAction1", this); libovw.OVwAddActionCallback("nopAction2", this); } catch (LibOvwException ex) { // handle the exception int error = ex.getError(); System.out.println("exception encountered while registering action CB"); System.out.println("error = "+error); libovw = null; return; } System.out.println("MyActionCB: listening..."); } void waitForDisconnect() { // implement wait until done while (libovw != null) { try { Thread.sleep(1000); } catch (Exception e) { ; } } } }

Use the OVwRemoveActionCallback() Java libovw API method to remove the callback registration for these action events. OVwRemoveActionCallback() has the following method signature:
public int OVwRemoveActionCallback(String actionID) throws LibOvwException;

60

Chapter 2

Using the HP OpenView Windows Java libovw API Implementing the ICallback Interface

Event Handling Examples

The following examples illustrate two code segments that each implement the ICallback interface differently to receive notifications for two methods of interest, OVwQueryDescribeChange() and OVwConfirmDescribeChange(). For more information about the two methods (OVwQueryDescribeChange() and OVwConfirmDescribeChange()) used in this example, see Query-Verify-Confirm methods on page 203. The first example illustrates the implementation of notification through the direct implementation of the ICallback interface. TestApplet1 must implement the entire hp.ov.libovw.ICallback interface to receive notifications for the two methods of interest:
import java.applet.Applet; import hp.ov.libovw.*; public class TestApplet1 extends Applet implements ICallback { LibOvw libovw; public TestApplet1() { } public void init() { String session = getParameter("OvwSessionID"); libovw = new LibOvw(); try { libovw.OVwInitSession("TestApplet1", session); } catch (LibOvwException ex) { // handle the exception */ System.out.println ("exception is " + ex.getError() + " " + ex.toString()); libovw = null; return; } long mask = OVwEvents.ovwConfirmDescribeChangeMask | OVwEvents.ovwQueryDescribeChangeMask; int ret; try ( ret = libovw.OVwAddCallback(mask, this); } catch (LibOvwException ex){ // failure libovw.OVwDone();

Chapter 2

61

Using the HP OpenView Windows Java libovw API Implementing the ICallback Interface
libovw = null; System.out.println("OVwAddCallback failed!"); return; } } public void OVwQueryDescribeChangeCB(OVwMapInfo map, OVwObjectInfo object, OVwFieldBindList dialogBoxFields) { // Check the validity of the dialog box fields. // Some meaningful test should be performed here. boolean validOperation = true; if (validOperation) { try { libovw.OVwVerifyDescribeChange(map, object, dialogBoxFields, 1, null); } catch (LibOvwException ex) { // handle the exception return; } } else { try { libovw.OVwVerifyDescribeChange(map, object, dialogBoxFields, 0, "operation not valid"); } catch (LibOvwException ex) { // handle the exception return; } } } public void OVwConfirmDescribeChangeCB(OVwMapInfo map, OVwObjectInfo object, OVwFieldBindList dialogBoxFields){ // Operation completed successfully; // perform any application specific operations } // The remainder of the ICallback interface must be // implemented. We provide here empty definitions for

62

Chapter 2

Using the HP OpenView Windows Java libovw API Implementing the ICallback Interface
// all other ICallback methods. public void OVwEndSessionCB(boolean normalEnd) { } public void OVwMapOpenCB(OVwMapInfo map) { } public void OVwMapCloseCB(OVwMapInfo map, int closeTime, int eventSource){ } public void OVwConfirmDeleteSymbolsCB(OVwMapInfo map, OVwSymbolList symbolList) { } public void OVwConfirmDeleteSubmapsCB(OVwMapInfo map, OVwSubmapList submapList) { } public void OVwConfirmCreateSymbolsCB(OVwMapInfo map, OVwSymbolList symbolList) { } public void OVwConfirmCreateSubmapsCB(OVwMapInfo map, OVwSubmapList submapList) { } public void OVwSubmapChangeCB(OVwMapInfo map, OVwSubmapUpdateList submaps){ } public void OVwSymbolChangeCB(OVwMapInfo map, OVwSymbolUpdateList symbols){ } public void OVwConfirmMoveSymbolCB(OVwMapInfo map, OVwSymbolInfo symbol) { } public void OVwSelectListChangeCB(OVwMapInfo map){ } public void OVwQueryAppConfigChangeCB(OVwMapInfo map, OVwFieldBindList configParams){ } public void OVwConfirmAppConfigChangeCB(OVwMapInfo map, OVwFieldBindList configParams){ } public void OVwQueryAddSymbolCB(OVwMapInfo map, OVwSubmapInfo submap, OVwFieldBindList capabilityFields, OVwFieldBindList dialogBoxFields){ } public void OVwConfirmAddSymbolCB(OVwMapInfo map, OVwSymbolInfo symbol, OVwFieldBindList capabilityFields, OVwFieldBindList

Chapter 2

63

Using the HP OpenView Windows Java libovw API Implementing the ICallback Interface
dialogBoxFields){ } public void OVwQueryConnectSymbolsCB(OVwMapInfo map, OVwSubmapInfo submap, OVwObjectInfo object1, OVwObjectInfo object2, OVwFieldBindList capabilityFields, OVwFieldBindList dialogBoxFields){ } public void OVwConfirmConnectSymbolsCB(OVwMapInfo map, OVwSymbolInfo symbol, OVwObjectInfo object1, OVwObjectInfo object2, OVwFieldBindList capabilityFields,OVwFieldBindList dialogBoxFields){ } public void OVwConfirmDeleteSymbolAlertCB(OVwMapInfo map, OVwSymbolInfo symbol){ } public void OVwQueryDeleteSymbolsCB(OVwMapInfo map, OVwSymbolVerifyList symbolVerifyList){ } public void OVwConfirmDeleteObjectsCB(OVwMapInfo map, OVwObjectList objectList){ } public void OVwConfirmCreateObjectsCB(OVwMapInfo map, OVwObjectList objectList){ } public void OVwConfirmManageObjectsCB(OVwMapInfo map, OVwObjectList objectList){ } public void OVwConfirmUnmanageObjectsCB(OVwMapInfo map, OVwObjectList objectList){ } public void OVwConfirmHideSymbolsCB(OVwMapInfo map, OVwSymbolList symbolList) { } public void OVwConfirmUnhideSymbolsCB(OVwMapInfo map, OVwSymbolList symbolList){ } public void OVwConfirmSymbolStatusChangeCB(OVwMapInfo map, OVwSymbolList symbolList){ } public void OVwConfirmObjectStatusChangeCB(OVwMapInfo map,OVwObjectList objectList){ } public void OVwConfirmCompoundStatusChangeCB(OVwMapInfo map, OVwObjectList objectList){

64

Chapter 2

Using the HP OpenView Windows Java libovw API Implementing the ICallback Interface
} public void OVwConfirmCapabilityChangeCB(OVwMapInfo map,OVwObjectList objectList){ } public void OVwUserSubmapCreateCB(OVwMapInfo map, OVwSymbolInfo symbol, OVwSubmapInfo submap){ } public void OVwSubmapOpenCB(OVwMapInfo map, OVwSubmapInfo submap){ } public void OVwSubmapCloseCB(OVwMapInfo map, OVwSubmapInfo submap){ } public void OVwAttributeLocateCB(OVwMapInfo map, int requestId, OVwObjectIdList objects){ } public void OVwSymbolStatusLocateCB(OVwMapInfo map, int requestId, int searchVal){ } public void OVwSymbolTypeLocateCB(OVwMapInfo map, int requestId, String searchVal){ } public void OVwSymbolLabelLocateCB(OVwMapInfo map, int requestId, String searchVal){ } public void OVwBusyCancelCB (OVwMapInfo map){ } }

The second example illustrates the use of the OVwEventAdapter to avoid the implementation of the entire ICallback interface. The only definitions to be provided are for the two notification methods of interest. However, since OvwHandler extends OVwEventAdapter, it must be defined in a class distinct from our derivation of Applet. OvwHandler could be implemented as an inner class within TestApplet2:
import java.applet.Applet; import hp.ov.libovw.*; // OvwHandler implements only two of the notification methods // (those dealing with the Describe dialog box) defined by // hp.ov.libovw.ICallback. class OvwHandler extends OVwEventAdapter {

Chapter 2

65

Using the HP OpenView Windows Java libovw API Implementing the ICallback Interface
public OvwHandler(LibOvw libovw) { long mask = OVwEvents.ovwConfirmDescribeChangeMask | OVwEvents.ovwQueryDescribeChangeMask; int ret; try { ret = libovw.OVwAddCallback(mask, this); } catch (LibOvwException ex){ // failure libovw.OVwDone(); libovw = null; System.out.println("OVwAddCallback failed!"); return; } } public void OVwQueryDescribeChangeCB(OVwMapInfo map, OVwObjectInfo object, OVwFieldBindList dialogBoxFields) { // Check the validity of the dialog box fields. // Some meaningful test should be performed here. boolean validOperation = true; if (validOperation) { try { libovw.OVwVerifyDescribeChange(map, object, dialogBoxFields, 1, null); } catch (LibOvwException ex) { // handle the exception return; } } else { try { libovw.OVwVerifyDescribeChange(map, object, dialogBoxFields, 0, "operation not valid"); } catch (LibOvwException ex) { // handle the exception return;

66

Chapter 2

Using the HP OpenView Windows Java libovw API Implementing the ICallback Interface
} } } public void OVwConfirmDescribeChangeCB(OVwMapInfo map, OVwObjectInfo object, OVwFieldBindList dialogBoxFields) { // Operation completed successfully; // perform any application specific operations } } public class TestApplet2 extends java.applet.Applet { LibOvw libovw; OvwHandler handler; public TestApplet2() { } public void init() { String session = getParameter("OvwSessionID"); libovw = new LibOvw(); try { libovw.OVwInitSession("OvwHandler", session); } catch (LibOvwException ex) { // handle the exception System.out.println ("exception is " + ex.getError() + " " + ex.toString()); return; } handler = new OvwHandler(libovw); } }

Chapter 2

67

Using the HP OpenView Windows Java libovw API Getting your Application Name

Getting your Application Name

As described in the online manual, Creating and Using Registration Files, an Application Block within an application registration file defines your application name. A number of Java libovw API invocations require an application name as an input argument. You could, of course, hard-code those Java libovw API invocations 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 method in the Java libovw API that programmatically retrieves your application name from the ARF. The method OVwGetAppName() returns your application name as defined in the ARF. The following code segment demonstrates:
String myname = libovw.OVwGetAppName(); System.out.println("My name is: " + myname); ...

OVwGetAppName() returns the name of the running application.

68

Chapter 2

Using the HP OpenView Windows Java libovw API Getting the Object Selection List

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 callback methods 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 Java libovw API provides a method that has the method signature:
public OVwObjectIdList OVwGetSelections(OVwMapInfo map, String actionId) throws LibOvwException

It returns the current contents of the selection list. The OVwGetSelections() method returns a list of objects currently selected in OVW. The following example shows how to use the OVwGetSelections() method to traverse the list of objects whose IDs are represented in the selection list. This example uses the OVwGetMapInfo() method to get the map information. OVwGetMapInfo() is described in Getting Map Information on page 121.
import hp.ov.libovw.LibOvw; public class MyMapInfo { public static void main(String args[]) { MyMapInfo mmi = new MyMapInfo(args[0]); } public MyMapInfo(String session) { LibOvw libovw = new LibOvw(); // do OvwInitSession ... OVwMapInfo map; try { map = libovw.OVwGetMapInfo(); } catch (LibOvwException ex) { // handle the exception

Chapter 2

69

Using the HP OpenView Windows Java libovw API Getting the Object Selection List
return; } try { OVwObjectIdList op = libovw.OVwGetSelections(map, null); System.out.println("There are " + op.count + " objects in the selection list."); } catch (LibOvwException ex) // handle the exception return; } for (int i=0; i<op.count; i++) { System.out.println("Object id[" + i + "] is " + op.object_ids[i]); } } }

Objects and object IDs are described in detail later in this manual.

Selection Rules and the Selection List

As described in the online manual, Creating and Using Registration Files, 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 is 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() method. For example, consider the following ARF:
Application "My app" { ... Action Trends { SelectionRule isNode && isDevice; ... } ... }

70

Chapter 2

Using the HP OpenView Windows Java libovw API Getting the Object Selection List To use the above selection rule in your program, you pass the Trends argument to your LibOvw.OVwGetSelections() method. LibOvw.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 ovwSelectListChange event whenever the selection list changes. You can implement the ICallback interface to determine the current selection list using LibOvw.OVwGetSelections(). Selection list changes can occur frequently in OVW, so you should register for the ovwSelectListChange 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 methods are:
public int OVwSelectObject(OVwMapInfo map, int objectId, int clearPrevious) throws LibOvwException

and
public int OVwSelectObjects(OVwMapInfo map, OVwObjectIdList objectList, int clearPrevious) throws LibOvwException

The object ID or list of object IDs is passed as an argument. Object ID lists are described in Chapter 3, Creating and Using Objects and Fields. The map parameter may be null, in which case these methods refer to the open map. The clearPrevious flag (described in the hp.ov.libovw.LibOvw class) controls whether previously selected objects are cleared. If 0, previously selected objects remain selected. If 1, 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 invocations, then it should use the clearPrevious flag only for the first invocation.

Chapter 2

71

Using the HP OpenView Windows Java libovw API Getting the Object Selection List 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 implement a method on the ICallback interface to be invoked when the selection changes. This method would invoke OVwGetSelections() to determine whether an illegal selection was being made. If so, the illegal object IDs would be removed from the list and the method would invoke OVwSelectObjects(map,objectList,1).

72

Chapter 2

Using the HP OpenView Windows Java libovw API Highlighting Objects

Highlighting Objects
Applications can highlight one or more objects on a map as a result of a user-initiated action (for example, 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 methods have the following method signatures:
public int OVwHighlightObject(OVwMapInfo map, int objectId, int clearPrevious) throws LibOvwException public int OVwHighlightObjects(OVwMapInfo map, OVwObjectIdList objectList, int clearPrevious) throws LibOvwException

The object ID (or list of object IDs) is passed as an argument. Object ID lists are described in Chapter 3, Creating and Using Objects and Fields. The map parameter may be null, in which case these methods refer to the open map. The clearPrevious flag (described in the hp.ov.libovw.LibOvw class) controls whether previously highlighted objects are cleared. If 0, previously highlighted objects remain highlighted. If 1, 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 invocations, then it should use the clearPrevious flag only for the first invocation.

Chapter 2

73

Using the HP OpenView Windows Java libovw API Summary

Summary
This chapter described the basic Java libovw API methods that are important to most OVW applications. Most typical applications must perform three steps: 1) connect to HP OpenView Windows, 2) register for events via OVwAddCallback() or OVwAddActionCallback(), 3) implement the ICallback interface to invoke methods when specific events occur. Applications connect to HP OpenView Windows by invoking the OVwInitSession() method, then register for events via the OVwAddCallback() or other callback method. Applications then implement methods of the ICallback interface to be invoked when specific events occur. Other general purpose methods were then described. These methods perform such functions as: checking for Java libovw API errors, getting the application name, getting the object selection list, and highlighting objects.

74

Chapter 2

Creating and Using Objects and Fields

Chapter 3

75

Creating and Using Objects and Fields Overview

Overview
This chapter introduces the Java libovw API object database methods. These methods create and manipulate objects and fields in the HP OpenView Windows object database. Read this chapter if you want to create and/or manipulate objects in the HP OpenView Windows object database. This chapter discusses: the HP OpenView Windows object database creating fields creating objects getting/setting object field values deleting objects

76

Chapter 3

Creating and Using Objects and Fields The HP OpenView Windows Object Database

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 Java libovw API object database methods. These Java libovw object database methods 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. Access the OVW object database using either the OVwInitSession() method or the OVwDbInit() method to connect only to the object database. In terms of naming conventions, the Java libovw API object database methods all begin with the prefix OVwDb and reside in the hp.ov.libovw class.

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 value character string enumerated value

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.

Chapter 3

77

Creating and Using Objects and Fields The HP OpenView Windows Object Database The Java libovw API provides a number of methods to create and manipulate fields. Other Java libovw API methods 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 Java libovw API provides methods to create and delete objects, as well as methods that change the object fields. Other Java libovw API methods 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 Methods and their Variants

The Java libovw API provides almost 50 methods for interaction with the HP OpenView Windows object database. The API is not as complex as it might first appear, though. A few basic classes and general purpose methods invocations suffice for most applications. Many of the general purpose methods also have specialized variations that are more convenient in certain situations. Once the general purpose methods are understood, the specialized method signatures follow easily. This chapter presents all of the general purpose object database methods, as well as some of the specialized variations. The complete set of method signatures and class definitions for all field and object database methods are described in the OVW API reference pages located in: /opt/OV/www/htdocs/C/java_libovw/doc (UNIX)

install_dir\www\htdocs\C\java_libovw\doc (Windows)

78

Chapter 3

Creating and Using Objects and Fields Creating Fields

Creating Fields
Fields are created using either the field registration file (FRF) or the OVwDbCreateField() method. Field values are set using other API methods 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() method 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 Java libovw API, their existence can only be determined programmatically.

Creating Fields Programmatically

Fields are created using the OVwDbCreateField() method. This method creates an entry in the OVW database that describes how data is stored and treated. This method 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.

Chapter 3

79

Creating and Using Objects and Fields Creating Fields OVwDbCreateField() has the following method signature:
public int OVwDbCreateField(String fieldName, int fieldType, int flags) throws LibOvwException

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 of the new field. Valid types are ovwIntField, ovwBooleanField, ovwStringField, and ovwEnumField. If the data type is a list, then the fieldType argument has the ovwListField value set. Valid types are defined in hp.ov.libovw.OVwFieldValue class. flags is a bitmap representing the flags to be set for the new field. Valid flags are ovwAllFields, ovwListField, ovwNameField, ovwCapabilityField, ovwLocateField, and ovwGeneralField. (Valid combinations of field flags are described in the online manual, Using Registration Files, in the Welcome collection in the field registration file section.) Valid flags are defined in hp.ov.libovw.Libovw.

The OVwDbCreateField() method returns an integer identifier that is used in subsequent Java libovw API invocations involving the field. At this point, the field exists in the database, and values can be set for the field for particular objects.

Converting between Field Names and Field IDs

Most Java libovw API methods 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 methods in the Java libovw API. Two Java libovw API methods are available to convert between field names and field IDs. They have the method signatures:
public int OVwDbFieldNameToFieldId(String fieldName) throws LibOvwException public String OVwDbFieldIdToFieldName(int fieldId) throws LibOvwException

80

Chapter 3

Creating and Using Objects and Fields Creating Fields Applications that create fields using the field registration file need to use the OVwDbFieldNameToFieldId() method at some time. As mentioned before, many of the OVW object database methods take a field ID, not a field name, as an argument. To use these types of methods, you need to first convert the field name in the field registration file to a field ID using OVwDbFieldNameToFieldId(). See the OVW API reference pages describing these methods if you need more information.

Using Enumeration Values

The Java libovw API supports enumerated types. The OVwEnumConstants class contains a list of enumerated values. Invoke the OVwDbSetEnumConstants() method to set the values for an enumerated data type.

Retrieving Field Information

The Java libovw API provides methods that return information about a field. These methods 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 class to retrieve information about a field. The class contains the field name, type, and flags, as well as the field ID. Getting Field Information for a Single Field The OVwDbGetFieldInfo() method returns field information for a single field. When invoked with a field ID, it returns an OVwFieldInfo class containing field information. Getting Field Information for All Fields The OVwDbListFields() method 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, ovwListField, ovwNameField, ovwLocateField, ovwCapabilityField, and ovwGeneralField. These fields are defined in the hp.ov.libovw.LibOvw class.

Chapter 3

81

Creating and Using Objects and Fields Creating Fields Getting Enumeration Type Values After you have defined an enumeration, you can use a number of Java libovw API methods to retrieve information about the enumeration. You can retrieve the symbolic name list (OVwDbGetEnumConstants()) as well as translate between symbol names and values (OVwDbGetEnumValue() and OVwDbGetEnumName()). See the OVW API reference pages for more information on these and other related methods that operate on enumerated data types.

Predefined Fields
Name fields are predefined by OVW and are available for application use. Refer to the online manual Creating and Using Registration Files for more information on the Namefield statement. Applications should not attempt to redefine or change these predefined OVW fields. The field creation methods 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.

82

Chapter 3

Creating and Using Objects and Fields 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.

The Selection Name

A selection name is a special name field that is set for all objects. Before 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
Three Java libovw API methods are available to create objects: A generic method that can create any type of Java libovw object (OVwDbCreateObject()).

Chapter 3

83

Creating and Using Objects and Fields Creating Objects Two convenience methods that create objects by their hostname or selection name (OVwDbCreateObjectByHostname() and OVwDbCreateObjectBySelectionName()).

In general, objects are created with the OVwDbCreateObject() method. It has the following method signature:
public int OVwDbCreateObject(OVwFieldBinding name) throws LibOvwException

The name argument is the field binding information used to create the object and is derived from the OVwFieldBinding class. The OVwFieldBinding class links a field ID with a field value. If you invoke OVwDbCreateObject() with a null parameter, OVW creates an object for you and assign it a system-generated selection name. If you supply a name argument in the OVwDbCreateObject() invocation, one of three things can happen: If the field value you supply is a selection name, then OVW attempts to define the object. If the selection name is already allocated, the invocation returns an error. If the field value is a name field other than the selection name, OVW attempts to define the object. If the name field value is not unique, an error is returned. If the name is unique, OVW defines the object, sets the name field value, and generates 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 creates a selection name for you. The name is 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 also generates a selection name for the object.
... LibOvw libovw = new LibOvw(); // do OvwInitSession ... int f_id; int obj_id;

84

Chapter 3

Creating and Using Objects and Fields Creating Objects

// get the field ID associated with the NetBIOS Name try { f_id = libovw.OVwDbFieldNameToFieldId("NetBIOS Name"); } catch (LibOvwException ex) { int error = ex.getError(); if (error == LibOvwException.OBJECT_NULL_NAME) { System.out.println(ex.toString()); } } OVwFieldBinding bp = new OVwFieldBinding(); bp.field_val = new OVwFieldValue(); // fill in the field_id entry and the field_value structure bp.field_id = f_id; bp.field_val.string_val = "nametest"; bp.field_val.field_type = OVwFieldValue.ovwStringField; bp.field_val.is_list = 0; // create the object and save the object ID that is returned try { obj_id = libovw.OVwDbCreateObject(bp); } catch (LibOvwException ex) { // catch exception as shown above return; } ...

Generating Unique Names

The OVwDbCreateObject() method 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 invocation again, but there is no guarantee that your new name is unique. The Java libovw API solves this problem by providing a method that generates a unique name for you, using a name you supply as a base. The invocation has the following method signature:
public String OVwDbGetUniqObjectName(int nameFieldId, String baseName) throws LibOvwException

Chapter 3

85

Creating and Using Objects and Fields Creating Objects The function behaves differently depending upon the baseName parameter that is supplied in the parameter list: 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 chooses a unique name based on the value you provide. OVW appends an integer to the base name such that the newly formed name is unique. If you pass a null parameter for the baseName parameter, OVW chooses a unique name field value for you. OVW converts the field ID to a base field name, and appends an integer to the base field name such that the new name is unique.

The name generated by the invocation is guaranteed to be unique, which lets you invoke OVwDbCreateField() with assurance that your name is not already allocated.

Creating Objects by Hostname or Selection Name

You can use the general purpose OVwDbCreateObject() method to create an object that has a hostname or selection name. The following steps are involved: 1. Invoke the OVwDbFieldNameToFieldId() method 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. Fill in the OVwFieldValue class, setting the ovwStringField entry to the name and setting the ovwIntField to the field ID. 3. Invoke OVwDbCreateObject(). As a convenience, the Java libovw API provides two methods that create objects by IP Hostname or Selection Name. They require only a single invocation, and they have the following method signatures:
public int OVwDbCreateObjectByHostname(String hostname)throws LibOvwException public int OVwDbCreateObjectBySelectionName(String selectionName)throws LibOvwException

These methods are a convenient alternative to using the generic OVwDbCreateObject() method. 86 Chapter 3

Creating and Using Objects and Fields Getting/Setting Object Field Values

Getting/Setting Object Field Values

After creating fields and objects, you can use the remaining Java libovw object database methods to manipulate the fields in a wide variety of ways. The Java libovw API object database methods 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 Invocations

Using the basic methods presented in this section, you can access all field and object information in the OVW object database. Many convenience versions of these basic invocations 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 invocations you need to make to get field information. The convenience versions do not, however, perform actions that could not be performed using the basic invocations. The most basic way to retrieve field value information is with the OVwDbGetFieldValue() method. Given a field ID and object ID, this method returns the field information. The OVwDbGetFieldValue() method has the following method signature
public OVwFieldValue OVwDbGetFieldValue(int objectId, int fieldId) throws LibOvwException

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 invokes OVwDbGetFieldValue() to retrieve the field value information.

Chapter 3

87

Creating and Using Objects and Fields Getting/Setting Object Field Values
... LibOvw libovw = new LibOvw(); int field_id; int obj_id; OVwFieldValue idinfo;... try { field_id = libovw.OVwDbFieldNameToFieldId("Selection Name"); } catch (LibOvwException ex) { //handle the exception return null; } // Get the field value. Assume that obj_id is set for the object. try { idinfo = libovw.OVwDbGetFieldValue(obj_id, field_id); System.out.println("The Selection Name for this object is + idinfo.string_val); } catch (LibOvwException ex) { // handle the exception return; } ...

Setting Field Values The OVwDbSetFieldValue() method is used to set field values as well as to add fields to existing objects. It has the following method signature:
public int OVwDbSetFieldValue(int objectId, int fieldId, OVwFieldValue fieldValue) throws LibOvwException

If you attempt to set a field value for a field that is not already associated with the object, OVW adds the field to the object for you. The OVwDbCreateObject() method is used to set a single field value and to create an object. The OVwDbSetFieldValue() method 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 operations, the Java libovw API provides convenience methods that simplify these tasks. Some Java libovw API convenience methods retrieve particular field values directly, bypassing the overhead of using the OVwFieldValue class upon return. Examples include 88 Chapter 3

Creating and Using Objects and Fields Getting/Setting Object Field Values OVwDbGetFieldIntegerValue() and OVwDbGetFieldBooleanValue(). To use these methods, you must know the data type of the field you are interested in. Other convenience methods eliminate the need to set up an OVwFieldValue class. The desired value is simply passed as an argument to the appropriate method. Examples of these types of methods include OVwDbSetFieldStringValue() and OVwDbSetSelectionName(). The convenience methods are straightforward and easy to use. See the reference pages that describe the methods for more information.

Getting All Fields Associated with an Object

The Java libovw API also provides methods that can return a list containing multiple fields, each of which may have different types. The OVwDbGetFieldValues() method, 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 class, OVwFieldBindList. This class contains object field binding list information. The following example shows how the OVwFieldBindList class is used. For convenience, we assume each field is a simple type, not a list of simple types.
... LibOvw libovw = new LibOvw(); OVwFieldBindList fbl; OVwFieldBinding fb; int obj_id; int i;... // assume that obj_id is the object ID for the object try { fbl = libovw.OVwDbGetFieldValues(obj_id); } catch (LibOvwException ex) { // handle the exception return; } for (i=0; i<fbl.count; i++){

Chapter 3

89

Creating and Using Objects and Fields Getting/Setting Object Field Values
fb=fbl.fields[i]; System.out.println("Processing field binding entry " + i); System.out.println("The field ID is " + fb.field_id); switch (fb.field_val.field_type) { case OVwFieldValue.ovwStringField: System.out.println("String value is " + field_val.string_val); break; case OVwFieldValue.ovwIntField: System.out.println("Integer value is " + fb.field_val.int_val); break; case OVwFieldValue.ovwBooleanField: System.out.println("Boolean value is " + fb.field_val.bool_val); break; case OVwFieldValue.ovwEnumField: System.out.println("Enum value is " + fb.field_val.enum_val); break; } } ...

Convenience Methods
The Java libovw API provides many convenience methods that, in some situations, are easier to use than the basic calls. These convenience methods depend on classes and concepts presented in this chapter. The following table lists some of the Java libovw API object database convenience methods. Table 3-1 Convenience Methods Method OVwDbGetFieldIntegerValue() OVwDbGetFieldBooleanValue() OVwDbGetFieldStringValue() OVwDbGetFieldEnumByValue() OVwDbGetFieldEnumByName() Purpose These methods take an object ID and field ID as arguments and return the appropriate field value. They save you the trouble of having to access the OVwFieldValue class.

90

Chapter 3

Creating and Using Objects and Fields Getting/Setting Object Field Values Table 3-1 Convenience Methods (Continued) Method OVwDbSetFieldIntegerValue() OVwDbSetFieldBooleanValue() OVwDbSetFieldStringValue() OVwDbSetFieldEnumByValue() OVwDbSetFieldEnumByName() OVwDbSetSelectionName() OVwDbSetHostname() OVwDbGetCapabilityFieldValues() OVwDbGetNameFieldValues() OVwDbNameToObjectId() OVwDbSelectionNameToObjectId() OVwDbObjectIdToSelectionName() OVwDbHostnameToObjectId() OVwDbObjectIdToHostname() OVwDbListObjectsByFieldValue() OVwDbListObjectsByFieldValues() The list or locate calls search the entire OVW object database for objects/fields that match certain criteria. They are slow, since the entire database is searched. This method gets a list of values for a certain field for a list of objects. These methods take an object ID and a string and then set the appropriate name field. These methods return a list of name or capability fields set for the object. This method converts the value of any name field to the object ID it identifies. These methods translate between selection name/object ID and hostname/object ID. Purpose These methods 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 class yourself if you use these methods.

OVwDbGetFieldValuesByObjects()

These convenience methods are not described in detail here since their use is straightforward once the basic calls are understood. See the OVW API reference pages for more information on these methods.

Chapter 3

91

Creating and Using Objects and Fields 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 Java libovw API provides a set of methods 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 Call OVwDbDeleteObject() to delete the object. The OVwDbDeleteObject() method has the method signature:
public int OVwDbDeleteObject(int objectId) throws LibOvwException

OVW deletes the object if either no fields are set for the object the object only has fields with either the capability or general flag set

If either of these conditions are true, OVW deletes the object. If any application has fields set for the object, the object is not deleted until that application unsets its field values and calls OVwDbDeleteObject(). See the OVwDbDeleteObject(3) reference page for the C function for 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 determine that an object is no longer in use by registering for the ovwConfirmDeleteObjects event. Chapter 6, Map Editing and Map Events, describes map editing and map events in detail. The OVwConfirmDeleteObjectsCB(3) reference page also describes when to delete objects.

92

Chapter 3

Creating and Using Objects and Fields Summary

Summary
This chapter described how to use the OVw object database methods 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() Java libovw API method. Objects are created with the OVwDbCreateObject() method 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() method generates values for name fields that are guaranteed to be unique. The Java libovw API classes used for object manipulation were presented. The libovw.OVwFieldValue class contains field value information. Lists within a field value must contain objects of the same type. The libovw.OVwFieldBindList class is used to create lists of field values. A variety of Java libovw API convenience methods 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 classes you must use. Applications delete objects through a two-step process. Applications first unset each field that they control, then applications call an Java libovw API method 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.

Chapter 3

93

Creating and Using Objects and Fields Summary

94

Chapter 3

Creating and Using Submaps

Chapter 4

95

Creating and Using Submaps Overview

Overview
This chapter describes 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. This chapter discusses: 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

96

Chapter 4

Creating and Using Submaps Map and Submap Concepts

Map and Submap Concepts

This section briefly describes the relationship between maps and submaps.

Maps
A map is a collection of OVW objects and their relationships. Users do not view maps directly; instead, 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.

Chapter 4

97

Creating and Using Submaps Map and Submap Concepts

Submaps
A submap is a collection of related symbols that are displayed in a single 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 causes 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.

98

Chapter 4

Creating and Using Submaps Map and Submap Concepts 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 of its parent. End users can add and remove context identifiers for a submap through the Submap Properties dialog box. 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.

Chapter 4

99

Creating and Using Submaps Map and Submap Concepts 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 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 5, 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.

100

Chapter 4

Creating and Using Submaps Map and Submap Concepts

Relationship Between Maps and Submaps

The following diagram illustrates the relationship between maps, submaps, and symbols. Figure 4-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

Chapter 4

101

Creating and Using Submaps Map and Submap Concepts In Figure 4-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 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 4-1 Algorithm No Layout Layout Algorithms for Submaps Purpose 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 (for example, when using background graphics). 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. Use for network connections on a bus segment or for showing multiple objects that tie into a common relationship. Use for network connections on a star segment or for showing multiple objects connected into a common master or hub object. Use for network connections on a ring segment or for showing multiple objects with equal connectivity between all objects. 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. Use for submaps that primarily contain a set of connections between two objects (for example, the logical channels of a physical link).

Point to Point

Bus Star Ring Row/Column

Multiple Connections

102

Chapter 4

Creating and Using Submaps Map and Submap Concepts 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 5, Creating and Using Symbols.

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 is managed by the application. Applications should not normally add, modify, or delete symbols on the user plane, although the Java libovw API permits this. Chapter 6, Map Editing and Map Events, explains how applications can determine when symbols or connections are added to submaps. Refer to this chapter if your application needs to determine when icon or connection symbols are added to submaps.

Chapter 4

103

Creating and Using Submaps Map and Submap Concepts

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. 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. Refer to 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 Windows systems, 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.

104

Chapter 4

Creating and Using Submaps Map and Submap Concepts 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 are 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 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 OVwEvents.ovwUserSubmapCreate event sent from ICallback.OVwUserSubmapCreateCB() and the LibOvw.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 LibOvw.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 209.

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

Chapter 4

105

Creating and Using Submaps Map and Submap Concepts 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 118 and Setting Submap Geometry on page 119 for a description of the relevant APIs.

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 While running OVW, 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 toolbar, 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.

106

Chapter 4

Creating and Using Submaps Map and Submap Concepts 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.

NOTE

When the geometry for a transient submap is saved, the submap becomes persistent.

NOTE

The maximize state of the window is not a part of submap geometry and is not saved.

Chapter 4

107

Creating and Using Submaps 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 LibOvw.OVwCreateSubmap() Java libovw API method. OVwCreateSubmap() creates a submap on the open map. It has the method signature
public int OVwCreateSubmap(OVwMapInfo map, int parentObject, int submapPolicy, int submapType, String submapTitle, int layout, int flags) throws LibOvwException

When calling OVwCreateSubmap(), you need to supply the following arguments: map is the currently open map of class LibOvw.OVwMapInfo. The OVwMapInfo class contains information about the map. Applications can retrieve map information in the OVwMapInfo class in two ways. Applications can call the OVwGetMapInfo() method, or applications can save the map information that accompanies a map open event. Later sections describe how to handle map open events and how to manipulate fields in the OVwMapInfo class. To create submaps, though, you can simply pass in the class returned by the OVwGetMapInfo() method or supplied with the map open event. An example shows how to use the OVwGetMapInfo() method when creating submaps. parentObject is the object ID of the parent object that this submap represents. You can also specify ovwNullObjectId, which means that this submap does not have a parent object. This is known as an orphaned submap.

108

Chapter 4

Creating and Using Submaps Creating Submaps submapPolicy indicates whether this submap is shared by other applications or if it is owned exclusively by this application. The possible values are ovwSharedSubmap and ovwExclusiveSubmap. Shared and exclusive submaps were described earlier in this chapter. The defined values are described in the class hp.ov.libovw.OVwSubmapInfo. submapType is an application-defined field that applications can use to classify submaps. Applications may use this field however they wish. 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. The defined layouts are described in the hp.ov.libovw.OVwSubmapInfo class. flags may include flags such as layout_on to set automatic layout or ovwTransientSubmap to mark the submap as being transient.When using multiple flags, the flags are logically ORed together. The defined flags are described in hp.ov.libovw.OVwSubmapInfo class.

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.)
... LibOvw libovw = new LibOvw(); int obj_id; OVwMapInfo map; int sub_id; // do OvwInitSession ...

Chapter 4

109

Creating and Using Submaps Creating Submaps

// assume obj_id is set to the ID of the parent object try { map = libovw.OVwGetMapInfo(); } catch (LibOvwException ex) { //handle the exception return; } try { sub_id = libovw.OVwCreateSubmap(map, obj_id, OvwSubmapInfo.ovwSharedSubmap, 0, "Administer: System Mgmt", OvwSubmapInfo.ovwBusLayout, OvwSubmapInfo.ovwNoSubmapFlags); } catch (LibOvwException ex) { //handle the exception return null; } ...

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 method LibOvw.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 Java libovw API method OVwCreateSubmap(). When the exclusive submap flag is set, no other applications may change the submaps context. When the exclusive

110

Chapter 4

Creating and Using Submaps Creating Submaps 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 Java libovw API methods OVwAddSubmapContext() and OVwRemoveSubmapContext(). Context can also be set via the OvwModifySubmaps() method.

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 notifies the user of this and prompts for additional information needed to create the child submap. OVW then displays the submap. The application does not need to issue an invocation to the Java libovw 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() Java libovw API method. The OVwDisplaySubmap() method has the signature:
public int OVwDisplaySubmap(OVwMapInfo map, int submapId) throws LibOvwException

Given a submap ID, this method 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. 111

Chapter 4

Creating and Using Submaps Creating Submaps

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 (for example, 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. Submap information is present in the event that a user saves a map snapshot.

Conversely, applications that create 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. Chapter 4

112

Creating and Using Submaps Creating Submaps 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 Java libovw API to close the submap: The user double-clicks the window menu button. The user selects Map:Close Submap. The user clicks on the close icon in the toolbar.

However, when an application does need to close a submap, use the OVwCloseSubmap() Java libovw API method which has the signature:
public int OVwCloseSubmap(OVwMapInfo map, int submapId) throws LibOvwException

Given a submap ID, this method 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 4

113

Creating and Using Submaps Loading and Unloading Submaps

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. However, the submap is not closed until the user closes it. When the user closes the submap that was loaded/opened by the application, the reference count is not decremented until the application invokes the unload submap method.

The OVwLoadSubmap() method 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 invoking application can use this submap ID for adding its own information to the submap and for unloading the submap from memory. The method signature for OVwLoadSubmap() is:
public int OVwLoadSubmap(OVwMapInfo map, int parentId, int display, int layout) throws LibOvwException

where: map provides information about a currently open map.

114

Chapter 4

Creating and Using Submaps Loading and Unloading Submaps parentID specifies the parent symbol id of the loaded submap. display specifies whether the newly loaded submap should be displayed. layout specifies whether to perform a layout of the newly loaded submap.

The OVwLoadSubmaps() method loads multiple submaps with a single invocation. The returned submap list provides the submap IDs of the loaded submaps. The method signature is:
public OVwSubmapLoadAckList OVwLoadSubmaps(OVwMapInfo map, OVwSymbolIdList symbolList, int display, int layout) throws LibOvwException

The parameters display and layout apply to all of the loaded submaps. The return value is a list of submap loading acknowledgments. The OVwSubmapLoadAckList class contains a list of submap loading acknowledgments that include two variables: count is the number of items in the list. submaps is a list of items of the type OVwSubmapLoadAckInfo.

The OVwSubmapLoadAckInfo class includes three variables: symbol is the symbol ID. submap is the submap ID. acknowledgment is the acknowledgment indicating the success or failure of the specified submap load

OVwUnloadSubmap() unloads the specified submap and decrements the reference count.
public int OVwUnloadSubmap (OVwMapInfo map, int submap) throws LibOvwException

The OVwUnloadSubmaps() method unloads multiple submaps with a single invocation.

public OVwSubmapLoadAckList OVwUnloadSubmaps (OVwMapInfo map, OVwSubmapIdList submapList) throws LibOvwException

The OVwSubmapLoadAckList class contains a list of submap loading acknowledgments. This class contains both a count of the number of items in the list as well as the list of submaps of the class OVwSubmapLoadAckInfo. The OVwSubmapLoadAckInfo class includes the Chapter 4 115

Creating and Using Submaps Loading and Unloading Submaps acknowledgment variable that indicates the success or failure of the submap unloads. The symbol variable in the class OVwSubmapLoadAckInfo is not valid when unloading submaps.

116

Chapter 4

Creating and Using Submaps Changing Submap Characteristics

Changing Submap Characteristics

When you create a submap using the LibOvw.OVwCreateSubmap() method, 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 methods 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 method signatures:
public int OVwModifySubmap(OVwMapInfo map, OVwSubmapUpdateInfo submap) throws LibOvwException public int OVwModifySubmaps(OVwMapInfo map, OVwSubmapUpdateList submaps) throws LibOvwException

When invoking OVwModifySubmaps() and OVwModifySubmap(), you need to supply these arguments: map contains complete map information. You can use the OVwGetMapInfo() method to get the map information.

Chapter 4

117

Creating and Using Submaps Changing Submap Characteristics The OVwSubmapUpdateInfo class contains the changes to the submap information. OVwSubmapUpdateList contains a list of OVwSubmapUpdateInfo items, describing changes to the submap information.

Many of the characteristics defined for the submap class (refer to Getting Submap Information on page 123) can be changed using the OVwModifySubmaps() and OVwModifySubmap() methods. 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() Java libovw method. The method has the signature:
public int OVwSetSubmapName(OVwMapInfo map, int submapId, String name) throws LibOvwException

The arguments are straightforward. You only need to supply the map, 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 create a new window on the display. By default a submap can be overlaid. Refer to Submap Presentation on page 105 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 class is:

submap_overlay

118

Chapter 4

Creating and Using Submaps Changing Submap Characteristics

Setting Submap Geometry

An application sets the size and location of a submap via the OVwModifySubmap() and OVwModifySubmaps() methods. 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 104. An applications request to change the geometry of a submap is denied if a user has saved a submaps geometry through the menu items. For a read-write map, window geometry is saved between sessions. Read-only maps do not have geometry saved between sessions. OVW does 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 is 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 class. The following four flags update the geometry via OVwModifySubmaps:
ovwUpdateSubmapWindowWidth ovwUpdateSubmapWindowHeight ovwUpdateSubmapWindowX ovwUpdateSubmapWindowY

The four relevant fields in the OVwSubmapInfo class are:

submap_window_width; submap_window_height; submap_window_x; submap_window_y;

Chapter 4

119

Creating and Using Submaps Deleting a Submap

Deleting a Submap
The OVwDeleteSubmap() method 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() method has the signature:
public int OVwDeleteSubmap(OVwMapInfo map, int submapId) throws LibOvwException

NOTE

When you delete a submap, OVW assumes that all symbols in the submap should be deleted as well. OVW deletes all symbols in that submap. If the symbol that is deleted is the last symbol representing an underlying object, the object is 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() method does not delete the submaps parent object.

120

Chapter 4

Creating and Using Submaps Getting Map and Submap Information

Getting Map and Submap Information

The Java libovw API provides a number of methods that are useful for finding out information about the open map and its component submaps. These methods: 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() method retrieves information about the open map. It returns a class 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() method has the signature:
public OVwMapInfo OVwGetMapInfo() throws LibOvwException

It returns the map information as an OVwMapInfo class with the following variables: map_name is the map name. permissions specifies whether the map is read-only or read-write. creation_time is the map creation time. last_closed_time is the time the read-write map was last closed. root_submap_id is the root submap for adding top level symbols.

The root_submap_id field is particularly interesting, since it provides an entry point into the submap hierarchies present for the map. Using OVwListSymbols(), a Java libovw API method 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 method, you can determine which symbols, and hence, which submap hierarchies, are present in the root submap.

Chapter 4

121

Creating and Using Submaps Getting Map and Submap Information Many Java libovw API methods take map parameter as the first argument. You should use the OVwGetMapInfo() Java libovw API method to generate the map information. Though you could invoke OVwGetMapInfo() every time you need a map information, 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 method that is registered for the OVwEvents.ovwMapOpen event. Within that callback method, you can use OVwCopyMapInfo() to save the map information returned with the OVwEvents.ovwMapOpen event. The OVwCopyMapInfo() method allocates memory for an OVwMapInfo structure and returns a copy of the specified map.

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() method. OVwGetAppConfigValues() has the following signature:
public OVwFieldBindList OVwGetAppConfigValues(OVwMapInfo map, String appName) throws LibOvwException

OVwGetAppConfigValues() returns a list of field values. The OVwFieldBindList class was described in Chapter 3, Creating and Using Objects and Fields. The OVwFieldBinding class contains field binding information. 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 certain parts of application functionality. The application, not OVW, is responsible for determining how the fields are used and what the field values mean.

122

Chapter 4

Creating and Using Submaps Getting Map and Submap Information Applications can set the application configuration fields using the OVwSetAppConfigValues() method. It has the method signature:
public OVwFieldBindList OVwGetAppConfigValues(OVwMapInfo map, String appName) throws LibOvwException

This method 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 method.

Getting Submap Information

The Java libovw API provides two methods that retrieve information at the submap level, OVwGetSubmapInfo() and OVwListSubmaps(). Using OVwGetSubmapInfo() The OVwGetSubmapInfo() method returns complete information about a given submap, including the submap name, policy, and parent object ID. It has the method signature:
public OVwSubmapInfo OVwGetSubmapInfo(OVwMapInfo map, int submapId) throws LibOvwException

It returns an OVwSubmapInfo class. Using OVwListSubmaps() The OVwListSubmaps() method 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 class, which is a list of field values. The OVwFieldBindList class is described in Chapter 3, Creating and Using Objects and Fields.

The OVwListSubmaps() method has the following signature:

Chapter 4

123

Creating and Using Submaps Getting Map and Submap Information

public OVwSubmapList OVwListSubmaps(OVwMapInfo map, String appName, int submapType, OVwFieldBindList parentFieldValues) throws LibOvwException

The arguments to OVwListSubmaps() are used in the following way: map contains map information for the open map. appName if null, OVW searches all submaps on the open map. If non-null, OVW limits the search to submaps created by the application with the name appName. submapType is a filter for submap types set by the application that created the submap. 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 filter based on a set of field values that are compared with the field values of the parent objects of the submaps. It is an OVwFieldBindList class that contains the particular field values against which parent objects should be compared. The OVwFieldBindList data structure is described in Chapter 3, Creating and Using Objects and Fields.

OVwListSubmaps() returns an OVwSubmapList class. The OVwSubmapList class uses the standard Java libovw API list form: it contains a integer count of the number of entries in the list, and an array of entries. The following code segment shows how to use the OVwListSubmaps() method. 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 1.
... public void init() { LibOvw libovw = new LibOvw(); ... OVwSubmapList list; int i; OVwMapInfo map; OVwFieldBindList bindlist = new OVwFieldBindList(); bind_list.count = 1; ind_list.fields = new OVwFieldBinding[bind_list.count];

124

Chapter 4

Creating and Using Submaps Getting Map and Submap Information

OVwFieldBinding fb = new OVwFieldBinding(); bind_list.fields[0] = fb; try { int f_id = libovw.OVwDbFieldNameToFieldID("isNode"); fb.field_id = f_id; fb.field_val.is_list = false; fb.field_val.field_type = OVwFieldValue.ovwBooleanField; fb.field_val.bool_val = true; } catch (LibOvwException ex) { // handle the exception return; } try { map = libovw.OVwGetMapInfo(); } catch (LibOvwException ex) { // handle exception return; } try { list = libovw.OVwListSubmaps(map, null, ovwAnySubmapType, bind_list); } catch (LibOvwException ex) { int error = ex.getError(); if (error == LibOvwException.SUBMAP_NOT_FOUND) { System.out.println(ex.toString); } } } for (i=0; i<list.count; i++) { System.out.println(" " + list.submaps[i].submap_name); } ...

Chapter 4

125

Creating and Using Submaps Getting Map and Submap Information 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 an application up 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:
public OVwSubmapList OVwListOpenSubmaps (OVwMapInfo map, string appName) throws LibOvwException

The arguments to OVwListOpenSubmaps() are used in the following way: map is the map information for the currently open map. If appName is null, OVW returns a list of all open submaps on the open map. If non-null, OVW limits the results to a list of opened submaps created by the application with the name appName.

OVwListOpenSubmaps() returns an OVwSubmapList class. The OVwSubmapList class uses the standard Java libovw API list form: it contains an integer count of the number of entries in the list, and an array of entries.

126

Chapter 4

Creating and Using Submaps Opening and Closing Maps

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

To determine when a user request to open a map occurs, the application must register a method in the ICallback interface for an OVwEvents.ovwMapOpen event. Within that method, 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 invoke special Java libovw API methods 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 OVwEvents.ovwMapOpen event type using the OVwAddCallback() method. (Chapter 2, Using the HP OpenView Windows Java libovw API, describes how to register callback methods.) The map open callback method has the following signature:
public int OVwAddCallback(long events, ICallback cb) throws LibOvwException

The arguments to the callback method are as follows: events is the mask of the events of interest.

Chapter 4

127

Creating and Using Submaps Opening and Closing Maps cb is the callback handler, the interface used by applications to receive callbacks.

Based on the information from the callback handler, applications can determine if updates are allowed, as well as what updates are required to make the map current. 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 invoke certain Java libovw API methods 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 methods The Java libovw API provides two methods that inform users of map synchronization. These methods are optional but recommended. They have the method signatures:
public int OVwBeginMapSync(OVwMapInfo map) throws LibOvwException public int OVwEndMapSync(OVwMapInfo map) throws LibOvwException

Invoke the LibOvw.OVwBeginMapSync() method to mark the beginning of a synchronization phase. Other applications may also synchronize at the 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 invoke 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. 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 OVwEvents.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

128

Chapter 4

Creating and Using Submaps Opening and Closing Maps 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 method correctly, you can use the same method 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. This simulates the reception of an OVwEvents.ovwMapOpen event. In the following example, some error checking has been removed for brevity.
import hp.ov.libovw.*; public class TestEvent { LibOvw libovw; public void OVwMapOpenCB(OVwMapInfo map, OVwFieldBindList configParams, int eventSource) { try { libovw.OVwBeginMapSync(map); } catch (LibOvwException ex) { // handle the exception return; } // check the map permissions, last close time, and app // configuration values to determine what map updates // are needed try { libovw.OVwEndMapSync(map); } catch (LibOvwException ex) { // handle the exception return; } } public static void main(String args[]) { TestEvent te = new TestEvent(args[0]); } public TestEvent(String session) {

Chapter 4

129

Creating and Using Submaps Opening and Closing Maps

libovw = new LibOvw(); String appname = "MyApplication"; try { libovw.OVwInitSession(appname, session); } catch (LibOvwException ex) { int error = ex.getError(); if (error == LibOvwException.OVW_NOT_RUNNING) { System.out.println("OVW is not running!"); } else { System.out.println("Encountered error " + error + "in TestEvent"); System.out.println(ex.toString()); } } int ret; try { ret = libovw.OVwAddCallback(OVwEvents.ovwMapOpenMask,this); System.out.println("successfully added callbacks"); } catch (LibOvwException ex){ // failure libovw.OVwDone(); libovw = null; System.out.println("OVwAddCallback failed!"); return; } OVwMapInfo map; try { map = libovw.OVwGetMapInfo(); } catch (LibOvwException ex){ // handle exception return; } OVwFieldBindList bind_list; try { bind_list = libovw.OVwGetAppConfigValues(map, appname); } catch (LibOvwException ex){ // handle exception

130

Chapter 4

Creating and Using Submaps Opening and Closing Maps

return; } libovw.OVwMapOpenCB(map, bind_list, OVwEvents.ovwEventSourceUnknown); } }

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 methods for the OVwEvents.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 in 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 reflects the earliest close time returned by all applications. An application can then make appropriate updates to make the map current.

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 method and the map close acknowledgment methods have the following signatures:
public void OVwMapCloseCB(OVwMapInfo map, int mapCloseTime, int eventSource) public int OVwAckMapClose(OVwMapInfo map, int close_time) throws LibOvwException

Chapter 4

131

Creating and Using Submaps Opening and Closing Maps See the reference pages describing the C routines to find more information about these methods.

132

Chapter 4

Creating and Using Submaps Using Submap Background Graphics

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 Java libovw 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 Java libovw API provides two methods that let you programmatically control the background graphics for submaps. They have the following method signatures:
public int OVwSetBackgroundGraphic(OVwMapInfo map, int submapId, String filename) throws LibOvwException public int OVwClearBackgroundGraphic(OVwMapInfo map, int submapId) throws LibOvwException

These methods are quite easy to use. The OVwSetBackgroundGraphic() method 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() method restores the submap background to the default solid color pattern.

Chapter 4

133

Creating and Using Submaps Using Submap Background Graphics

Symbol Placement and Background Graphics

If you use a background graphic that provides some form of geographical map (for example, a building floor plan), then you probably also want to place symbols explicitly at particular locations relative to that map. For this behavior to work correctly, specify ovwNoLayout as the layout algorithm when you create the submap.

Image Formats
OVW Java bindings support background graphic images in these formats: GIF: CompuServe Graphics Interchange Format GIF89 JPEG: Joint Photographics Experts Group

OVW transparently handles the details of displaying different graphics image formats.

134

Chapter 4

Creating and Using Submaps 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.

Chapter 4

135

Creating and Using Submaps 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 create large numbers of submaps should consider creating transient submaps on demand, to minimize the overall size of the map database. Numerous methods 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 Java libovw API methods 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.

136

Chapter 4

Creating and Using Symbols

Chapter 5

137

Creating and Using Symbols Overview

Overview
This chapter introduces the Java libovw API symbol methods. These methods create, manipulate, and delete symbols in HP OpenView Windows. 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. This chapter discusses: characteristics of symbols creating symbols changing symbol appearance and behavior retrieving symbol information retrieving object information

138

Chapter 5

Creating and Using Symbols Characteristics of Symbols

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 Java libovw API symbol methods. 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.

Chapter 5

139

Creating and Using Symbols Characteristics of Symbols 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 are added to the existing capability fields of the underlying object. Symbol classes, symbol subclasses, and default capability fields are described in detail in the online manual, 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: 140 line style based on the subclass of the symbol type Chapter 5

Creating and Using Symbols Characteristics of Symbols 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 shows 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 happens 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 the online manual, 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 point to point bus

Chapter 5

141

Creating and Using Symbols Characteristics of Symbols 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 5-1 lists the four different forms of position: Table 5-1 Forms for Positioning Symbols Form No Position What It Does The symbol has no specific position on the submap. OVW uses the default symbol placement algorithm if you choose this placement value. This position is valid for any layout algorithm. The symbol has an X, Y coordinate position within a grid of given width and height. This position is valid for any layout algorithm. 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. The symbol is the center of a star layout. This position is valid only for the star layout algorithm.

Coordinate Position Sequence Position

Star Center

NOTE

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.

142

Chapter 5

Creating and Using Symbols Characteristics of Symbols 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. Table 5-2 summarizes the possible status values, when they are used, and the color associated with each status condition. Table 5-2 Status Category Administrative HP OpenView Status Colors Status Condition Unmanaged Icon Color/ Connection Color Off-white/ Black

Status Meaning Users can set this value, which indicates that the object should not be monitored and that the status should be ignored. An application sets the status to testing when an object is undergoing temporary diagnostic or maintenance procedures. An application sets the status to restricted when an object is functioning normally, but it may not be available to all users. An application sets the status to disabled when an object is inactive (although there may not be anything wrong with the object). An application sets the status to unknown when the status of an object cannot be determined. An application sets the status to normal when the object is in a normal operational state. An application sets the status to warning when an object may face a potential problem.

Administrative

Testing

Tan/Tan

Administrative

Restricted

Light Pink /Light Pink

Administrative

Disabled

Dark Brown /Dark Brown

Operational

Unknown

Blue/Black

Operational

Normal

Green/ Black Cyan/Cyan

Operational

Warning

Chapter 5

143

Creating and Using Symbols Characteristics of Symbols Table 5-2 Status Category Operational HP OpenView Status Colors (Continued) Status Condition Minor/ Marginal Icon Color/ Connection Color Yellow/ Yellow

Status Meaning An application sets the status to minor/marginal when an object has a minor problem; this status should not, however, impede the normal use of the object. An application sets the status to major when an object has serious problems; these problems are likely to impede normal use of the object. An application sets the status to critical when an object is not functioning.

Operational

Major

Orange/ Orange

Operational

Critical

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 5-3 OVW - ISO Equivalents ISO 10164 Severity Levels none cleared indeterminate critical major minor OVW Status Conditions unmanaged normal unknown critical critical minor/marginal

144

Chapter 5

Creating and Using Symbols Characteristics of Symbols Table 5-3 OVW - ISO Equivalents (Continued) ISO 10164 Severity Levels warning OVW Status Conditions 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 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.

Chapter 5

145

Creating and Using Symbols Characteristics of Symbols 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 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 implemented 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 5-4 lists the symbol presentation capabilities that provide visual cues to emphasize or to de-emphasize a symbol.

146

Chapter 5

Creating and Using Symbols Characteristics of Symbols Table 5-4 Attribute Flashing symbols Symbol Presentation Attributes Description 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. Refer to Flashing Symbols on page 174. 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. Refer to Transparent Symbol Background on page 171. Applications can present executable symbols without the box around the symbol. (The box provides the visual cue that the symbol is executable.) This functionality can be disabled by operators by changing a setting. Refer to Executable Symbol Appearance on page 173. 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 176. 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 176.

Transparent symbol backgrounds

Disable executable symbol cue

Connection symbol thickness

Chapter 5

147

Creating and Using Symbols Characteristics of Symbols Table 5-4 Attribute Connection symbol secondary status Symbol Presentation Attributes (Continued) Description 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 176. Text annotation Applications can dynamically superimpose text over icon symbols, connection symbols, and symbol alerts. Refer to Text Annotation for Symbols on page 174.

148

Chapter 5

Creating and Using Symbols 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 LibOvw.OVwCreateSymbol() method is a general purpose method that can create any type of icon symbol for an existing object. It has the method signature:
public int OVwCreateSymbol(OVwMapInfo map, int submapId, int objectId, String symbolType, String label, int status, int statusSource, OVwSymbolPosition position, int flags) throws LibOvwException

The arguments to OVwCreateSymbol() are described below. The map argument deserves special attention here. Most Java libovw API symbol methods take the map parameter as the first argument. You can use the OVwGetMapInfo() Java libovw API method to generate the map parameter, or you can save the map information in a notification. Within the callback method, you can use LibOvw.OVwCopyMapInfo() to save the map information returned with the OVwEvents.ovwMapOpen event. Map information is valid until the map is closed. When invoking OVwCreateSymbol(), you need to supply these arguments: map contains an OVwMapInfo class that contains complete map information. You can use the OVwGetMapInfo() method 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.

Chapter 5

149

Creating and Using Symbols Creating Symbols symbolType is a character string identifying a symbol class/subclass pair as defined in a Symbol Registration File. 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, ovwMinorStatus, ovwCriticalStatus, and ovwUnmanagedStatus. The defined values are described in the hp.ov.libovw.OVwSymbolInfo class. statusSource defined in the OVwSymbolInfo class describes how the symbol receives status information. Possible values are: ovwSymbolStatusSource, ovwObjectStatusSource, and ovwCompoundStatusSource. The defined values are described in the hp.ov.libovw.OVwSymbolInfo class. 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 and are found in the hp.ov.libovw.OVwSymbolInfo class.

The OVwCreateSymbol() method returns a symbol ID, which is a unique numeric identifier for the symbol. The symbol ID is used in subsequent invocations 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.
import hp.ov.libovw.OVwSymbolInfo; ... public void create_symbol(int object_id) { OVwMapInfo map; try { map = libovw.OVwGetMapInfo(); } catch (LibOvwException ex) { // handle the exception return; }

150

Chapter 5

Creating and Using Symbols Creating Symbols

// Create the symbol using an OVW constant to represent // the symbol type int symid; try { symid = libovw.OVwCreateSymbol(map, map.root_submap_id, oject_id, "test", OVwSymbolInfo.ovwUnknownStatus, "Computer:Workstation", OVwSymbolInfo.ovwSymbolStatusSource,null, OVwSymbolInfo.ovwNoSymbolFlags); } catch (LibOvwException ex) { //handle the exception return null; } ... }

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() method While the OVwCreateSymbol() method can create any type of icon symbol, convenience methods are available that are easier to use in certain situations. All of these methods throw a LibOvwException and must be bracketed in try...catch blocks. They include:
OVwCreateSymbolByName(), OVwCreateSymbolBySelectionName(), OVwCreateSymbolByHostname()

These methods let you identify the object by one of its names, instead of by its object ID. If the object does not yet exist, these methods first create the object for you using OVwDbCreateObject():
OVwCreateComponentSymbol(), OVwCreateComponentSymbolByName()

These two methods 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 creates it for you. These convenience methods use many of the same parameters as the general purpose OVwCreateSymbol() method and are quite similar in concept. See the reference pages for the C functions for more information about these invocations.

Chapter 5

151

Creating and Using Symbols Creating Symbols Symbol Creation Flags Flags control miscellaneous aspects of symbol creation. The flags are described in the hp.ov.libovw.OVwSymbolInfo class. 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(). ovwDoNotDisplayLabel Setting this flag prevents 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() invocation are 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 is added to the object. Existing field values within the object are not changed. See the OVwCreateSymbol(3) reference page for the C function for 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 places symbols where you request and makes 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 defined in the hp.ov.libovw.OVwSymbolPosition class. The following list summarizes the four position forms and when they can be used: ovwNoPosition Indicates no position, which is valid for any layout algorithm. ovwCoordPosition Indicates Coordinate Position and is valid for any layout algorithm. The symbol has x and y coordinate position. The width and height values set the scale of a grid on which to interpret the x and y values. 152 Chapter 5

Creating and Using Symbols Creating Symbols ovwSequencePosition Indicates Sequence Position, which is valid for any sequence layout algorithm (ring, star, bus, or row/column). ovwStarCenterPosition Indicates Star Center Position, which is valid only for the star layout algorithm. The symbol is the center of a start layout. You can specify these position forms, as well as the associated information for the position, using the OVwSymbolPosition class that includes the four position forms and the following variables: placement is the type of symbol placement x is the x position on the grid y is the y position on the grid width is the width of the grid height is the height of the grid pred_symbol is the ordering information for the ovwSequencePosition

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 class. The first symbol in the sequence has the special value ovwNullSymbolId. OVW places 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.

Chapter 5

153

Creating and Using Symbols 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 are 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 is placed at the center of the submap. A symbol placed at position [150,200] on a [300 x 400] grid is also 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 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, 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.

154

Chapter 5

Creating and Using Symbols Creating Symbols

NOTE

Symbol positions specified by coordinates are lost whenever the user invokes the automatic layout algorithm. If your application needs to disable all automatic layouts, set the layout algorithm flag, layout_on, to false during submap creation. The flag is described in the hp.ov.libovw.OVwSubmapInfo class.

More information about the symbol positions including the ovwNoPosition and ovwStarCenterPosition position forms can be found on the OVwSetSymbolPosition(3) reference page for the C functions. 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() method to create a connection symbol. This method has the signature:
public int OVwCreateConnSymbol(OVwMapInfo map, int connectId, int endpoint1, int endpoint2, String symbolType, String label,int status, int statusSource, int flags) throws LibOvwException

An object that represents the connection must already exist in order to use the OVwCreateConnSymbol() method. The objectId argument contains the object ID of the object that represents the connection. Chapter 5 155

Creating and Using Symbols Creating Symbols 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 find a meta-connection symbol, not the actual connection symbol for the particular connection. You 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 can change the status of the connection symbol. Refer to the OVwCreateSymbol(3) reference page for the C routine if you need more information about meta-connections.

156

Chapter 5

Creating and Using Symbols Creating Symbols

Creating Multiple Symbols with a Single Invocation

The Java libovw API provides the OVwCreateSymbols() method to let you create multiple symbols in a single invocation. The OVwCreateSymbols() method can create combinations of both icon and connection symbols. To do this, OVwCreateSymbols() uses a rather complex class that allows you to define either icon or connection symbols. Most of the class elements have been described in some form earlier in this chapter; however, three of the class 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 174 and Connection Symbol Appearance on page 176. The OVwCreateSymbols() method has the signature:
public int OVwCreateSymbols(OVwMapInfo map, OVwSymbolCreateList symbolList) throws LibOvwException

The symbolList parameter is an OVwSymbolCreateList that contains a count of the number of symbols and an array of OVwSymbolCreateInfo, each of which fully defines the symbol to be created. Use OVwSymbolCreateInfo to define each symbol you want to create. OVwSymbolCreateInfo contains the symbol information used to create symbols such as the the connection endpoints, submap ID, object information, and connection symbol. The following code fragment shows how to create multiple symbols with the OVwCreateSymbols() method without making connections between the symbols:
import hp.ov.libovw.*; class MyOvwClass { LibOvw libovw; ... public MyOvwClass() { // perform appropriate initialization ... }

Chapter 5

157

Creating and Using Symbols Creating Symbols

public OVwSymbolCreateInfo build_icon(int submapId) { OVwSymbolCreateInfo sym = new OVwSymbolCreateInfo(); sym.submap_name_style = OVwSymbolInfo.ovwSubmapIdValue; sym.id = submapId; sym.object_name_style = OVwSymbolInfo.ovwObjectIdValue; try { sym.object_id = libovw.OVwDbCreateObject(null); } catch (LibOvwException ex) { // handle the exception return; } sym.object_name = "Computer:Workstation"; sym.label = "new symbol"; // all the other fields initialized here ... return sym; } public OVwSymbolCreateInfo[] buildIconSymbols(int howMany, int submapId) { OVwSymbolCreateInfo info[] = new OVwSymbolCreateInfo[howMany]; for (int i = 0; i < howMany; i++) { info[i] = build_icon(submapId); } return info; } public void createSymbol() { OVwSymbolCreateList symbolList = new OVwSymbolCreateList(); symbolList.symbols = buildIconSymbols(1, map.root_submap_id); symbolList.count = symbolList.symbols.length; try { libOvw.OVwCreateSymbols(map, symbolList); } catch (LibOvwException ex) { // handle error

158

Chapter 5

Creating and Using Symbols Creating Symbols

return; } } }

Advantages/Disadvantages to Using OVwCreateSymbols() The advantage to using this method 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 classes involved 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() method or use OVwCreateSymbols() with only a few symbols. If users do not expect immediate feedback, you can use the more efficient OVwCreateSymbols() method.

Deleting Symbols
The Java libovw API provides two methods to delete symbols. The OVwDeleteSymbol() method deletes a single symbol from the open map, while the OVwDeleteSymbols() method deletes a list of symbols. Either method can be used to delete icon or connection symbols. These methods have the signatures:
public int OVwDeleteSymbol(OVwMapInfo map, int symbolId) throws LibOvwException public int OVwDeleteSymbols(OVwMapInfo map, OVwSymbolIdList symbolList) throws LibOvwException

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 5

159

Creating and Using Symbols 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 3, 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 6, Map Editing and Map Events, describes how to determine when objects should be deleted. Specifically, that chapter describes how to implement methods of the ICallback interface 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 invocations: 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 notification method for the actions or events 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 Java libovw APIs to implement symbol alerts. For information about definition of registration file components of symbol alerts, refer to the online manual, Creating and Using Registration Files.

160

Chapter 5

Creating and Using Symbols 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 targets 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) implement the ICallback method, then register interest in that callback using the OVwAddActionCallback() method. 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,

Chapter 5

161

Creating and Using Symbols Creating Symbols which has registered for the 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 method 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 looks like this:
Application "FireFighter" { Action "CheckSmoke" { . .

and the callback registration code looks like this:

import hp.ov.libovw.*; class FireFighterCB extends OVwEventAdapter { public void OVwAddActionCB(String actionID, String menuItemID,OVwObjectIdList selected, int argc, StringVectorParm argv,OVwMapInfo mapInfo, int submapId) {

162

Chapter 5

Creating and Using Symbols Creating Symbols

if (actionID == "CheckSmoke") {...} } public static void main(String args[]) { FireFighterCB firefighter = new FireFighterCB(args[0]); } public FireFighterCB(String session) { LibOvw libovw = new LibOvw(); try { libovw.OVwInitSession("Test", session); } catch (LibOvwException ex) { // handle the exception return; } try { libovw.OVwAddActionCallback("CheckSmoke", this); } catch (LibOvwException ex) { //handle the exception return; } } }

Symbol Alert Components The symbol alert, illustrated in Figure 5-1 and described in the remainder of this section, consists of five parts.

Chapter 5

163

Creating and Using Symbols Creating Symbols

Figure 5-1

Symbol Alert
3 Text Annotation for Symbol Alert

Pop-Up Menu 4 Default Action 5 Alert Action 2 Alert Action 3 1

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 throws an exception. 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. Only one symbol alert per symbol is allowed; an attempt to create one for a symbol that already has a symbol alert throws an exception. The ICallback.OVwConfirmDeleteSymbolAlert()

164

Chapter 5

Creating and Using Symbols Creating Symbols method 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 the online manual, Creating and Using Registration Files, 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. (For text localization issues, refer to Chapter 7, Developing Internationalized and Localized Applications. The text region for each alert type is specified in its registration file. Refer to the online manual, Creating and Using Registration Files. 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 168.)

4. Default action.

Chapter 5

165

Creating and Using Symbols Creating Symbols The default action is the action that is executed when a symbol 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 the online manual, Creating and Using Registration Files, 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 the online manual, Creating and Using Registration Files, 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 ICallback methods for the symbol alert pop-up menu actions defined within its application registration file. These ICallback methods 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. 166 Chapter 5

Creating and Using Symbols Creating Symbols 5. OVW invokes the applications specific action notification 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:

pubic int OVwCreateSymbolAlert(OVwMapInfo map, int baseSymbolId, String symAlertType, String defaultActionId, String defaultActionAppId, String textAnnotation, int alertTextAlignment) throws LibOvwException

OVwCreateSymbolAlert() requires the following arguments: map contains map information for an open map. The map 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 the online manual, Creating and Using Registration Files. The value of symAlertType must be in double quotes like other values of the type String. 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 the online manual, Creating and Using Registration Files. 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.

Chapter 5

167

Creating and Using Symbols Creating Symbols 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). These values are described in the hp.ov.libovw.OVwSymbolInfo class.

Deleting the Symbol Alert OVwDeleteSymbolAlert() has the following method signature:
public int OVwDeleteSymbolAlert(OVwMapInfo map, int baseSymbolId) throws LibOvwException

map contains map information for an open map. The map parameter can be obtained using OVwGetMapInfo() or saved from the ovwMapOpen event using OVwCopyMapInfo(). baseSymbolId specifies the symbol ID of the base symbol.

Setting Symbol Alert Text Annotation OVwSetSymbolAlertText() lets applications dynamically create or change the contents of a symbol alerts text region. The method signature for OVwSetSymbolAlertText() is:
public int OVwSetSymbolAlertText(OVwMapInfo map, int baseSymbolId, String textAnnotation, int alertTextAlignment) throws LibOvwException

map contains map information for an open map. The map parameter can be obtained using OVwGetMapInfo() or saved from the ovwMapOpen event using OVwCopyMapInfo(). baseSymbolId specifies the symbol ID of the base symbol. 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). These values are described in the hp.ov.libovw.OVwSymbolInfo class.

Implementing Methods for Confirmation of Symbol Alert Deletion

168

Chapter 5

Creating and Using Symbols Creating Symbols Applications can implement methods of the ICallback interface 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 situation, an application can implement methods for the OVwEvents.ovwConfirmDeleteSymbolAlert event. As other applications delete symbol alerts, OVW invokes the method implemented for the event of interest. Within the callback function, the application tests the symbol_id element within the baseSymbolInfo parameter and determine whether the symbol alert deletion is from the targeted symbol. The method signature for OVwConfirmDeleteSymbolAlertCB()is:
public abstract void OVwConfirmDeleteSymbolAlertCB (OVwMapInfo map,OVwSymbolInfo symbol)

map is the map information for the open map. symbol is the OVwSymbolInfo of the symbol whose alert was deleted.

Chapter 5

169

Creating and Using Symbols Changing Symbol Appearance and Behavior

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 LibOvw.OVwModifySymbol() and LibOvw.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

The resources for enabling transparency, executability, and flashing are specified via: X resources for UNIX systems. the registry in HKEY_LOCAL_MACHINE\SOFTWARE\Hewlett-Packard\OpenView\ Network Node Manager\OVw for Windows systems.

You can use OVwModifySymbols() and OVwModifySymbol() to change attributes of symbols. These methods have the following signatures:

170

Chapter 5

Creating and Using Symbols Changing Symbol Appearance and Behavior

public int OVwModifySymbol(OVwMapInfo map, OVwSymbolUpdateInfo symbol) throws LibOvwException public int OVwModifySymbols(OVwMapInfo map, OVwSymbolUpdateList symbols) throws LibOvwException

When calling OVwModifySymbols(), you need to supply these arguments: map contains complete map information. You can use the OVwGetMapInfo() method to get the map information. symbols contains a list of OVwSymbolUpdateInfo items, describing each symbol to be updated. symbol points to the OVwSymbolUpdateInfo class containing the updated symbol information and the flags indicating which elements of information to change.

The steps below describe how to change symbol appearance or behavior: 1. Create OVwSymbolInfo. 2. Set the transparency field to true via:
public boolean transparent

3. Create OVwSymbolUpdateInfo. 4. Specify a mask including the logically ORed update flags relevant to the symbol appearance or behavior. For example, the mask could contain update flags for transparency or flashing behavior. 5. Call LibOvw.OVwModifySymbol(). 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. 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.

Chapter 5

171

Creating and Using Symbols Changing Symbol Appearance and Behavior When that happens, the symbols background shape and status color are shown so that it is 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. The status is defined in the hp.ov.libovw.OVwSymbolInfo class. 1. If a symbol has the status source set to ovwObjectStatusSource, then a moved symbol has the same status that it had before it was moved. Therefore, a transparent symbol with a status source set to ovwObjectStatusSource most likely appears as transparent after it is moved. It only appears differently 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 is determined by the status propagation algorithm set for the map. Typically, the status is the same and the symbol appears as transparent unless the status of the other objects changed. 3. If a symbol has the status source set to ovwSymbolStatusSource, then a moved symbol has a status of unknown. Therefore, the symbol is not transparent when it is moved because it needs a normal status to be transparent. It continues to have an unknown status until an application adopts the symbol.The application may then set the status to normal and the symbol becomes transparent. If an application never recognizes the symbol it remains in an unknown status. Use the OVwModifySymbol() and OVwModifySymbols() methods to specify whether a symbol should be transparent or not on a per-symbol basis. The update flag is:
ovwUpdateSymbolTransparency

The field in the OVwSymbolInfo class is:

public boolean transparent

For both the Windows and UNIX, to make the symbol transparent, the developer must specify that the symbol should be transparent via the ovwUpdateSymbolTransparency flag.

172

Chapter 5

Creating and Using Symbols Changing Symbol Appearance and Behavior For UNIX, the user must also enable 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 LibOvw.OVwModifySymbol() and LibOvw.OVwModifySymbols() methods on a per symbol basis whether the visual cue for executable symbols is visible. The update flag is:
ovwUpdateSymbolExecVisCue

The field in the OVwSymbolInfo class is:

public boolean exec_vis_cue

For both Windows and UNIX, to disable the executable symbol visual cue, the developer must specify that the symbol visual cue should be disabled via the ovwUpdateSymbolExecVisCue flag. For UNIX, an executable symbol visual cue is disabled only if the user has also set the X resource to True. The default X resource for this functionality is:
OVw*enableExecCueRemoval:True

Chapter 5

173

Creating and Using Symbols Changing Symbol Appearance and Behavior 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 LibOvw.OVwModifySymbol() and LibOvw.OVwModifySymbols() methods. The update flag is:
ovwUpdateSymbolFlashing

The field in the OVwSymbolInfo class is:

public boolean flashing

For both Windows and UNIX, a symbol is flashing if the developer has specified that the symbol should be flashing via the ovwUpdateSymbolFlashing flag. For UNIX, a symbol is flashing only if the user has also 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*enableFlashing:True

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

174

Chapter 5

Creating and Using Symbols Changing Symbol Appearance and Behavior 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 than 12 characters do not automatically wrap to a new line; rather, the additional characters are 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 displays an error message and truncates the text annotation to 2 lines. You can specify annotation text via the OVwCreateSymbols() methods (see Creating Multiple Symbols with a Single Invocation on page 157) or the OVwModifySymbol() and OVwModifySymbols() APIs. The field in the OVwSymbolInfo class is:
public String text_annotation

The update flag is:

ovwUpdateTextAnnotationText

For UNIX, the default behavior for text annotation is defined by setting the following X resources: OVw*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.

Chapter 5

175

Creating and Using Symbols Changing Symbol Appearance and Behavior textAnnotationBackgroundColor Defines the fill color for the text background. textAnnotationColor Defines the color of the text annotation string. On Windows, the default behavior is set in the following key in the Windows registry: \HKEY_LOCAL_MACHINE\SOFTWARE\Hewlett-Packard\OpenView\ Network Node Manager\OVw\Map TextAnno The following values can be defined: displayTextAnnotationBackground TextAnnotationBackgroundColor textAnnotationColor

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 appears 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.

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).

176

Chapter 5

Creating and Using Symbols Changing Symbol Appearance and Behavior 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 appears 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 appears 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 is of sufficient width to display the differences, the connection symbol appears 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 LibOvw.OVwCreateSymbols() API (see Creating Multiple Symbols with a Single Invocation on page 157) or the OVwModifySymbol() and OVwModifySymbols() APIs. The update flags are:
ovwUpdateSymbolPercentFull ovwUpdateSymbolSecondaryStatus

The fields in the OVwSymbolInfo class are:

public int percent_full public int 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. 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() Java libovw API method changes the symbol type. It has the method signature:

Chapter 5

177

Creating and Using Symbols Changing Symbol Appearance and Behavior

public int OVwSetSymbolType(OVwMapInfo map, int symbolId, String symbolType, int flags) throws LibOvwException

You can use application-defined symbol types or you can use the symbol types provided with OVW.

Changing a Symbols Position

You can change the position of a symbol at any time using the OVwSetSymbolPosition() method. This method changes the position of an existing symbol. It has the method signature:
public int OVwSetSymbolPosition(OVwMapInfo map, int symbolId, OVwSymbolPosition position) throws LibOvwException

The OVwSymbolPosition class is described in the Creating Symbols on page 149. See that section to learn how to use the OVwSymbolPosition class to define symbol position.

Changing a Symbols Behavior

The OVwSetSymbolBehavior() method changes the behavior of a symbol on the open map. By default, symbols are explodable. This method can make a symbol explodable or executable. The OVwSetSymbolBehavior() method has the method signature:
public int OVwSetSymbolBehavior(OVwMapInfo map, int symbolId, int behavior, String appName, String actionId, OVwObjectIdList targetObjects) throws LibOvwException

The OVwSetSymbolBehavior() method has the following arguments: map contains complete map information. You can use the OVwGetMapInfo() method 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 the online manual, Creating and Using Registration Files. Chapter 5

178

Creating and Using Symbols Changing Symbol Appearance and Behavior 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 continues 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 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 173. 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:
import hp.ov.libovw.*; .... LibOvw libovw = new LibOvw(); public void make_executable(int symId){ String action_name = "Show Users";

Chapter 5

179

Creating and Using Symbols Changing Symbol Appearance and Behavior

OVwMapInfo map; try { map = libovw.OVwGetMapInfo(); } catch (LibOvwException ex) { // handle the exception return; } String app_name; try { app_name = libovw.OVwGetAppName(); } catch (LibOvwException ex) { // handle the exception return; } try { libovw.OVwSetSymbolBehavior(map, symId, OVwSymbolInfo.ovwSymbolExecutable, app_name, action_name, null); } catch (LibOvwException ex) { // handle the exception return; } } ....

The OVwGetAppName() method retrieves the application name before invoking OVwSetSymbolBehavior().

Changing a Symbols Label

You can change a symbols label with the OVwSetSymbolLabel() method. The method has the signature:
public int OVwSetSymbolLabel(OVwMapInfo map, int symbolId, String label) throws LibOvwException

The OVwSetSymbolLabel() method is used only to define the label. Use the OVwSetSymbolType() method to control whether the label is displayed.

180

Chapter 5

Creating and Using Symbols Changing Symbol Appearance and Behavior

NOTE

You should use discretion when using this method. 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() method, 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 methods are 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 methods are described later.

An application interested in a symbol created by another application should invoke the OVwSetSymbolApp() Java libovw API method. This method adds the invoking application to the list of applications interested in the symbol. The OVwClearSymbolApps() method clears the application from this list. These methods have the signatures:
public int OVwSetSymbolApp(OVwMapInfo map, int symbolId) throws LibOvwException public int OVwClearSymbolApp(OVwMapInfo map, int symbolId) throws LibOvwException

Refer to the OVwSetSymbolApp(3) reference page for the C function for more information about these methods. Chapter 5 181

Creating and Using Symbols Changing Symbol Appearance and Behavior

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 139 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() method. It has the method signature:
public int OVwSetSymbolStatusSource(OVwMapInfo map, int symbolId, int statusSource) throws LibOvwException

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 Java libovw methods that set status values on a symbol or object have the following method signatures:
public int OVwSetStatusOnSymbol(OVwMapInfo map, int symbolId, int status) throws LibOvwException

182

Chapter 5

Creating and Using Symbols Changing Symbol Appearance and Behavior

public int OVwSetStatusOnObject(OVwMapInfo map, int objectId, int status) throws LibOvwException

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 invocation also sets the object status on all symbols that represent the object and have status source ovwObjectStatusSource. You cannot set symbol or object status on an object that is unmanaged. Two list forms of status methods are also available for setting status on multiple symbols or objects. They are more efficient than making multiple individual invocations, since OVW compound status propagation is disabled until the status of all entities in the list are set. They have the method signatures:
public int OVwSetStatusOnSymbols(OVwMapInfo map, OVwSymbolStatusList symbolList) throws LibOvwException public int OVwSetStatusOnObjects(OVwMapInfo map, OVwObjectStatusList objectList) throws LibOvwException

The symbolList and objectList classes have the same form as other common lists in the Java libovw API. They contain a count of the number of elements in the list and a contiguous array of list entries.

Chapter 5

183

Creating and Using Symbols Retrieving Symbol Information

Retrieving Symbol Information

This section describes the various Java libovw API methods that retrieve symbol information.

OVwSymbolInfo Class
Before describing the methods that retrieve symbol information, it is first necessary to describe the OVwSymbolInfo class. This class is used by most Java libovw API methods 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 class 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 class, and their descriptions are not repeated here. The OVwSymbolBehavior class contains information specific to the symbol behavior. Currently, this is used only for executable symbol information. Most of the fields have already been used in previously described Java libovw API symbol methods. With the discussion of the OVwSymbolInfo class complete, the methods to retrieve symbol information can be described.

Retrieving Symbol Information with OVwGetSymbolInfo()

The OVwGetSymbolInfo() Java libovw API method is a general purpose method that can retrieve complete symbol information for any symbol. Given a symbol ID for any symbol, this method returns an OVwSymbolInfo class containing complete symbol information. The method signature is shown below:
public OVwSymbolInfo OVwGetSymbolInfo(OVwMapInfo map, int symbolId) throws LibOvwException

The following code segment demonstrates how to use this method.

184

Chapter 5

Creating and Using Symbols Retrieving Symbol Information

... LibOvw libovw = new LibOvw(); public void dump_symbol_info(int symbol_id){ OVwMapInfo map; try { map = libovw.OVwGetMapInfo(); } catch (LibOvwException ex) { // handle the exception return; } OVwSymbolInfo p; try { p = libovw.OVwGetSymbolInfo(map,symbol_id); } catch (LibOvwException ex) { // handle the exception return; } System.out.println("The symbol with ID has the following values:" + symbol_id); System.out.println(" variety: " + ((p.symbol_variety == OVwSymbolCreateInfo.ovwIconSymbol) ("icon"):("connection"))); System.out.println(" behavior:" + ((p.behavior == OVwSymbolInfo.ovwSymbolExecutable) ("executable"):("explodable"))); ... } ...

Getting Connection Symbol Information

The OVwGetConnSymbol() determines if a connection exists between any two icon symbols. If such a connection exists, the method returns an OVwSymbolInfo class containing complete connection symbol information. The method has the signature:
public OVwSymbolInfo OVwGetConnSymbol(OVwMapInfo map, int endpoint1, int endpoint2) throws LibOvwException

Chapter 5

185

Creating and Using Symbols Retrieving Symbol Information The following code fragment shows how to list the connections of a metaconnection submap.
import hp.ov.libovw.*; ... LibOvw libovw = new LibOvw(); OVwSymbolInfo syminfo; OVwMapInfo map; try { map = libovw.OVwGetMapInfo(); } catch (LibOvwException ex) { // handle the exception return; } int from_id, to_id; try { syminfo = libovw.OVwGetConnSymbol(map, from_id, to_id); } catch (LibOvwException ex) { // handle the exception System.out.println("exception is " + ex.getError() + " " + ex.toString()); return null; } OVwSymbolList symlist = new OVwSymbolList() try { symlist = libovw.OVwListSymbols(map, syminfo.object.child_submap_id, OVwSymbolInfo.ovwAllPlanes, null); } catch (LibOvwException ex) { // handle the exception return; } for (i=0; i<symlist.count; i++) { if (symlist.symbols[i].symbol_variety == OVwSymbolInfo.ovwConnSymbol) {

186

Chapter 5

Creating and Using Symbols Retrieving Symbol Information

System.out.println("Connection found."); } }

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() Java libovw method 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() method has the method signature:
public OVwSymbolList OVwListSymbols(OVwMapInfo map, int submapId, int plane, String appName) throws LibOvwException

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() returns only those symbols for which the application has expressed interest. If appName is null, OVwListSymbols() returns a list of all symbols in the specified planes.

Symbol Type methods

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

Chapter 5

187

Creating and Using Symbols Retrieving Object Information

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 methods that operate on them, are described in this section.

The OVwObjectInfo Class

The OVwObjectInfo class stores map-specific object information. This class is used by Java libovw API methods that retrieve map-specific object information. The OVwObjectInfo class contains the following variables: child_submap_id compound_status field_values num_symbols object_id object_status op_scope Note that all of the fields in this class 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 class are self-explanatory. Two fields, however, require further description.

188

Chapter 5

Creating and Using Symbols Retrieving Object Information 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 ICallback methods. 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 method for ovwConfirmCapabilityChange and ovwConfirmDeleteObjects events. The Java doc file contains the definition for the OVwObjectInfo class, as well as additional comments about the fields and how they are used.

Retrieving Object Information with OVwGetObjectInfo()

The OVwGetObjectInfo() Java libovw API method retrieves map-specific object information for any object. Given an object ID, this method returns an OVwObjectInfo class containing complete mapspecific object information. The method signature is shown below:
public OVwObjectInfo OVwGetObjectInfo(OVwMapInfo map, int objectId) throws LibOvwException

NOTE

OVwGetObjectInfo() returns only the map-specific information relating to an object. If you need global object information, you might need to use the OVwDbGetFieldValues() Java libovw API method. See Chapter 3, Creating and Using Objects and Fields, for information about Java libovw API methods that apply to the global attributes of objects.

Getting Symbol IDs Associated with an Object

The OVwGetSymbolsByObject() Java libovw API method 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 method. When OVW invokes a notification, 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() method to convert the list of object IDs to a list of all symbols that represent the given object. The OVwGetSymbolsByObject() method has the following signature:

Chapter 5

189

Creating and Using Symbols Retrieving Object Information

public OVwSymbolList OVwGetSymbolsByObject(OVwMapInfo map, int objectId) throws LibOvwException

It returns a standard Java libovw API list, composed of an integer count of the number of entries in the list and an array of list entries. For information about the use of OVwGetSymbolsByObject()in transient submaps, refer to Considerations for Transient Submap Applications on page 213.

Getting a List of All Objects on a Map

The OVwListObjectsOnMap() Java libovw method is useful for getting a list of all the objects that are present on the open map. The OVwListObjectsOnMap() method has the following signature:
public OVwObjectList OVwListObjectsOnMap(OVwMapInfo map, OVwFieldBindList fieldValues) throws LibOvwException

The OVwListObjectsOnMap() method returns an OVwObjectList class. The OVwObjectList class is a standard Java libovw API list, composed of an integer count of the number of entries in the list and an array of list entries. The fieldValues argument is an optional argument that OVW uses to filter the list of objects returned by the OVwListObjectsOnMap() method. 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. For information about the use of OVwGetSymbolsByObject()in transient submaps, refer to Considerations for Transient Submap Applications on page 213.

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 Java libovw methods take care of setting the appropriate global or map-specific object attributes. For example, when calling the OVwSetStatusOnObjects() method, 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.

190

Chapter 5

Creating and Using Symbols Retrieving Object Information 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 method. Those methods are described in Chapter 3, Creating and Using Objects and Fields. When retrieving map-specific information, the developer should use the OVwGetObjectInfo() method or another method presented in this section.

Chapter 5

191

Creating and Using Symbols Summary

Summary
This chapter described how to use the OVw symbol methods 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 Java libovw symbol methods were presented that change symbol appearance or behavior. These included methods 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() method and various other related methods. 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.

192

Chapter 5

Map Editing and Map Events

Chapter 6

193

Map Editing and Map Events Overview

Overview
This chapter introduces the Java libovw API map editing methods. Map editing methods 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 discusses: receiving notification of map changes participating in map changes cut and paste operations how to participate in map locates considerations for transient submaps

194

Chapter 6

Map Editing and Map Events Receiving Notification of Map Changes

Receiving Notification of Map Changes

Recall from Chapter 2, Using the HP OpenView Windows Java libovw API, that applications can implement the ICallback interface to send notifications to applications when specific OVW events occur. A number of OVW events have already been described earlier in this manual, including the OVwEvents.ovwMapOpen, OVwEvents.ovwMapClose, and OVwEvents.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 implement the LibOvw.OVwAddCallback() method to register their interest in specific event types.

Map Editing Events

Table 6-1 summarizes the map editing events. Table 6-1 OVW Events and ICallback Methods Event Type ovwEndSession ovwSelectListChange Event Meaning/Name of Corresponding ICallback Method OVW terminated. OVwEndSessionCB(...) The selection list changed. OVwSelectListChangeCB(...)

Chapter 6

195

Map Editing and Map Events Receiving Notification of Map Changes Table 6-1 OVW Events and ICallback Methods (Continued) Event Type ovwMapOpen ovwMapClose ovwConfirmDeleteSymbols ovwConfirmDeleteObjects ovwConfirmDeleteSubmaps ovwConfirmCreateSymbols ovwConfirmCreateObjects ovwConfirmCreateSubmaps ovwConfirmMoveSymbol ovwConfirmManageObjects ovwConfirmUnmanageObjects ovwConfirmHideSymbols ovwConfirmUnhideSymbols ovwConfirmSymbolStatusChange ovwConfirmObjectStatusChange Event Meaning/Name of Corresponding ICallback Method A map was opened. OVwMapOpenCB(...) A map was closed. OVwMapCloseCB(...) One or more symbols were deleted from the map. OVwConfirmDeleteSymbolsCB(...) One or more objects were deleted from the map. OVwConfirmDeleteObjectsCB(...) One or more submaps were deleted from the map. OVwConfirmDeleteSubmapsCB(...) One or more symbols were created on the map. OVwConfirmCreateSymbolsCB(...) One or more objects were created on the map. OVwConfirmCreateObjectsCB(...) One or more submaps were created on the map. OVwConfirmCreateSubmapsCB(...) A symbol was moved within a submap. OVwConfirmMoveSymbolCB(...) One or more objects became managed on the map. OVwConfirmManageObjectsCB(...) One or more objects became unmanaged on the map. OVwConfirmUnmanageObjectsCB(...) OVW made one or more symbols hidden. OVwConfirmHideSymbolsCB(...) OVW made one or more symbols unhidden. OVwConfirmUnhideSymbolsCB(...) The status of one or more symbols changed. OVwConfirmSymbolStatusChangeCB(...) The object status of one or more objects changed. OVwConfirmObjectStatusChangeCB(...)

196

Chapter 6

Map Editing and Map Events Receiving Notification of Map Changes Table 6-1 OVW Events and ICallback Methods (Continued) Event Type ovwConfirmCompoundStatusChange Event Meaning/Name of Corresponding ICallback Method The compound status of one or more objects changed. OVwConfirmCompoundStatusChangeCB(...) The capability field of one or more objects changed. OVwConfirmCapabilityChangeCB(...) The app field of one or more objects was configured. OVwConfirmAppConfigCB(...) ovwConfirmDescribe The description field of one or more objects was changed. OVwConfirmDescribeCB(...) As you can see from the table, the names of the ICallback methods are derived from the event name. For example, the OVwEvents.ovwConfirmSymbolStatusChange event has the callback method OVwConfirmSymbolStatusChangeCB(). This naming convention lets you easily translate between event types and method signatures. 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 yethidden symbol events and unmanaged object events. These are described next.

ovwConfirmCapabilityChange ovwConfirmAppConfig

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 does 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 notifies all objects that have: implemented the ICallback interface, and

Chapter 6

197

Map Editing and Map Events Receiving Notification of Map Changes registered for the specific event, OVwEvents.ovwConfirmHideSymbols, via OVwAddCallback()

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 notifies all objects that have implemented the ICallback interface and have registered for the OVwEvents.ovwConfirmUnhideSymbols event type via OVwAddCallback(). 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 214). Symbols representing unmanaged objects do not receive status updates from applications. Applications 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 5, Creating and Using Symbols, if you need more information about status colors and their meaning.

198

Chapter 6

Map Editing and Map Events Receiving Notification of Map Changes

NOTE

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 implementing the ICallback interface and registering for the OVwEvents.ovwConfirmUnmanageEvent type via OVwAddCallback(), applications can determine if the object is currently managed on any other maps that might exist. Applications can examine the op_scope field in the OVwObjectInfo class to see if the object is still managed on any other maps. (The op_scope value is 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. For specific examples of event handling, refer back to Event Handling Examples on page 61.

Chapter 6

199

Map Editing and Map Events Participating in Map Changes

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 is 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 notifies all objects implementing the ICallback interface that have registered for the event type to verify that the changes are acceptable. The application must have already implemented an ICallback method, called an ICallback Query method, which determines if the user changes are valid. 3. The applications ICallback "Query" callback method checks to see if the dialog box fields are valid. The application synchronously invokes an OVW method with a Boolean indication whether the dialog box fields are acceptable. The application can also return a message that is 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 method called by the application is known as a Verify method.

200

Chapter 6

Map Editing and Map Events Participating in Map Changes 4. Depending on the applications response, OVW may enable the [OK] button to allow the user to proceed. If the application does not accept 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 notifies all objects implementing the ICallback interface that have registered for this event type a confirm event, confirming that the operation was performed. The application ICallback method that receives the notification is called the ICallback Confirm method. 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) implemented both Query and Confirm callback methods on the ICallback interface. If an enroll block does not exist, OVW cannot construct the application-specific dialog box. If the callback methods are not implemented, OVW cannot communicate with the application.

Chapter 6

201

Map Editing and Map Events Participating in Map Changes 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. Figure 6-1 Query-Verify-Confirm Transactions

User Action

Responsible Application

Other Applications

User presses [Verify] or dialog box is enrolled for .automatic verification.

OVwQueryAddSymbol notification

If the fields are invalid, the user can start over. If the fields are valid and the user wants to proceed, he can press [OK]. OVW completes the operation and sends an event to the application.

Application checks if user-supplied information is valid. Application responds to OVW, setting a lag to indicate if the information is valid.

OVwVerifyAdd() invocation

Time

OVwConfirmAddSymbol notification

Application receives confirmation that the operation was completed.

OVwConfirmCreateSymbol notification

Application receives confirmation that the operation was completed.

202

Chapter 6

Map Editing and Map Events Participating in Map Changes

Query-Verify-Confirm methods
The following list contains the callback method signatures that apply for each of the four map operations. The method signatures are grouped by map operation. Adding a Symbol
public void OVwQueryAddSymbolCB(OVwMapInfo map,OVwSubmapInfo submap, OVwFieldBindList capabilityFields, OVwFieldBindList dialogBoxFields) public int OVwVerifyAdd(OVwMapInfo map, OVwFieldBindList info, int verified, int appPlane, String errorMsg) throws LibOvwException public void OVwConfirmAddSymbolCB(OVwMapInfo map, OVwSymbolInfo symbol, OVwFieldBindList capabilityFields, OVwFieldBindList dialogBoxFields)

Changing the Application Configuration

public void OVwQueryAppConfigCB(OVwMapInfo map, OVwFieldBindList configParams) public int OVwVerifyAppConfigChange(OVwMapInfo map, OVwFieldBindList configParams, int verified, String errorMsg) throws LibOvwException public void OVwConfirmAppConfigCB(OVwMapInfo map, OVwFieldBindList configParams)

Connecting Two Symbols

public void OVwQueryConnectSymbolsCB(OVwMapInfo map, OVwSubmapInfo submap, OVwObjectInfo object1, OVwObjectInfo object2, OVwFieldBindList capabilityFields, OVwFieldBindList dialogBoxFields) public int OVwVerifyConnect(OVwMapInfo map, OVwObjectInfo object1, OVwObjectInfo object2, OVwFieldBindList info, int verified, int appPlane, String errorMsg) throws LibOvwException public void OVwConfirmConnectSymbolsCB(OVwMapInfo map, OVwSymbolInfo symbol, OVwObjectInfo object1, OVwObjectInfo object2, OVwFieldBindList capabilityFields, OVwFieldBindList dialogBoxFields)

Chapter 6

203

Map Editing and Map Events Participating in Map Changes Changing the Object Description
public void OVwQueryDescribeCB (OVwMapInfo map, OVwObjectInfo object, OVwFieldBindList dialogBoxFields) public int OVwVerifyDescribeChange(OVwMapInfo map, OVwObjectInfo object, OVwFieldBindList info, int verified, String errorMsg) throws LibOvwException public void OVwConfirmDescribeCB (OVwMapInfo map, OVwObjectInfo object, OVwFieldBindList dialogBoxFields)

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 methods.

NOTE

If your application registers for any of the ICallback query methods, your application must invoke the associated OVW verify method as part of the query callback processing. Users may experience unnecessary delays if your application does not invoke the verify method as part of query event processing.

See the reference pages for the associated C functions if you need more information about these methods. The following short code segments show how to use the Query-VerifyConfirm methods. 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" { } }

204

Chapter 6

Map Editing and Map Events Participating in Map Changes

} ... }

The next code segment implements callback methods to handle editing interaction with OVW. Note that the dialog box fields are passed to the callback methods in OVwFieldBindList classes, which were described in Chapter 3, Creating and Using Objects and Fields. The fields supplied with the query and confirm notifications correspond to the fields enrolled in the application-specific dialog box.
import hp.ov.libovw.*; public class Sample1 { Libovw libovw; extends OvwEventAdapter

public void OVwQueryDescribeCB(OVwMapInfo map, OVwObjectInfo object, OVwFieldBindList dialogBoxFields) { // Check the validity of the dialog box fields. // Depending on the result, return success or failure // back to OVW. try { libovw.OVwVerifyDescribeChange(map, object, dialogBoxFields, 1, null); } catch (LibOvwException ex) { // handle the exception return; } } public void OVwConfirmDescribeCB(OVwMapInfo map, OVwObjectInfo object, OVwFieldBindList dialogBoxFields) { // Operation completed successfully; perform any // application specific operations }

Chapter 6

205

Map Editing and Map Events Participating in Map Changes

public static void main(String args[]) { Sample1 s1 = new Sample1(args[0]); // perform standard initialization ... } long mask = ovwQueryDescribeChangeMask|ovwConfirmDescribeChangeMask; int ret; try { ret = libovw.OVwAddCallback(mask, this); } catch LibOvwException ex){ // failure libovw.OVwDone(); libovw = null; System.out.println("OVwAddCallback failed!"); return; } }

Choosing Which Confirm Event to Use

As stated in previous sections in this chapter, applications can receive confirmation of the Add or Connect map-editing operations in not one, but two ways. Applications can register for the specific OVwEvents.ovwConfirmAddSymbol or OVwEvents.ovwConfirmConnectSymbol events that correspond to the Query-Verify-Confirm methods, or they can register for the more generic OVwEvents.ovwConfirmCreateSymbols event. For example, an application that wants to receive notification that a symbol has been added to a submap can register either the ICallback.OVwConfirmAddSymbolCB() callback method or the ICallback.OVwConfirmCreateSymbolsCB() callback method. They are invoked through different events, with different method signatures and arguments. Your choice of which confirm event to use is largely based on: 206 the way the symbol is created the arguments that are supplied to the callback methods Chapter 6

Map Editing and Map Events Participating in Map Changes The generic OVwEvents.ovwConfirmCreateSymbols event is generated regardless of how the symbol is created (by the user through the user interface or by another application through the Java libovw API). The same event is generated when either an icon or connection symbol is added. In contrast, the OVwEvents.ovwConfirmAddSymbol and OVwEvents.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 OVwEvents.ovwConfirmCreateSymbols event can be associated with the creation of multiple symbols. The OVwEvents.ovwConfirmAddSymbol and OVwEvents.ovwConfirmConnectSymbol events are associated with a single symbol. The data returned to the callback methods differ between the generic OVwEvents.ovwConfirmCreateSymbols event and the specific OVwEvents.ovwConfirmAddSymbol and OVwEvents.ovwConfirmConnectSymbol events. For example, compare the two method signatures below:
public void OVwConfirmAddSymbolCB(OVwMapInfo map, OVwSymbolInfo symbol, OVwFieldBindList capabilityFields, OVwFieldBindList dialogBoxFields) public void OVwConfirmCreateSymbolsCB(OVwMapInfo map, OVwSymbolList symbolList)

The arguments to the OVwConfirmAddSymbolCB() callback method provide complete, detailed information about the single symbol affected by the operation. The callback method also receives the complete list of object database fields enrolled by the calling application. On the other hand, the more generic ICallback.OVwConfirmCreateSymbolsCB() method contains a symbol list, which the application must traverse to inquire about the affected symbols. The generic OVwConfirmCreateSymbolsCB() method 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 6-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 OVwEvents.ovwConfirmAddSymbols event, while a second application received the OVwEvents.ovwConfirmCreateSymbols event.

Chapter 6

207

Map Editing and Map Events Participating in Map Changes Each of those two applications might have been designed to receive the other Confirm event, provided that the callback method 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 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 OVwEvents.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 methods have the following method signatures:
public void OVwQueryDeleteSymbolsCB(OVwMapInfo map, OVwSymbolVerifyList symbolVerifyList) public int OVwVerifyDeleteSymbol(OVwMapInfo map, OVwSymbolVerifyList symbolVerifyList) throws LibOvwException public void OVwConfirmDeleteSymbolsCB(OVwMapInfo map, OVwSymbolList symbolList)

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.

208

Chapter 6

Map Editing and Map Events 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 waits 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 method is used to return to OVW your applications response to a user locate query. This single method is used to return results for all locate queries.
public int OVwReturnLocateResults(OVwMapInfo map, int requestId, String errorMessage, OVwLocateResultList list) throws LibOvwException

Your application should invoke this with an OVwLocateResultList that contains the objects resulting from users locate query. The code below provides an example for the use of the OVwReturnLocateResults() method:
import java.applet.Applet; import hp.ov.libovw.*; public class MyLocater extends java.applet.Applet { LibOvw libovw; String session; MyAdapter adapter; public MyLocater () { }

Chapter 6

209

Map Editing and Map Events Participating in Map Locates In Transient Map Applications

public void init() { libovw = new LibOvw(); session = getParameter("OvwSessionID"); try { lib.OVwInitSession("VerifyApis", session); } catch (LibOvwException ex) { // failed to connect return; } long eventMask = OVwEvents.ovwAttributeLocateMask | OVwEvents.ovwSymbolStatusLocateMask | OVwEvents.ovwSymbolTypeLocateMask | OVwEvents.ovwSymbolLabelLocateMask; adapter = new MyAdapter(); int ret; try { ret = lib.OVwAddCallback(eventMask, adapter); } catch (LibOvwException ex) { // failed to add self as notification handler libovw.OVwDone(); libovw = null; System.out.println("MyLocater: addCallback failed!"); return; } } // define inner class to allow use of OVwEventAdapter class MyAdapter extends OVwEventAdapter { public void OVwAttributeLocateCB(OVwMapInfo map, int requestId, OVwObjectIdList objects) { doLocate(map, requestId, objects, -1, null, null); } public void OVwSymbolStatusLocateCB(OVwMapInfo map, int requestId, int searchVal){ doLocate(map, requestId, null, searchVal, null, null); } public void OVwSymbolTypeLocateCB(OVwMapInfo map, int requestId, String searchVal) { doLocate(map, requestId, null, -1, searchVal, null);

210

Chapter 6

Map Editing and Map Events Participating in Map Locates In Transient Map Applications
} public void OVwSymbolLabelLocateCB(OVwMapInfo map, int requestId, String searchVal) { doLocate(map, requestId, null, -1, null, searchVal); } } // A real application performs some matching based on // type. This one simply selects the same object protected void doLocate(OVwMapInfo map, int requestId, OVwObjectIdList objList, int status, String type, String label) { OVwLocateResultList list = new OVwLocateResultList(); list.count = 1; list.items = new OVwLocateResultObject[list.count]; list.items[0] = new OVwLocateResultObject(); list.items[0].object_id = 1; list.items[0].submap_parent_id = 1; int ret; try { ret = libovw.OVwReturnLocateResults(map, requestId, null, null); } catch (LibOvwException ex) { System.out.println ("MyLocater.OVwReturnLocateResults(FAILED)"); return; } } }

Each callback provides information specific to the kind of locate operation the user has performed. The following table shows what information about the locate query the callback receives and what OVW

Chapter 6

211

Map Editing and Map Events Participating in Map Locates In Transient Map Applications expects your application to return. Refer to the software developer kit reference pages for each specific callback type for more detail on the callback functionality. Table 6-2 Locate Query Method Information Method OVwAttributeLocateCB() Information Received List of all object ids of objects in the object database matching the user query. The status value of symbols for which the user is searching. The name of the symbol type for which the user is searching. The label of the symbol for which the user is searching. Information Returned That subset of objects from the supplied list which your application places on the map. A list of objects which has a symbol on the map matching the queried status. A list of objects which has a symbol on the map of the specified symbol type. The list of objects which has a symbol on the map with the specified symbol label.

OVwSymbolStatusLocateCB()

OVwSymbolTypeLocateCB()

OVwSymbolLabelLocateCB()

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() methods return a list of symbol or object locations that match the search criteria.

212

Chapter 6

Map Editing and Map Events 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 OVwEvents.ovwConfirmCreateSubmaps event), and should deal correctly with the submap being destroyed (the OVwEvents.ovwConfirmDeleteSubmaps event). The application should be prepared to deal with these events over and over, since submaps are 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 methods return submaps and objects that currently exist on the map, not the complete set of submaps and objects that may 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.

Chapter 6

213

Map Editing and Map Events Managing Objects

Managing Objects
OVW provides several methods 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 invocations are not recursive; that is, they do not manage or unmanage objects contained in the child submap of an object managed via these invocations. The method signatures for OVwManageObject() and OVwManageObjects() are:
public int OVwManageObject(OVwMapInfo map, int objectId) throws LibOvwException public int OVwManageObjects(OVwMapInfo map, OVwObjectManageList objectList) throws LibOvwException

When invoking OVwManageObject() and OVwManageObjects(), you need to supply the following arguments: map contains map information for an open map. The map parameter can be obtained using OVwGetMapInfo(). objectLists is a list of the objectIDs of the objects to manage.

Use OVwUnmanageObject() and OVwUnmanageObjects() to unmanage the managed objects.

214

Chapter 6

Map Editing and Map Events Cut and Paste Operations

Cut and Paste Operations

Applications can receive various notifications when users perform cut and paste operations through the OVW user interface. Applications receive notifications for the following events through the ICallback interface: OVwEvents.ovwQueryDeleteSymbolsCB and OVwEvents.ovwConfirmCreateSymbolsCB with the eventSource argument set to either OVwEvents.ovwEventSourceUserCut or OVwEvents.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 applications that have implemented the appropriate callback methods of the ICallback interface. The eventSource is set to OVwEvents.ovwEventSourceUserCut. Depending on how the applications respond in their verify invocations, the symbol may or may not be deleted. When the symbol is pasted, OVW sends an OVwEvents.ovwConfirmCreateSymbols event with an event source of OVwEvents.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 invoking the OVwSetSymbolApp() Java libovw API method. An application that receives notification for an OVwEvents.ovwConfirmDeleteSymbols event with the event source set to OVwEvents.ovwEventSourceUserCut must buffer information about the deleted symbol. The information might be needed later for a subsequent notification regarding an OVwEvents.ovwConfirmCreateSymbols event with the event source of OVwEvents.ovwEventSourceUserPaste. Not all applications 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

Chapter 6

215

Map Editing and Map Events Cut and Paste Operations 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 want to buffer at least the object ID. OVW sends a notification when an OVwEvents.ovwConfirmCreateSymbols event is sent with an event source of OVwEvents.ovwEventSourceUserPaste. Your application 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.

216

Chapter 6

Map Editing and Map Events Customizing Drag and Drop Operations for HP-UX, Solaris, and Linux Applications

Customizing Drag and Drop Operations for HP-UX, Solaris, and Linux 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 symbols on the child submap of the explodable symbols. A successful drop does not guarantee that the symbols are 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 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 symbols. 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 permits 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.

Chapter 6

217

Map Editing and Map Events Customizing Drag and Drop Operations for HP-UX, Solaris, and Linux Applications 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 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 215). 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 window 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 submap window. Drag and Drop and Non-Persistent Submaps Users receive ample feedback about the legitimacy of the dropsite while dragging symbols within a submap or between submaps. This feedback is provided by a change to the cursor and indicates that the drop target being considered is invalid. Symbols with no existing child submap are considered invalid drop targets, and the user is given this feedback when dragging another symbol over the childless symbol. In the case of non-persistent child submaps, OVW queries applications that control symbols that are being dragged over. This is done by invoking the OVwUserSubmapCreateCB() callback or the OVwUserEventSubmapCreateCB() callback. OVW does this query so that 218 Chapter 6

Map Editing and Map Events Customizing Drag and Drop Operations for HP-UX, Solaris, and Linux Applications applications that create submaps on demand may do so while the drag operation is happening or may simply look at the event source passed as a parameter, NOT create a submap, and return a null as the submap id. 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 the online manual, Creating and Using Registration Files. 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 is rejected. Remember that symbol selection for drag sources is limited to a single submap. 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 is 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.

Chapter 6

219

Map Editing and Map Events Customizing Drag and Drop Operations for HP-UX, Solaris, and Linux Applications 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 drop_action 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. 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 is 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.

220

Chapter 6

Map Editing and Map Events Customizing Drag and Drop Operations for HP-UX, Solaris, and Linux Applications 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 explains the result of the drop. Application Control of Help An application must provide help text for any drop targets that it controls. If a drop is invalid, the help dialog box needs to 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. 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 the online manual, Creating and Using Registration Files. Drop action configuration includes: The drop operations 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 Java libovw API. This step makes the symbol or submap a drop target. See Assigning a Drop Action To a Drop Target on page 222. 3. Associate a drop action with an application callback method using the libovw API. This callback implements the semantic behavior for a successful drop, and is also responsible for invoking LibOvw.OVwVerifyDrop() to return the result. This callback is invoked when the end user performs a drop onto a target associated Chapter 6 221

Map Editing and Map Events Customizing Drag and Drop Operations for HP-UX, Solaris, and Linux Applications with the given drop action. This is described in Associating a Drop Action with an Application Callback on page 222. If the behavior cannot be carried out for any reason, a notification must be sent to the user via the LibOvw.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 classes each contain two fields that must be modified when a drop action is assigned:
String drop_action String drop_app_name

To modify the drop_action and drop_app_name fields, call OVwGetSymbolInfo() to get the OVwSymbolInfo class (or OVwGetSubmapInfo() to get the OVwSubmapInfo class). 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 class is:
ovwUpdateSymbolDropAction

The update flag for the OVwSubmapInfo class is:

ovwUpdateSubmapDropAction

Associating a Drop Action with an Application Callback

OVwAddDropCallback() from the ICallback package associates a notification with a particular drop action defined in an application registration file. This configures OVW to invoke the callback method when the drop action event occurs (that is, when the end user performs a drop on the registered drop target). The method signature is:
public int OVwAddDropCallback(String drop_action, ICallback cb) throws LibOvwException

222

Chapter 6

Map Editing and Map Events Customizing Drag and Drop Operations for HP-UX, Solaris, and Linux Applications 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. cb is the applications callback routine that controls the drop behavior.

The association between a DropAction and a callback may be severed by calling the API function LibOvw.OVwRemoveDropCallback(), which has a method signature as shown below:
public int OVwRemoveDropCallback(String drop_action) throws LibOvwException

Application Drop Callback Invocation

The drop callback is invoked when OVW recognizes that a drop is 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 ICallback.OVwDropCB() callback method has the following signature:

public void OVwDropCB(String drop_action, OVwSymbolIdList dragged_symbs, int droptarget_submap, int droptarget_symbol, int operation, OVwMapInfo map, int drop_id);

The parameters include: drop_action is the DropAction defined in the application registration file. dragged_symbs 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.

Chapter 6

223

Map Editing and Map Events Customizing Drag and Drop Operations for HP-UX, Solaris, and Linux Applications droptarget_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 is 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 is 0. operation identifies the drop operation: OpMove or OpCopy. One or both of these can be specified as allowed. If an operation is attempted that is not allowed, the user receives feedback that the operation is not allowed. map identifies the OVW map that the drop occurred in. drop_id identifies this particular drop 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 method may choose to handle the individual symbols in the dragged_symbs 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 LibOvw.OVwVerifyDrop(). This is required so OVW knows whether the drop succeeded. If the drop failed, the application must return an error message to tell the user what went wrong. The LibOvw.OVwVerifyDrop() method has the following signature:
public int OVwVerifyDrop (int drop_id, boolean succes, String errorMsg) throws LibOvwException

The arguments to OVwVerifyDrop() are: 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.

224

Chapter 6

Map Editing and Map Events Customizing Drag and Drop Operations for HP-UX, Solaris, and Linux Applications error_msg is a string that is displayed in an error dialog if the drop fails. It should provide clear feedback so the user understands the cause of the failure.

Chapter 6

225

Map Editing and Map Events Summary

Summary
This chapter described OVW map editing. Applications that need to be notified of map changes can implement methods of the ICallback interface. Table 6-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 implement methods of the ICallback interface 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 method 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 method 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 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.

226

Chapter 6

Developing Internationalized and Localized Applications

Chapter 7

227

Developing Internationalized and Localized Applications Overview

Overview
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 Java applications. discusses special considerations for Java applications written within HP OpenView Windows 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. Chapter 8 explains internationalization and localization information for Web-based applications and applets. This chapter does not explain general guidelines for designing or developing internationalized or localized software.For more information on these subjects refer to these books: McFarland, Thomas C.; X Windows On The World: Developing Internationalized Software with X, Motif and CDE, Prentice Hall PTR, New Jersey, 1996. ISBN 0-13-359787-3 ODonnell, Sandra Martin; Programming for the World: A Guide to Internationalization, Prentice Hall PTR, New Jersey, 1994. ISBN 0-13-722190-8

228

Chapter 7

Developing Internationalized and Localized Applications Internationalization

Internationalization
To produce software for multiple countries, the software must be designed to support the 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. 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. Java supports internationalization of code by providing the Locale, ResourceBundle, DateFormat, NumberFormat, and Collator classes, among others. It also inherently supports Unicode as a means of providing text that can represent data from many locales. Any program that needs to run under multiple locales should make use of the MessageBundle class to extricate locale-specific information from the program itself. The methods for performing internationalization within Java programs are well-documented. See the Internationalization trail in the online Java Tutorial at Suns java.sun.com web site for further details.

Chapter 7

229

Developing Internationalized and Localized Applications 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. It is the responsibility of Java applets and applications to ensure they interact appropriately with the HP OpenView Windows products through correct initialization of the Java LibOvw API. This is performed by passing the appropriate encoding arguments to the LibOvw constructor, as described in The OVW Programming Model and Java on page 37. Applets and applications alike may need to modify behavior (perhaps by loading a different ResourceBundle) depending on the locale. An integrated applet should make use of the Session class to correctly identify the locale in which it is running:
Session s = new Session(this); Locale l = s.getLocale(); String language = l.getLanguage();

See Chapter 8, Integrating Your Application with the HP OpenView Web, for further information on this topic. Applications may determine the locale from their runtime environment through the Locale class as follows:
import java.util.Locale; ... Locale l = Locale.getDefault(); String language = l.getLanguage();

230

Chapter 7

Developing Internationalized and Localized Applications Localization The language returned by both of the examples above may be used to determine which resources to use when modifying symbols, creating submap and symbol names, and so on.

Chapter 7

231

Developing Internationalized and Localized Applications 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 run-time, 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.

232

Chapter 7

Developing Internationalized and Localized Applications 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, for 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) based locales.

Chapter 7

233

Developing Internationalized and Localized Applications 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 two strings, one for the internal name that is guaranteed to be the same across all locales and one for the display name that is localizable.

234

Chapter 7

Developing Internationalized and Localized Applications Developing Internationalized and Localized HP OpenView Windows 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. The English version of the registration file should be stored under the install_dir\registration\C directory (Windows) or under the /etc/opt/OV/share/registration/C (UNIX) directory.

NOTE

In this chapter, $OV_REGISTRATION is used to refer to the directory containing registration files on either Windows or on HP-UX, Solaris, and Linux.

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 loads the language-specific version of the application registration file from the $OV_REGISTRATION/locale name directory, if it exists, and ignores the files under the $OV_REGISTRATION/C directory. If the language-specific version of the application registration file does not exist, OVW loads the registration file from $OV_REGISTRATION/C directory.

Chapter 7

235

Developing Internationalized and Localized Applications Developing Internationalized and Localized HP OpenView Windows Applications 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 do 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 does not appear under the localized version of the Misc menu. Instead the reference to MenuBar Misc (in English) causes OVW to create a second Misc menu and integrates 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 end-user that such menus appear under an English menu bar name. In

236

Chapter 7

Developing Internationalized and Localized Applications Developing Internationalized and Localized HP OpenView Windows Applications any case, if the developer wants to integrate the menu items of the non-localized application (such as My menu item) with the localized menu bars, the developer needs to supply a partially localized application 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 integrates 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. The online manual, Creating and Using Registration Files, provides detailed descriptions and examples of the components of registration files. Application Registration Files OVW application registration files provide the following localizable strings:

Chapter 7

237

Developing Internationalized and Localized Applications Developing Internationalized and Localized HP OpenView Windows Applications 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 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 the online manual, Creating and Using Registration Files. 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 the online manual, Creating and Using Registration Files, 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.

238

Chapter 7

Developing Internationalized and Localized Applications Developing Internationalized and Localized HP OpenView Windows Applications

OVwSymbolType Argument
When an application needs to specify the OVwSymbolType type argument to call the various Java libovw 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:
... LibOvw libovw = new LibOvw(); // session initialization omitted for brevity OVwMapInfo map; try { map = libovw.OVwGetMapInfo(); } catch (LibOvwException ex) { // handle the exception return; } int symid; int objectId; ... try { symid = libovw.OVwCreateSymbol(map, map.root_submap_id, objectId, "Computer:Workstation", "test", OVwSymbolInfo.ovwUnknownStatus, OVwSymbolInfo.ovwSymbolStatusSource, null, OVwSymbolInfo.ovwNoSymbolFlags); } catch (LibOvwException ex) { // handle the exception return; } ...

Here, "Computer:Workstation" is the non-localizable string defined in the Java code.

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.

Chapter 7

239

Developing Internationalized and Localized Applications Developing Internationalized and Localized HP OpenView Windows 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 an application is 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 is 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 still displays its strings in English, but the strings from the localized application are in French. If a user starts up OVW in English language mode, both the user interface and the localized applications user interface display English strings.

240

Chapter 7

Developing Internationalized and Localized Applications 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 applications are expected to run on non-English versions of Windows systems. 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.

Chapter 7

241

Developing Internationalized and Localized Applications Warnings for Non-Internationalized Applications 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 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.

242

Chapter 7

Developing Internationalized and Localized Applications 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.

Chapter 7

243

Developing Internationalized and Localized Applications Summary

244

Chapter 7

Integrating Your Application with the HP OpenView Web

Chapter 8

245

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 Network. 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, and know what APIs are available to you to access session information.

246

Chapter 8

Integrating Your Application with the HP OpenView Web 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 install_dir\www\conf\session.conf on Windows or /etc/opt/OV/share/www/conf/session.conf on UNIX. Security is set up via several configuration files: the user password file:install_dir\www\etc\htpasswd on Windows or /etc/opt/OV/share/www/etc/htpasswd on UNIX. the user roles file: install_dir\www\etc\htgroup on Windows or /etc/opt/OV/share/www/etc/htgroup on UNIX. the session configuration file: install_dir\www\conf\session.conf on Windows or /etc/opt/OV/share/www/conf/sesson.conf on UNIX.

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,

Chapter 8

247

Integrating Your Application with the HP OpenView Web Model of Operation 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 8-1 Services and Files for the Web Components

Network Presenter

SNMP Data Presenter

Web Launcher

Alarm Browser

Web Browser OVW Server

httpd ovw ovalarmsrv

ovwdb

CGI Programs pmd locale mapping files ovsessionmgr.exe Event database

Map database

Object database

config. files

configuration file background process

application, foreground service database

If the session times out and the user logs back in with different values, the application is not notified of this. The application continues running with the old values. 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 bring down the Browser and connect to a different server.

248

Chapter 8

Integrating Your Application with the HP OpenView Web Model of Operation 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 install_dir\www\conf\session.conf file on Windows or the /etc/opt/OV/share/www/conf/session.conf file on UNIX. If the session times out, the user is 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 browser accessing the server must be brought down and brought back up again in order to start a new session.

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 8-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 8-1 lists the NNM Web UI CGI programs. Many of the CGI programs have parameters, which are listed in the reference page OvWebURLIntro(5). Table 8-1 Program jovw.exe Starts Network Presenter. NNM Web CGI Programs Description

Chapter 8

249

Integrating Your Application with the HP OpenView Web Model of Operation Table 8-1 Program jovwreg.exe NNM Web CGI Programs (Continued) Description 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. The graph tool used by SNMP Data Presenter. Launches the SNMP Data Presenter, or displays textual or graphical results of SNMP monitoring operations on a browser. Application encapsulator used by SNMP Data Presenter. Reads the Web Launcher registration files (WLRFs), passing input to the Launcher window for display. Launches the Launcher and opens the user login screen, when UserLogin is set. Processes the user login screen. Should not be called as a standalone URL. Collects session information from the ongoing session. Launches the Alarm Browser user interface. Tool for accessing NNM data stores via read-only http queries. The NNM Help CGIs. Browser-callable URL to present user session information.

jovgraph.exe snmpviewer.exe webappmon.exe ovlaunchreg.exe ovlaunch.exe ovlogin.exe ovsessioninfo.exe ovalarm.exe ovwebdata.exe OvWebHelp.exe printsession.exe

250

Chapter 8

Integrating Your Application with the HP OpenView Web Application Configuration and Integration

Application Configuration and Integration

The Launcher provides top-level user-interface integration of HP OpenView Web user interfaces. Table 8-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 Windows systems. 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 is executed from the Launcher. This information is provided in Managing Your Network 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 8

251

Integrating Your Application with the HP OpenView Web Application Configuration and Integration The following table shows the integration points that are available to administrators and to developers. Table 8-2 OV Web Launcher Configuration and Integration Points File UNIX systems Definition: /etc/opt/OV/www/etc/htpasswd On/off :/etc/opt/OV/share/www/conf/session.conf Windows systems Definition: install_dir\www\etc\htpasswd On/off: install_dir\www\conf\session.conf authorization UNIX systems Definition: /etc/opt/OV/www/etc/htgroup On/off: /etc/opt/OV/share/www/conf/session.conf Windows systems Definition: install_dir\www\etc\htgroup On/off: install_dir\www\conf\session.conf 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 Windows systems Definition: install_dir\www\logs\launcher\login_log Definition: install_dir\www\logs\launcher\access_log On/off: install_dir\www\conf\session.conf session timeout UNIX systems /etc/opt/OV/share/www/conf/session.conf Windows systems

Configuration or Integration Point authentication

install_dir\www\conf\session.conf

252

Chapter 8

Integrating Your Application with the HP OpenView Web Application Configuration and Integration Table 8-2 OV Web Launcher Configuration and Integration Points (Continued) File UNIX systems /opt/OV/bin/ovchange_locale_mapping Windows systems Not available installed locale UNIX systems /etc/opt/OV/share/www/conf/locales.installed Windows systems

Configuration or Integration Point locale mapping

install_dir\www\conf\locales.installed
parameter configuration UNIX systems /opt/OV/www/htdocs/$LANG/nnm/launcher/browser.html Windows systems

install_dir\www\htdocs\%LANG%\nnm\launcher\browser.html
application integration into the Launcher UNIX systems /etc/opt/OV/share/www/registration/launcher/<LANG> Windows systems

install_dir\www\registration\launcher\%LANG%
application integration into Network Presenter UNIX systems /etc/opt/OV/share/www/registration/jovw/<LANG> Windows systems

install_dir\www\registration\jovw\%LANG%

Chapter 8

253

Integrating Your Application with the HP OpenView Web Application Configuration and Integration

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.

254

Chapter 8

Integrating Your Application with the HP OpenView Web Application Configuration and Integration The session APIs are provided in a Java class and in a set of CGI APIs. For Java programs, the package hp.ov.session defines the classes and interfaces used in the class Session. See Connecting Applications to HP OpenView Windows on page 50 for more information about the Session API. 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 8

255

Integrating Your Application with the HP OpenView Web Application Configuration and Integration 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()

256

Chapter 8

Integrating Your Application with the HP OpenView Web Application Configuration and Integration OVwwwIsLoginEnabled()checks in /etc/opt/OV/share/www/conf/session.conf on UNIX or install_dir\www\conf\session.conf on Windows 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 or install_dir\www\etc\htgroup on Windows to determine whether a user has particular role. It 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 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 Chapter 8 257

Integrating Your Application with the HP OpenView Web Application Configuration and Integration 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 to initialize the encoding argument for the LibOvw(String encoding) constructor, and for converting characters to Unicode with the InputStreamReader class for the current Launcher session, as in InputStreamReader (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.

258

Chapter 8

Integrating Your Application with the HP OpenView Web Application Configuration and Integration 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 C OVwwwGetOSLocale() returns a string containing the platform-dependent OS locale for the current Launcher session. Its function prototype is:
char *OVwwwGetOSLocale()

OVwwwGetWebLocale()returns a string containing the platform-independent web locale specified in the files in /etc/opt/OV/www/conf/ on UNIX or in install_dir\www\conf\ on Windows. It returns en-US if the session is not valid. The function prototype for OVwwwGetWebLocale() is:
char *OVwwwGetWebLocale()

Chapter 8

259

Integrating Your Application with the HP OpenView Web Application Configuration and Integration

260

Chapter 8

Guidelines for Documenting Map Applications

Appendix A

261

Guidelines for Documenting Map Applications Overview

Overview
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 or reference page for an example of how HP documents the IP Map application. The guidelines for documenting each of these elements are described next.

262

Appendix A

Guidelines for Documenting Map Applications 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 (for example, enable or disable application functionality)

Appendix A

263

Guidelines for Documenting Map Applications Registration Files

Registration Files
Because 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.

264

Appendix A

Guidelines for Documenting Map Applications 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 (for example., 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

265

Guidelines for Documenting Map Applications 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

266

Appendix A

Guidelines for Documenting Map Applications 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

267

Guidelines for Documenting Map Applications 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.

268

Appendix A

Guidelines for Documenting Map Applications Dependencies on other Map Applications

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 happens if those dependencies are not met.

Appendix A

269

Guidelines for Documenting Map Applications Dependencies on other Map Applications

270

Appendix A

An Example Applet

Appendix B

271

An Example Applet Overview

Overview
This chapter contains a partial example that demonstrates many of the key concepts presented throughout this manual. The example application demonstrates the use of the Java bindings for the OVw and OVwDb APIs, Java libovw API, as used in an applet. The example is available electronically in: /opt/OV/www/htdocs/C/java_libovw/sample (UNIX)

install_dir\www\htdocs\C\java_libovw\sample (Windows)

272

Appendix B

An Example Applet Instructions for Sample Application

Instructions for Sample Application

Follow the instructions below to run the sample application for the Java libovw API: 1. Make the directory /OvDocs/C/nnm/test, then copy the TestApi.html file to that directory. 2. Edit the TestApi.html file by changing the system_running_ovw variable to the actual system name. 3. Set the permissions on the directory to: dr-xr-xr-x 2 bin bin 4. Set the permissions on the .html file to: -r-xr-xr-x 1 bin bin 5. Make the directory /OvDocs/classes/test. 6. Build the TestApi.class file from the TestApi.java file, then copy the TestApi.class file to that directory. 7. Set the permissions on the directory to: dr-xr-xr-x 2 bin bin 8. Set the permissions on the .class file to: -r-xr-xr-x 1 bin bin 9. Copy the TestApi.reg file to $OVwRegDir, then restart OVW so that OVW allows the applet to connect. 10. Point a Java-enabled web browser to the .html file. 11. Output from the applet is displayed in the web browser's Java console window.

Appendix B

273

An Example Applet Example

Example
package test; import java.applet.Applet; import hp.ov.libovw.*; public class TestApi extends java.applet.Applet implements ICallback { public TestApi() { } public void init() { System.out.println("In TestApi"); LibOvw libovw = new LibOvw(); String session = getParameter ("OVSession"); try { libovw.OVwInitSession("TestApi", session); System.out.println ("successfully connected to ovw"); } catch (LibOvwException ex) { System.out.println ("exception is " + ex.getError() + " " + ex.toString()); } // add callback long mask = OVwEvents.ovwConfirmCreateSubmapsMask OVwEvents.ovwConfirmDeleteSubmapsMask OVwEvents.ovwEndSessionMask | OVwEvents.ovwMapOpenMask | OVwEvents.ovwMapCloseMask | OVwEvents.ovwConfirmDeleteSymbolsMask OVwEvents.ovwConfirmCreateSymbolsMask OVwEvents.ovwSymbolChangeMask | OVwEvents.ovwConfirmMoveSymbolMask | OVwEvents.ovwSubmapChangeMask; | |

| |

try { libovw.OVwAddCallback(mask, this); System.out.println ("successfully added callbacks"); }

274

Appendix B

An Example Applet Example

catch (LibOvwException ex) { System.out.println ("exception is " + ex.getError() + " " + ex.toString()); } OVwMapInfo map; try { map = libovw.OVwGetMapInfo(); System.out.println("Got map: " + map.map_name); catch (LibOvwException ex) { System.out.println ("exception is " + ex.getError() + " " + ex.toString()); } OVwSubmapInfo submap; try { submap = libovw.OVwGetSubmapInfo(map, 1); System.out.println("Got submap: " + submap.submap_name); } catch (LibOvwException ex) { System.out.println ("exception is " + ex.getError() + " " + ex.toString()); } OVwSymbolList syms; try { syms = libovw.OVwListSymbols(map, 1 OVwSymbolInfo.ovwAllPlanes, null); } catch (LibOvwException ex) { System.out.println ("exception is " + ex.getError() + " " + ex.toString()); } int sub; try { sub = libovw.OVwCreateSubmap(map, 0, 1, 1, "My Submap", 1, 0); System.out.println("Created submap: " + sub); } catch (LibOvwException ex) { System.out.println ("exception is " + ex.getError() + " " + ex.toString()); } try { submap = libovw.OVwGetSubmapInfo(map, sub); System.out.println("Got submap: " + submap.submap_name);

Appendix B

275

An Example Applet Example

} catch (LibOvwException ex) { System.out.println ("exception is " + ex.getError() + " " + ex.toString()); } try { libovw.OVwDeleteSubmap(map, sub); System.out.println("Deleted submap"); } catch (LibOvwException ex) { System.out.println ("exception is " + ex.getError() + " " + ex.toString()); } OVwSymbolInfo sym; try { sym = libovw.OVwGetSymbolInfo(map, 1); System.out.println("Got symbol: " + sym.symbol_label); } catch (LibOvwException ex) { System.out.println ("exception is " + ex.getError() + " " + ex.toString()); } int objid; try { objid = libovw.OVwDbCreateObjectBySelectionName("test"); System.out.println("Created Object: " + objid); } catch (LibOvwException ex) { System.out.println ("exception is " + ex.getError() + " " + ex.toString()); } OVwSymbolCreateList symlist = new OVwSymbolCreateList(); symlist.count = 1; symlist.symbols = new OVwSymbolCreateInfo[1]; symlist.symbols[0] = new OVwSymbolCreateInfo(); symlist.symbols[0].submap_name_style = OVwSymbolCreateInfo.ovwSubmapIdValue; symlist.symbols[0].id = 3; symlist.symbols[0].object_name_style = OVwSymbolCreateInfo.ovwObjectIdValue; symlist.symbols[0].object_id = objid; symlist.symbols[0].label = "jovw created this"; symlist.symbols[0].status = 1;

276

Appendix B

An Example Applet Example

symlist.symbols[0].status_source = 1; symlist.symbols[0].symbol_type = "Network:Bus"; symlist.symbols[0].symbol_variety = OVwSymbolInfo.ovwIconSymbol; symlist.symbols[0].position = null; try { libovw.OVwCreateSymbols(map, symlist); System.out.println("Created symbol: " + symlist.symbols[0].symbol_id); } catch (LibOvwException ex) { System.out.println ("exception is " + ex.getError() + " " + ex.toString()); } OVwSymbolIdList symids = new OVwSymbolIdList(); symids.count = 1; symids.symbol_ids = new int[1]; symids.symbol_ids[0] = symlist.symbols[0].symbol_id; try { libovw.OVwDeleteSymbols(map, symids); System.out.println ("successfully deleted symbol"); } catch (LibOvwException ex) { System.out.println ("exception is " + ex.getError() + " " + ex.toString()); } try { libovw.OVwDbUnsetFieldValue (objid, libovw.OVwDbFieldNameToFieldId("Selection Name")); } catch (LibOvwException ex) { System.out.println ("exception is " + ex.getError() + " " + ex.toString()); } try { libovw.OVwDbDeleteObject(objid); System.out.println ("successfully deleted object"); }

Appendix B

277

An Example Applet Example

catch (LibOvwException ex) { System.out.println ("exception is " + ex.getError() + " " + ex.toString()); } libovw.OVwDone(); } public void OVwEndSessionCB(boolean normalEnd) { } public void OVwMapOpenCB(OVwMapInfo map, OVwFieldBindList configParams, int eventSource) { } public void OVwMapCloseCB(OVwMapInfo map, int closeTime, int eventSource){ } public void OVwConfirmDeleteSymbolsCB(OVwMapInfo map,OVwSymbolList symbolList, int eventSource) { } public void OVwConfirmDeleteSubmapsCB(OVwMapInfo map, OVwSubmapList submapList, int eventSource) { } public void OVwConfirmCreateSymbolsCB(OVwMapInfo map, OVwSymbolList symbolList, int eventSource) { } public void OVwConfirmCreateSubmapsCB(OVwMapInfo map, OVwSubmapList submapList, int eventSource) { } public void OVwSubmapChangeCB(OVwMapInfo map, OVwSubmapUpdateList submaps, int eventSource){ } public void OVwSymbolChangeCB(OVwMapInfo map, OVwSymbolUpdateList symbols, int eventSource){ } public void OVwConfirmMoveSymbolCB(OVwMapInfo map, OVwSymbolInfo symbol, int eventSource) { } public void OVwSelectListChangeCB(OVwMapInfo map){ } public void OVwQueryAppConfigChangeCB(OVwMapInfo map, OVwFieldBindList configParams){ } public void OVwConfirmAppConfigChangeCB(OVwMapInfo map, OVwFieldBindList configParams){ } public void OVwQueryDescribeChangeCB(OVwMapInfo map, OVwObjectInfo object,OVwFieldBindList dialogBoxFields){

278

Appendix B

An Example Applet Example

} public void OVwConfirmDescribeChangeCB(OVwMapInfo map, OVwObjectInfo object, OVwFieldBindList dialogBoxFields){ } public void OVwQueryAddSymbolCB(OVwMapInfo map, OVwSubmapInfo submap,OVwFieldBindList capabilityFields, OVwFieldBindList dialogBoxFields){ } public void OVwConfirmAddSymbolCB(OVwMapInfo map, OVwSymbolInfo symbol,OVwFieldBindList capabilityFields, OVwFieldBindList dialogBoxFields){ } public void OVwQueryConnectSymbolsCB(OVwMapInfo map, OVwSubmapInfo submap, OVwObjectInfo object1, OVwObjectInfo object2, OVwFieldBindList capabilityFields, OVwFieldBindList dialogBoxFields){ } public void OVwConfirmConnectSymbolsCB(OVwMapInfo map, OVwSymbolInfo symbol, OVwObjectInfo object1, OVwObjectInfo object2, OVwFieldBindList capabilityFields,OVwFieldBindList dialogBoxFields){ } public void OVwConfirmDeleteSymbolAlertCB(OVwMapInfo map, OVwSymbolInfo symbol){ } public void OVwQueryDeleteSymbolsCB(OVwMapInfo map, OVwSymbolVerifyList symbolVerifyList){ } public void OVwConfirmDeleteObjectsCB(OVwMapInfo map, OVwObjectList objectList){ } public void OVwConfirmCreateObjectsCB(OVwMapInfo map, OVwObjectList objectList){ } public void OVwConfirmManageObjectsCB(OVwMapInfo map, OVwObjectList objectList){ } public void OVwConfirmUnmanageObjectsCB(OVwMapInfo map, OVwObjectList objectList){ } public void OVwConfirmHideSymbolsCB(OVwMapInfo map, OVwSymbolList symbolList) { } public void OVwConfirmUnhideSymbolsCB(OVwMapInfo map, OVwSymbolList symbolList){

Appendix B

279

An Example Applet Example

} public void OVwConfirmSymbolStatusChangeCB(OVwMapInfo map, OVwSymbolList symbolList){ } public void OVwConfirmObjectStatusChangeCB(OVwMapInfo map,OVwObjectList objectList){ } public void OVwConfirmCompoundStatusChangeCB(OVwMapInfo map, OVwObjectList objectList){ } public void OVwConfirmCapabilityChangeCB(OVwMapInfo map,OVwObjectList objectList){ } public void OVwUserSubmapCreateCB(OVwMapInfo map, OVwSymbolInfo symbol, OVwSubmapInfo submap){ } public void OVwSubmapOpenCB(OVwMapInfo map, OVwSubmapInfo submap){ } public void OVwSubmapCloseCB(OVwMapInfo map, OVwSubmapInfo submap){ } public void OVwAttributeLocateCB(OVwMapInfo map, int requestId, OVwObjectIdList objects){ } public void OVwSymbolStatusLocateCB(OVwMapInfo map, int requestId, int searchVal){ } public void OVwSymbolTypeLocateCB(OVwMapInfo map, int requestId, String searchVal){ } public void OVwSymbolLabelLocateCB(OVwMapInfo map, int requestId, String searchVal){ } public void OVwBusyCancelCB (OVwMapInfo map){ } public void OVwAddActionCB(String actionId,String menuItemId, OVwObjectIdList selected, int argc, StringVectorParm argv,OVwMapInfo mapInfo, int submapId){ } public void OVwDropCB(String drop_action, OVwSymbolIdList dragged_symbs, int droptarget_submap, int droptarget_symbol, int operation, OVwMapInfo map, int drop_id){ } }

280

Appendix B

Using the OVw API Reference Pages

Appendix C

281

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. Note that these reference pages describe the OVw API used for the development of C programs. Although these reference pages were written for the OVw API for C programs, most of the information is equally applicable to the Java bindings for the OVw API. 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. 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.

OVwRegIntro(5)

282

Appendix C

Using the OVw API Reference Pages Printing Reference Pages

Printing Reference Pages

NNM reference pages on Windows systems 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 and Linux 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 (for example., 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, execute: 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. Execute: echo $MANPATH You should see a list with one or more directories. Multiple directories are separated by colons (that is, /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.

Appendix C

283

Using the OVw API Reference Pages Printing Reference Pages 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, execute the following command: tbl -TX /usr/man/man1/bggen.1 |neqn|nroff -man|col|more Example: to send the bggen(1) commands reference page to a file for printing instead, execute 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, execute the following: tbl -TX bggen.1 |neqn|nroff -man|col > /filename

284

Appendix C

Using the OVw API Reference Pages Run-Time Routines By Category

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 Error Handling OVwIsIdNull(3)

Callback Registration OVwAddCallback(3) OVwAddActionCallback(3) OVwAddDropCallback(3)

Appendix C

285

Using the OVw API Reference Pages Run-Time Routines By Category Table C-1 OVw API Manpages Grouped by Category (Continued) Submap Routines OVwAckUserSubmapCreate(3) OVwAddSubmapContext(3) OVwCreateSubmap(3) OVwCreateSubmaps(3) OVwDisplaySubmap(3) OVwGetSubmapInfo(3) OVwListSubmaps(3) OVwLoadSubmap(3) OVwLoadSubmaps(3) OVwUnloadSubmap(3) OVwUnloadSubmaps(3) OVwModifySubmaps(3) OVwSetBackgroundGraphic(3) OVwSubmapChangeCB(3) OVwSetSubmapName(3) OVwSubmapOpenCB(3) OVwSubmapCloseCB(3) OVwUserSubmapCreateCB(3)

Process Management OVwDbInit(3) OVwDone(3) OVwEndSessionCB(3)

286

Appendix C

Using the OVw API Reference Pages Run-Time Routines By Category Table C-1 Symbol Routines OVwCreateSymbolAlert(3) OVwCreateSymbols(3) OVwGetConnSymbol(3) OVwGetSymbolInfo(3) OVwGetSymbolsByObject(3) OVwListSymbols(3) OVwListSymbolTypes(3) OVwModifySymbol(3) OVwSetSymbolApp(3) OVwSetSymbolBehavior(3) OVwSetSymbolLabel(3) OVwSetSymbolPosition(3) OVwSetSymbolStatusSource(3) OVwSetSymbolType(3) OVwSymbolChangeCB(3) OVw API Manpages Grouped by Category (Continued) Object Database Routines OVwDbAppendEnumConstants(3) OVwDbCreateField(3) OVwDbCreateObject(3) OVwDbDeleteObject(3) OVwDbFieldNameToFieldId(3) OVwDbGetEnumConstants(3) OVwDbGetFieldInfo(3) OVwDbGetFieldValue(3) OVwDbGetFieldValues(3) OVwDbGetFieldValuesByObjects(3) OVwDbGetUniqObjectName(3) OVwDbHostnameToObjectId(3) OVwDbInit(3) OVwDbListFields(3) OVwDbListObjectsByFieldValue(3) OVwDbNameToObjectId(3) OVwDbSelectionNameToObjectId(3) OVwDbSetEnumConstants(3) OVwDbSetFieldValue(3) OVwDbSetSelectionName(3) OVwDbUnsetFieldValue(3)

Appendix C

287

Using the OVw API Reference Pages Run-Time Routines By Category Table C-1 OVw API Manpages Grouped by Category (Continued)

Map-Specific Object Routines OVwGetObjectInfo(3) OVwGetSymbolsByObject(3) OVwHighlightObject(3) OVwListObjectsOnMap(3) OVwLocateBySelectionName(3) OVwLocateByAttribute(3) OVwLocateByComment(3) OVwLocateBySymbolStatus(3) OVwLocateBySymbolType(3) OVwLocateBySymbolLabel(3) OVwManageObject(3) OVwSelectObjects(3) OVwSetStatusOnObject(3) Miscellaneous OVwGetSelections(3) OVwSelectListChangeCB(3) Map Routines and Map Events OVwAckMapClose(3) OVwBeginMapSync(3) OVwGetMapInfo(3) OVwMapCloseCB(3) OVwMapOpenCB(3) OVwReturnLocateResults(3) OVwSymbolLabelLocateCB(3) OVwSymbolStatusLocateCB(3) OVwSymbolTypeLocateCB(3) OVwAttributeLocateCB(3)

288

Appendix C

Using the OVw API Reference Pages Run-Time Routines By Category Table C-1 OVw API Manpages Grouped by Category (Continued) Application Information OVwGetAppConfigValues(3) OVwGetAppName(3)

Map Editing and Map Change Events OVwConfirmCapabilityChangeCB(3) OVwConfirmCreateObjectsCB(3) OVwConfirmCreateSubmapCB(3) OVwConfirmCreateSymbolsCB(3) OVwConfirmDeleteObjectsCB(3) OVwConfirmDeleteSubmapsCB(3) OVwConfirmHideSymbolsCB(3) OVwConfirmManageObjectsCB(3) OVwConfirmMoveSymbolCB(3) OVwConfirmObjectStatusCB(3) OVwVerifyAdd(3) OVwVerifyAppConfigChange(3) OVwVerifyConnect(3) OVwVerifyDeleteSymbol(3) OVwVerifyDescribeChange(3) Status OVwSetStatusOnObject(3)

Appendix C

289

Using the OVw API Reference Pages Run-Time Routines By Name

Run-Time Routines By Name

Table C-2 presents a listing of the Java bindings to OVw API routines, sorted alphabetically. The left column contains a list of all Java bindings to OVw API routines, and the right column lists the manpages that contain each of the OVw API 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 Reference Page OVwAckMapClose(3) OVwAckUserSubmapCreate(3) OVwAddCallback(3) OVwAddSubmapContext(3) OVwAttributeLocateCB(3) OVwBeginMapSync(3) OVwSetBackgroundGraphic(3) OVwSetSymbolApp(3) OVwDisplaySubmap(3) OVwVerifyAdd(3) OVwVerifyAppConfigChange(3) OVwConfirmCapabilityChangeCB(3) OVwConfirmObjectStatusCB(3) OVwVerifyConnect(3) OVwConfirmCreateObjectsCB(3) OVwConfirmCreateSubmapsCB(3) OVwConfirmCreateSymbolsCB(3)

Alphabetical List of Functions or Callback Names OVwAckMapClose OVwAckUserSubmapCreate OVwAddCallback OVwAddSubmapContext OVwAttributeLocateCB OVwBeginMapSync OVwClearBackgroundGraphic OVwClearSymbolApp OVwCloseSubmap OVwConfirmAddSymbolCB OVwConfirmAppConfigCB OVwConfirmCapabilityChangeCB OVwConfirmCompoundStatusCB OVwConfirmConnectSymbolsCB OVwConfirmCreateObjectsCB OVwConfirmCreateSubmapsCB OVwConfirmCreateSymbolsCB

290

Appendix C

Using the OVw API Reference Pages Run-Time Routines By Name Table C-2 Function to Reference Page Mapping (Continued) Reference Page OVwConfirmDeleteObjectsCB(3) OVwConfirmDeleteSubmapsCB(3) OVwConfirmDeleteSymbolAlertCB(3) OVwVerifyDeleteSymbol(3) OVwVerifyDescribeChange(3) OVwConfirmHideSymbolsCB(3) OVwConfirmManageObjectsCB(3) OVwConfirmMoveSymbolCB(3) OVwConfirmObjectStatusCB(3) OVwConfirmObjectStatusCB(3) OVwConfirmHideSymbolsCB(3) OVwConfirmManageObjectsCB(3) OVwGetMapInfo(3) OVwCreateSymbol(3) OVwCreateSymbol(3) OVwCreateSymbol(3) OVwCreateSymbol(3) OVwCreateSubmap(3) OVwCreateSubmaps(3) OVwCreateSymbol(3) OVwCreateSymbolAlert(3) OVwCreateSymbol(3)

Alphabetical List of Functions or Callback Names OVwConfirmDeleteObjectsCB OVwConfirmDeleteSubmapsCB OVwConfirmDeleteSymbolAlertCB OVwConfirmDeleteSymbolsCB OVwConfirmDescribeCB OVwConfirmHideSymbolsCB OVwConfirmManageObjectsCB OVwConfirmMoveSymbolCB OVwConfirmObjectStatusCB OVwConfirmSymbolStatusCB OVwConfirmUnhideSymbolsCB OVwConfirmUnmanageObjectsCB OVwCopyMapInfo OVwCreateComponentSymbol OVwCreateComponentSymbolByName OVwCreateConnSymbol OVwCreateConnSymbolByName OVwCreateSubmap OVwCreateSubmaps OVwCreateSymbol OVwCreateSymbolAlert OVwCreateSymbolByHostname

Appendix C

291

Using the OVw API Reference Pages Run-Time Routines By Name Table C-2 Function to Reference Page Mapping (Continued) Reference Page OVwCreateSymbol(3) OVwCreateSymbol(3) OVwCreateSymbol(3) OVwDbAppendEnumConstants(3) OVwDbCreateField(3) OVwDbCreateObject(3) OVwDbCreateObject(3) OVwDbCreateObject(3) OVwDbCreateField(3) OVwDbDeleteObject(3) OVwDbInit(3) OVwDbFieldNameToFieldId(3) OVwDbFieldNameToFieldId(3) OVwDbGetFieldValues(3) OVwDbGetEnumConstants(3) OVwDbGetEnumConstants(3) OVwDbGetEnumConstants(3) OVwDbGetFieldValue(3) OVwDbGetFieldValue(3) OVwDbGetFieldValue(3) OVwDbGetFieldInfo(3) OVwDbGetFieldValue(3)

Alphabetical List of Functions or Callback Names OVwCreateSymbolByName OVwCreateSymbolBySelectionName OVwCreateSymbols OVwDbAppendEnumConstants OVwDbCreateField OVwDbCreateObject OVwDbCreateObjectByHostname OVwDbCreateObjectBySelectionName OVwDbDeleteField OVwDbDeleteObject OVwDbDone OVwDbFieldIdToFieldName OVwDbFieldNameToFieldId OVwDbGetCapabilityFieldValues OVwDbGetEnumConstants OVwDbGetEnumName OVwDbGetEnumValue OVwDbGetFieldBooleanValue OVwDbGetFieldEnumByName OVwDbGetFieldEnumByValue OVwDbGetFieldInfo OVwDbGetFieldIntegerValue

292

Appendix C

Using the OVw API Reference Pages Run-Time Routines By Name Table C-2 Function to Reference Page Mapping (Continued) Reference Page OVwDbGetFieldValue(3) OVwDbGetFieldValue(3) OVwDbGetFieldValues(3) OVwDbGetFieldValuesByObjects(3) OVwDbGetFieldValues(3) OVwDbGetUniqObjectName(3) OVwDbHostnameToObjectId(3) OVwDbInit(3) OVwDbListFields(3) OVwDbListObjectsByFieldValue(3) OVwDbListObjectsByFieldValue(3) OVwDbNameToObjectId(3) OVwDbHostnameToObjectId(3) OVwDbSelectionNameToObjectId(3) OVwDbSelectionNameToObjectId(3) OVwDbSetEnumConstants(3) OVwDbSetFieldValue(3) OVwDbSetFieldValue(3) OVwDbSetFieldValue(3) OVwDbSetFieldValue(3) OVwDbSetFieldValue(3) OVwDbSetFieldValue(3)

Alphabetical List of Functions or Callback Names OVwDbGetFieldStringValue OVwDbGetFieldValue OVwDbGetFieldValues OVwDbGetFieldValuesByObjects OVwDbGetNameFieldValues OVwDbGetUniqObjectName OVwDbHostnameToObjectId OVwDbInit OVwDbListFields OVwDbListObjectsByFieldValue OVwDbListObjectsByFieldValues OVwDbNameToObjectId OVwDbObjectIdToHostname OVwDbObjectIdToSelectionName OVwDbSelectionNameToObjectId OVwDbSetEnumConstants OVwDbSetFieldBooleanValue OVwDbSetFieldEnumByName OVwDbSetFieldEnumByValue OVwDbSetFieldIntegerValue OVwDbSetFieldStringValue OVwDbSetFieldValue

Appendix C

293

Using the OVw API Reference Pages Run-Time Routines By Name Table C-2 Function to Reference Page Mapping (Continued) Reference Page OVwDbSetSelectionName(3) OVwDbSetSelectionName(3) OVwDbUnsetFieldValue(3) OVwDbUnsetFieldValue(3) OVwCreateSubmap(3) OVwCreateSymbol(3) OVwCreateSymbolAlert(3) OVwCreateSymbol(3) OVwDisplaySubmap(3) OVwDone(3) OVwBeginMapSync(3) OVwEndSessionCB(3) OVwGetAppConfigValues(3) OVwGetAppName(3) OVwGetConnSymbol(3) OVwGetMapInfo(3) OVwGetObjectInfo(3) OVwGetSelections(3) OVwGetSubmapInfo(3) OVwGetSymbolInfo(3) OVwGetSymbolsByObject(3) OVwHighlightObject(3)

Alphabetical List of Functions or Callback Names OVwDbSetHostname OVwDbSetSelectionName OVwDbUnsetFieldValue OVwDbUnsetFieldValues OVwDeleteSubmap OVwDeleteSymbol OVwDeleteSymbolAlert OVwDeleteSymbols OVwDisplaySubmap OVwDone OVwEndMapSync OVwEndSessionCB OVwGetAppConfigValues OVwGetAppName OVwGetConnSymbol OVwGetMapInfo OVwGetObjectInfo OVwGetSelections OVwGetSubmapInfo OVwGetSymbolInfo OVwGetSymbolsByObject OVwHighlightObject

294

Appendix C

Using the OVw API Reference Pages Run-Time Routines By Name Table C-2 Function to Reference Page Mapping (Continued) Reference Page OVwHighlightObject(3) OVwInit(3) OVwIsIdNull(3) OVwIsIdNull(3) OVwListObjectsOnMap(3) OVwListSubmaps(3) OVwListSymbolTypes(3) OVwListSymbolTypes(3) OVwListSymbols(3) OVwLoadSubmap(3) OVwLoadSubmap(3) OVwLocate(3) OVwLocate(3) OVwLocate(3) OVwLocate(3) OVwLocate(3) OVwLocate(3) OVwManageObject(3) OVwManageObject(3) OVwMapCloseCB(3) OVwMapOpenCB(3) OVwModifySubmaps(3)

Alphabetical List of Functions or Callback Names OVwHighlightObjects OVwInitSession OVwIsIdEqual OVwIsIdNull OVwListObjectsOnMap OVwListSubmaps OVwListSymbolTypeCaps OVwListSymbolTypes OVwListSymbols OVwLoadSubmap OVwLoadSubmaps OVwLocateByAttribute OVwLocateByComment OVwLocateBySelectionName OVwLocateBySymbolLabel OVwLocateBySymbolStatus OVwLocateBySymbolType OVwManageObject OVwManageObjects OVwMapCloseCB OVwMapOpenCB OVwModifySubmap

Appendix C

295

Using the OVw API Reference Pages Run-Time Routines By Name Table C-2 Function to Reference Page Mapping (Continued) Reference Page OVwModifySubmaps(3) OVwModifySymbols(3) OVwModifySymbols(3) OVwVerifyAdd(3) OVwVerifyAppConfigChange(3) OVwVerifyConnect(3) OVwVerifyDeleteSymbol(3) OVwVerifyDescribeChange(3) OVwAddCallback(3) OVwAddSubmapContext(3) OVwReturnLocateResults(3) OVwSelectListChangeCB(3) OVwSelectObject(3) OVwSelectObject(3) OVwGetAppConfigValues(3) OVwSetBackgroundGraphic(3) OVwSetStatusOnObject(3) OVwSetStatusOnObject(3) OVwSetStatusOnObject(3) OVwSetStatusOnObject(3) OVwSetSubmapName(3) OVwCreateSymbolAlert(3)

Alphabetical List of Functions or Callback Names OVwModifySubmaps OVwModifySymbol OVwModifySymbols OVwQueryAddSymbolCB OVwQueryAppConfigCB OVwQueryConnectSymbolsCB OVwQueryDeleteSymbolsCB OVwQueryDescribeCB OVwRemoveCallback OVwRemoveSubmapContext OVwReturnLocateResults OVwSelectListChangeCB OVwSelectObject OVwSelectObjects OVwSetAppConfigValues OVwSetBackgroundGraphic OVwSetStatusOnObject OVwSetStatusOnObjects OVwSetStatusOnSymbol OVwSetStatusOnSymbols OVwSetSubmapName OVwSetSymbolAlertText

296

Appendix C

Using the OVw API Reference Pages Run-Time Routines By Name Table C-2 Function to Reference Page Mapping (Continued) Reference Page OVwSetSymbolApp(3) OVwSetSymbolBehavior(3) OVwSetSymbolLabel(3) OVwSetSymbolPosition(3) OVwSetSymbolStatusSource(3) OVwSetSymbolType(3) OVwSubmapChangeCB(3) OVwSubmapCloseCB(3) OVwSubmapOpenCB(3) OVwSymbolChangeCB(3) OVwSymbolLabelLocateCB(3) OVwSymbolStatusLocateCB(3) OVwSymbolTypeLocateCB(3) OVwLoadSubmap(3) OVwLoadSubmap(3) OVwManageObject(3) OVwManageObject(3) OVwUserSubmapCreateCB(3) OVwVerifyAdd(3) OVwVerifyAppConfigChange(3)

Alphabetical List of Functions or Callback Names OVwSetSymbolApp OVwSetSymbolBehavior OVwSetSymbolLabel OVwSetSymbolPosition OVwSetSymbolStatusSource OVwSetSymbolType OVwSubmapChangeCB OVwSubmapCloseCB OVwSubmapOpenCB OVwSymbolChangeCB OVwSymbolLabelLocateCB OVwSymbolStatusLocateCB OVwSymbolTypeLocateCB OVwUnloadSubmap OVwUnloadSubmaps OVwUnmanageObject OVwUnmanageObjects OVwUserSubmapCreateCB OVwVerifyAdd OVwVerifyAppConfigChange

Appendix C

297

Using the OVw API Reference Pages Run-Time Routines By Name Table C-2 Function to Reference Page Mapping (Continued) Reference Page OVwVerifyConnect(3) OVwVerifyDeleteSymbol(3) OVwVerifyDescribeChange(3)

Alphabetical List of Functions or Callback Names OVwVerifyConnect OVwVerifyDeleteSymbol OVwVerifyDescribeChange

298

Appendix C

Index
A acknowledgment timer map close, 131 action events description, 57 example, 58 adding a symbol, 203 alerts See status See symbol alert applet example, 42 applets, 230 application callbacks associating with a DropAction, 222 removing association with DropAction, 223 application configuration changing the application configuration, 203 map editing, 203 application development connecting to ovw, 50 disconnecting from ovw, 51 getting application name, 68 registering for event notification, 54 application integration control of drag sources, 219 control of drop targets, 219 participation in map changes, 200 using IP Map as example, 135 application registration file localizing, 237 applications checking map status, 129 connecting to OpenView Windows, 50 example, 273 integration tips, 135 retrieving configuration information, 122 searching for symbols, 181 setting configuration programmatically,
123

clearing, 133 modifying for a submap, 117 setting, 133 supported graphic formats, 134 base symbols, 146 behavior changing for a symbol, 178 symbols, 141 Bus layout algorithm, 102 C callback routines example, 56 for map change events, 195 capabilities merging default fields of symbol type with fields of object, 152 CGI programs, 249 changing attributes of submaps, 117 object description, 203 status colors, 144 submap name, 118 text annotation dynamically for symbol alert, 168 child submaps, 98 clearing background graphics, 133 closing submaps, 113 codeset information, 257 colors changing status colors, 144 compound status, 145 in on-demand map applications, 213 see status configuration changing the application configuration, 203 retrieving information about, 122 setting application configuration programmatically, 123 connecting two symbols, map editing, 203 connection symbol appearance, 176 connection symbols creating, 155 filled, 176 primary status, 176 secondary status, 177 status, 176 299

setting interest in a symbol, 181 starting after map open, 129 attributes map-specific, 188 automatic layout overriding, 153 B background graphics, 133

Index
connections example listing connections within meta-connection submap, 186 multiple, 156 representing multiple connections, 100 contact HP, 19 container symbols meta-connections, 156 convenience routines OVwDb, 90 conventions typographical, 17 coordinate position, 142 setting, 154 copying flashing symbols, 174 symbol alerts, 146 creating a symbol based on object name, 151 a symbol based on parent object, 151 advantages/disadvantages using OVwCreateSymbols(), 159 combinations of icon and connection symbols, 157 connection symbols, 155 example creating multiple symbols with OVwCreateSymbols(), 157 multiple symbols with a single call, 157 object database fields, 79 objects, 83 submaps, deciding when to, 112 symbol alerts, 167 symbols, 149 text annotation dynamically for symbol alert, 168 critical status, 143 customer support, 19 customization drag and drop operations, 221 cut and paste operations, 215 cutting flashing symbols, 174 transparent symbols, 172 D data structures OVwFieldBindList, 89 OVwObjectInfo, 188 OVwObjectList, 190 OVwSubmapList, 115, 124 300 OVwSymbolCreateInfo, 157 OVwSymbolInfo, 184 OVwSymbolPosition, 153 data types object database fields, 77 deleting guidelines for deleting symbols, 159 guidelines for deleting symbols and objects,
160

submaps, 120 symbol alerts, 168 symbols, 159, 208 dialog boxes documenting, 268 disabled status, 143 disconnecting from ovw, 51 displaying graphical map of managed environment,
133

highlighted objects, 73 submaps, 111 displayTextAnnotationBackground, 175 documenting your map application, 263 drag and drop operations, 217225 application callback invocation, 223 assigning a DropAction to a drop target, 222 associating a DropAction with an application callback, 222 behavior, 219 customization steps, 221 help for, 221 removing association between DropAction and application callback, 223 drag source behavior, 219 drop operations behavior, 220 drop targets assigning DropAction to, 222 behavior, 219 drop_action, 222 drop_app_name, 222 DropAction assigning to a drop target, 222 associating with an application callback,
222

removing association with application callback, 223

Index
E enableExecCueRemoval, 173, 174 enableFlashing, 174 encoding, 230 enumerated types defiing, 81 enumeration types retrieving information, 82 event handling example, 61 events, 54 capability field of object changed, 195 compound status changed, 195 confirming appropriate confirm event, 206 hidden symbol, 197 hidden symbol events, 197 manage/unmanage object, 198 manage/unmanage object events, 198 map closed, 195 map editing, 195 map opened, 195 object status changed, 195 one or more objects become managed on map, 195 one or more objects become unmanaged on map, 195 one or more objects created on map, 195 one or more objects deleted from map, 195 one or more submaps created on map, 195 one or more submaps deleted from map, 195 one or more symbols created on map, 195 one or more symbols delected from the map,
195

creating an object containing a name field,

84

creating multiple symbols with OVwCreateSymbols(), 157 event handling, 61 getting contents of selection list, 69 listing connections of a meta-connection submap, 186 retrieving a list of submaps, 124 retrieving field value information, 87 symbol alert callback registration, 162 using OVwCreateSubmap(), 109 using OVwFieldBindList data structure, 89 using OVwGetSelections(), 69 exclusive submaps, 99, 104 exec_vis_cue, 173 executable symbols, 141 appearance, 173 explodable symbols, 98, 141 F field information managing, 77 field registration file localizing, 238 fields convenience routines to retrieve and set values, 88 converting field IDs to field names, 80 converting field names to field IDs, 80 creating, 79 data types, 77 defined, 77 documenting, 265 getting values, 87 name versus identifier, 80 passing values as arguments, 89 retrieving, 81 retrieving information about enumeration,
82

one or more symbols hidden, 195 one or more symbols unhidden, 195 OVW terminated, 195 ovwMapOpen, 127 ovwSelectListChange, 71 selection list changes, 195 status of symbol changed, 195 symbol moved within map, 195 example modifying submap attributes, 118 examples action event registration, 58 callback routine, 56 changing symbol behavior, 179 creating a symbol, 150

retrieving values, 87 returning information based on flag settings, 81 returning information for a single field, 81 setting a value, 88 unsetting a value, 92 flashing, 174 flashing symbols, 174 copying, 174

301

Index
cutting, 174 dragging, 174 map editing, 174 moving, 174 formats for background graphics, 134 G geometry submap, definition, 106 submap, setting, 119 submaps, 107 graphics background of managed environment, 133 supported formats for background graphics,
134

locale, 229 locale information, 258 localization, 230 locate results returning for on-demand map applications,
209

locating objects on transient submaps, 209 M major status, 143 managing objects programmatically, 214 managing status on-demand map applications, 213 map applications dependencies, 269 documenting, 263 on-demand, 209 transient, 209 map databases controlling size, 105 map editing adding a symbol, 200 changing application configuration, 200 changing the application configuration, 203 choosing confirm event, 206 connecting symbols, 200 connecting two symbols, 203 cut and paste operations, 215 flashing symbols, 174 interactions, 200 modifying object attributes, 200 query-verify-confirm sequence, 201 map edits transparent symbols, 172 maps application configuration, 122 application participation in map changes, callback routines for map change events,
195 200, 208

H help on drag and drop operations, 221 hidden symbol events, 197 hiding symbol alerts, 146 highlighting objects, 73 home submaps, 99 HP OpenView Windows object database, 77 I internationalization, 229 IP hostname predefined name field, 82 ISO 10164 status severity levels, 144 L labels changing symbol labels, 180 symbol, 140 layout algorithms, 102 constraints, 142 defined, 141 modifying for a submap, 117 overriding, 142 placing symbols on background graphic, 134 listing all objects on a map, 190 open submaps, 126 registered symbols types, 187 symbols on submap, 187 302

close request, 131 defined, 97 getting information, 121 map close acknowledgment timer, 131 map editing events, 195 open, 97 processing a map close event, 131 processing map open request, 127 synchronization, 128

Index
synchronization routines, 128 meta-connection submaps example listing connections, 186 meta-connections, 156 submap, 100 minor/marginal status, 143 modifying attributes of submaps, 117 submap name, 118 submaps, 117 moving flashing symbols, 174 transparent symbols, 172 multiple connections, 156 Multiple Connections layout algorithm, 102 N name field, 82 No Layout layout algorithm, 102 no position, 142 normal status, 143 O object databases convenience routines, 90 developer access, 77 field data types, 77 persistence, 77 object information managing, 77 Objects, 188 objects adding field, 88 as status sources, 145 changing description, 203 changing selection list via APIs, 71 creating, 83 creating by hostname, 86 creating by selection name, 86 defined, 78 definition, 139 deleting, 92 generating unique name, 85 generating unique selection name, 85 getting the selection list, 69 global attributes vs. map-specific attributes, 190 highlighting, 73 listing all on a map, 190 locating on transient submaps, 209 manage/unmanage object events, 198 managing programmatically, 214 map-specific attributes, 189 OVwDbCreateObject(), 84 parent, 98 retrieving information, 188191 selecting via API, 71 selection name, 83 unique ID, 83 unmanaging programmatically, 214 on-demand map applications considerations when creating and destroying submaps, 213 design considerations, 213 location objects and symbols, 209 managing status, 213 ovwConfirmCreateSubmaps, 213 ovwConfirmDeleteSubmaps, 213 OVwGetSymbolsByObject, 213 OVwListObjectsOnMap, 213 OVwListSubmaps, 213 returning locate results, 209 using compound presentation status, 213 using OVwGetSymbolsByObject(), 213 using OVwListObjectsOnMap(), 213 using OVwListSubmaps(), 213 on-demand programming tips considerations when creating and destroying submaps, 213 status management in transient submaps,
213

on-demand submaps, 104, 112 op_scope, 199 open maps, 97 orphaned submaps, 99 overlay setting submap overlay, 118 submap windows, 106 OVw APIs groups, 28 ovw events, 54 OVwAckMapClose(), 131 OVwAddActionCallback(), 57 OVwAddActionCB(), 57 OVwAddDropCallback(), 222 OVwAddSubmapContext(), 110 OVwAttributeLocateCB(), 212 OVwClearBackgroundGraphic, 133 OVwClearSymbolApp(), 181

303

Index
OVwCloseSubmap(), 113 OVwConfirmAddSymbolCB(), 203, 207 OVwConfirmAppConfigCB(), 203 ovwConfirmCapabilityChange, 195 OVwConfirmCapabilityChangeCB(), 195 ovwConfirmCompoundStatusChange, 195 OVwConfirmCompoundStatusChangeCB(), OVwConfirmConnectSymbolsCB(), 203 ovwConfirmCreateObjects, 195 OVwConfirmCreateObjectsCB(), 195 ovwConfirmCreateSubmaps, 195 OVwConfirmCreateSubmapsCB(), 195 OVwConfirmCreateSymbolCB(), 207 ovwConfirmCreateSymbols, 195 OVwConfirmCreateSymbolsCB(), 195 ovwConfirmDeleteObjects, 195 OVwConfirmDeleteObjectsCB(), 195 ovwConfirmDeleteSubmaps, 195 OVwConfirmDeleteSubmapsCB(), 195 OVwConfirmDeleteSymbolAlertCB(), 168 ovwConfirmDeleteSymbols, 195 OVwConfirmDeleteSymbolsCB(), 195 OVwConfirmDescribeCB, 203 ovwConfirmHideSymbols, 195, 198 OVwConfirmHideSymbolsCB(), 195 ovwConfirmManageObjects, 195 OVwConfirmManageObjectsCB(), 195 ovwConfirmMoveSymbols, 195 OVwConfirmMoveSymbolsCB(), 195 ovwConfirmObjectStatusChange, 195 OVwConfirmObjectStatusChangeCB(), 195 ovwConfirmSymbolStatusChange, 195 OVwConfirmSymbolStatusChangeCB(), 195 ovwConfirmUnhideSymbols, 195, 198 OVwConfirmUnhideSymbolsCB(), 195 ovwConfirmUnmanageEvent, 199 ovwConfirmUnmanageObjects, 195 OVwConfirmUnmanageObjectsCB(), 195 OVwCreateComponentSymbol(), 151 OVwCreateConnSymbol(), 155 OVwCreateSubmap(), 108 OVwCreateSymbolAlert(), 167 OVwCreateSymbolByName(), 151 OVwCreateSymbols(), 149, 157 OVwDb convenience routines, 90 OVwDbCreateObject(), 84 OVwDbCreateObjectByHostname(), 86 OVwDbCreateObjectBySelectionName(), 86 OVwDbFieldIdToFieldName(), 80 OVwDbFieldNameToFieldId(), 80 OVwDbGetEnumConstants(), 82
195

OVwDbGetEnumName(), 82 OVwDbGetEnumValue(), 82 OVwDbGetFieldInfo(), 81 OVwDbGetFieldValue(), 87 OVwDbGetFieldValues(), 89 OVwDbSetEnumConstants(), 81 OVwDbSetFieldValue(), 88 OVwDeleteSubmap(), 120 OVwDeleteSymbol(), 159 OVwDeleteSymbolAlert(), 168 OVwDeleteSymbols(), 159 OVwDisplaySubmap(), 111 OVwDone, 51 ovwDoNotDisplayLabel, 152 OVwDropCallbackProc(), 224 OVwDropCB(), 223 ovwEndSession, 195 OVwEndSessionCB(), 195 OVwGetAppConfigValues(), 122 OVwGetAppName(), 68 OVwGetConnSymbol(), 185 OVwGetMapInfo(), 121 OVwGetObjectInfo(), 189 OVwGetSymbolInfo(), 184 OVwGetSymbolsByObject(), 189 in on-demand map applications, 213 OVwHighlightObject(), 73 OVwHighlightObjects(), 73 OVwListObjectsOnMap(), 190 in on-demand map applications, 213 OVwListOpenSubmaps(), 126 OVwListSubmaps(), 123 in on-demand map applications, 213 OVwListSymbols(), 187 OVwListSymbolTypeCaps(), 187 OVwListSymbolTypes(), 187 OVwManageObject(), 214 OVwManageObjects(), 214 ovwMapClose, 195 OVwMapCloseCB(), 195 ovwMapOpen, 127, 195 OVwMapOpenCB(), 127, 195 ovwMergeDefaultCapabilities, 152 OVwModifySubmap, 117 OVwModifySubmap(), 117 OVwModifySubmaps, 117 OVwModifySubmaps(), 117 ovwNoLayout, 134 ovwNoPosition, 152 ovwNoSymbolFlags, 152 OVwObjectInfo data structure, 188 OVwQueryAddSymbolCB(), 203 OVwQueryConnectSymbolsCB(), 203

304

Index
OVwQueryDescribeCB(), 203 OVwRemoveActionCallback(), 60 OVwRemoveDropCallback(), 223 OVwRemoveSubmapContext(), 111 OVwReturnLocateResults(), 209 ovwSelectionListChange, 195 OVwSelectionListChangeCB(), 195 ovwSelectListChange event, 71 OVwSelectObject(), 71 OVwSelectObjects(), 71 OVwSetAppConfigValues(), 123 OVwSetBackgroundGraphic, 133 OVwSetStatusOnObject, 182 OVwSetStatusOnObjects(), 183 OVwSetStatusOnSymbol(), 182 OVwSetStatusOnSymbols(), 183 OVwSetSymbolAlertText(), 168 OVwSetSymbolApp(), 181 OVwSetSymbolBehavior(), 178 OVwSetSymbolPosition(), 178 OVwSetSymbolStatusSource(), 182 OVwSetSymbolType(), 177 OVwSubmapList data structure, 115, 124 OVwSymbolCreateInfo data structure, 157 OVwSymbolInfo data structure, 184 OVwSymbolLabelLocateCB(), 212 OVwSymbolStatusLocateCB(), 212 OVwSymbolTypeLocateCB(), 212 OVwUnmanageObject(), 214 OVwUnmanageObjects(), 214 ovwUpdateSubmapDropAction, 222 ovwUpdateSubmapOverlay, 118 ovwUpdateSubmapWindowHeight, 119 ovwUpdateSubmapWindowWidth, 119 ovwUpdateSubmapWindowX, 119 ovwUpdateSubmapWindowY, 119 ovwUpdateSymbolDropAction, 222 ovwUpdateSymbolExecVisCue, 173 ovwUpdateSymbolFlashing, 174 ovwUpdateSymbolPercentFull, 177 ovwUpdateSymbolSecondaryStatus, 177 ovwUpdateTextAnnotationText, 175 OVwVerifyAdd(), 203 OVwVerifyAppConfigChange(), 203 OVwVerifyConnect(), 203 OVwVerifyDeleteSymbol(), 208 OVwVerifyDescribeChange(), 203 P parent objects, 98 modifying for a submap, 117 parent submaps, 98 paste and cut operations, 215 percent_full, 177 persistent submaps, 104 symbol alerts, 164 Point to Point layout algorithm, 102 position changing symbol position, 178 setting for symbol, 152 predefined fields, 82 processing map close event, 131 map open requests, 127 programming tips acknowledging map close events, 131 advantages/disadvantages using OVwCreateSymbols(), 159 changing symbol behavior, 179 changing symbol labels, 180 choosing appropriate confirm event, 206 cut and paste operations, 215 deleting symbols, 159 deleting symbols and objects, 160 efficient use of map information, 122 global attributes vs. map-specific attributes, 190 guidelines for symbol placement, 155 IP Map as application integration example,
135

managing status, 213 map-specific object information vs. global object information, 189 placing symbols on background graphic, 134 status management in transient submaps,
213

symbol alerts in persistent/transient submaps, 164 using compound presentation status in on-demand map applications, 213 Q query-verify-confirm methods, 203 R receiving map change notifications, 195 registering map open events, 127 registration files, 41 documenting, 264 localizing, 237 305

Index
types, 26 removing submap context, 111 reply card, 19 restricted status, 143 retrieving application configuration information, 122 global object attributes vs. map-specific attributes, 190 information about a specific submap, 123 information about open map, 121 list of open submaps, 126 list of registered symbol types, 187 list of submaps, 123 map-specific object information, 189 object information, 188191 symbol information, 156, 184 reusing submap window, 118 Ring layout algorithm, 102 root submaps, 99 routine OVwManageObject(), 214 OVwManageObjects(), 214 OVwUnmanageObject(), 214 OVwUnmanageObjects(), 214 routines OVwAckMapClose(), 131 OVwAddCallback(), 55 OVwAddSubmapContext(), 110 OVwBeginMapSync(), 128 OVwClearBackgroundGraphic(), 133 OVwClearSymbolApp(), 181 OVwCloseSubmap(), 113 OVwCopyMapInfo(), 122 OVwCreateComponentSymbol(), 151 OVwCreateConnSymbol(), 155 OVwCreateSubmap(), 108 OVwCreateSymbol(), 149 OVwCreateSymbolAlert(), 167 OVwCreateSymbolByName(), 151 OVwCreateSymbols(), 157 OVwDbCreateField(), 80 OVwDbCreateObject(), 84 OVwDbDeleteObject(), 92 OVwDbFieldIdToFieldName(), 80 OVwDbFieldNameToFieldId(), 80 OVwDbGetEnumConstants(), 82 OVwDbGetEnumName(), 82 OVwDbGetEnumValue(), 82 306 OVwDbGetFieldInfo(), 81 OVwDbGetFieldValue(), 87 OVwDbGetFieldValues(), 89 OVwDbSetEnumConstants(), 81 OVwDbSetFieldValue(), 88 OVwDbUniqObjectName(), 85 OVwDbUnsetFieldValue(), 92 OVwDeleteSubmap(), 120 OVwDeleteSymbol(), 159 OVwDeleteSymbolAlert(), 168 OVwDeleteSymbols(), 159 OVwDisplaySubmap(), 111 OVwDone(), 51 OVwEndMapSync(), 128 OVwGetAppConfigValues(), 122 OVwGetAppName(), 68 OVwGetConnSymbol(), 185 OVwGetMapInfo(), 121 OVwGetObjectInfo(), 189 OVwGetSelections(), 69 OVwGetSubmapInfo(), 123 OVwGetSymbolInfo(), 184 OVwGetSymbolsByObject(), 189 OVwHighlightObject(), 73 OVwHighlightObjects(), 73 OVwInit(), 50 OVwListFields(), 81 OVwListObjectsOnMap(), 190 OVwListOpenSubmaps(), 126 OVwListSubmaps(), 123 OVwListSymbols(), 187 OVwListSymbolTypeCaps(), 187 OVwListSymbolTypes(), 187 OVwModifySubmap, 117 OVwModifySubmaps, 117 OVwRemoveSubmapContext(), 111 OVwSelectObject(), 71 OVwSelectObjects(), 71 OVwSetAppConfigValues(), 123 OVwSetBackgroundGraphic(), 133 OVwSetStatusOnObject(), 182 OVwSetStatusOnObjects(), 183 OVwSetStatusOnSymbol(), 182 OVwSetStatusOnSymbols(), 183 OVwSetSubmapName(), 118 OVwSetSymbolAlertText(), 168 OVwSetSymbolApp(), 181 OVwSetSymbolBehavior(), 178 OVwSetSymbolLabel(), 180

Index
OVwSetSymbolPosition(), 178 OVwSetSymbolStatusSource(), 182 OVwSetSymbolType(), 177 OVwVerifyDeleteSymbol(), 208 Row/Column layout algorithm, 102 S scalability, 104 secondary_status, 177 selecting objects via API, 71 selection lists, 69 change notification, 71 changing contents, 71 getting contents, 69 selection rules, 70 selection names, 83 predefined name field, 82 selection rules using in OVW programs, 70 sequence position, 142 constraints, 142 setting, 153 session management, 51, 254 setting application configuration dynamically, 123 background graphics, 133 submap context, 110 severity levels ISO 10164 standard, 144 shared submaps, 104 SNMP traps localization, 239 Star Center layout algorithm, 102 star center position, 142 constraints, 142 status changing colors, 144 changing the value, 182 colors, 143 compound, 100, 145 connection symbols, 176 control of status summation algorithm, 145 eliminating status conflict between applications, 145 managing status in on-demand map applications, 213 representing in parent object, 100 sources, 145 status source by object, 145 summation of status for multiple symbols,
145

symbol, 145 symbol status, 145 symbols, 143 status categories, 143 status colors changing, 144 See also symbol alerts status conditions, 143 status meaning, 143 status source changing for a symbol, 182 submap context defined, 98 removing, 111 setting, 110 submap geometry modifying for a submap, 117 setting, 119 transient submaps, 119 submap overlay modifying for a submap, 117 ovwUpdateSubmapOverlay, 118 setting, 118 submap_overlay, 118 submap policies modifying for a submap, 117 submap types modifying for a submap, 117 submap_overlay, 118 submap_window_height, 119 submap_window_width, 119 submap_window_x, 119 submap_window_y, 119 submaps, 104 background graphic, 133 changing characteristics, 117 changing the name, 118 child, 98 choosing when to create, 112 closing, 113 creating, 108 defined, 98 deleting, 120 displaying, 111 documenting, 267 exclusive, 99, 104 geometry, 107 geometry definition, 106

307

Index
getting information about specific submap,
123

hierarchy, 112 home, 99 layout algorithm, 102 layout algorithm, defined, 141 list of symbols on, 187 listing open submaps, 126 meta-connection, 100 modifying, 117 modifying attributes of, 117 modifying name, 118 names, modifying for a submap, 117 on-demand, 104 organizing hierarchy, 112 orphaned, 99 overlay, 106 overlay defined, 105 parent, 98 persistent, 104 planes, 103 presentation, 105 retrieving a list, 123 root, 99 scalability, 104 setting context, 110 setting geometry, 119 shared, 104 shared vs. exclusive, 104 size and location, 119 size and location of window, 106 transient, 104 window reuse, 106 symbol alerts, 160169 aligning text annotation, 168 and panner display, 146 base symbol, 146 base symbol description, 164 behavior, 161 components, 163 copying, 146 creating, 167 default action, 165 deleting, 168 description, 146 dynamically creating or changing text annotation, 168 example action and callback registration,
162

hiding, 146 on-demand submaps, 164 popup menu, 166 scaling, 146 See also status size, 146 specifying text string for text annotation,
167

text annotation, 165 transient/persistent submaps, 164 use model, 161 symbol placement automatic, 103 guidelines, 155 See also layout algorithms setting coordinate position, 154 setting sequence position, 153 using a grid, 154 symbol position setting coordinate position, 154 setting sequence position, 153 symbol registration file localizing, 238 symbol types documenting, 266 symbols adding, 203 advantages/disadvantages using OVwCreateSymbols(), 159 affect of copying on symbol alerts, 146 as base for symbol alerts, 146 as status sources, 145 behavior, 141 changing appearance and behavior, changing status values, 182 changing the label, 180 changing the position, 178 changing the status source, 182 changing the type, 177 clearing application interest, 181 connection symbol appearance, 176 connection symbol status, 176 connection, defined, 140 creating, 149 creating a symbol based on object name, 151 creating a symbol based on parent object,
151 170183

creating connection symbols, 155

308

Index
creating several with a single call, 157 default behavior, 141 definition, 139 deleting, 159, 208 disabling executable symbol visual cue, during map editing, 200 example changing behavior, 179 example creating multiple symbols with OVwCreateSymbols(), 157 executable, 141 executable symbol appearance, 173 explodable, 98, 141 filled connection symbols, 176 flags for creating, 152 flashing, 174 guidelines for deleting symbols, 159 guidelines for deleting symbols and objects,
160 173, 174

hidden symbol events, 197 icon, defined, 140 label, definition, 140 listing on a submap, 187 listing possible object capabilities, 187 listing registered types, 187 making executable, 178 making explodable, 178 meta-connections, 156 placement guidelines, 155 position, 141 primary status of connection symbols, 176 representing multiple connections between,
100

T technical support, 19 testing status, 143 text annotation, 174 text_annotation, 175 textAnnotationBackgroundColor, 175 textAnnotationColor, 175 The, 187 timer map close acknowledgment, 131 training information, 19 transient submaps locating objects, 209 submap geometry, 119 symbol alerts, 164 when to use, 112 transparent symbols, 171 effects of map edits, 172 trapd.conf localization, 239 type symbols, 177 types symbol, 140 symbol type routines, 187 U unique object names generating, 85 unknown status, 143 unmanage status, 143 unmanaging objects programmatically, 214 updating map synchronization, 128 V varieties symbol, 140 visual cues See also connection symbols See executable symbols See flashing symbols See status See symbol alerts See transparent symbols W warning status, 143

secondary status of connection symbols, 177 see status setting application interest, 181 setting coordinate position, 154 setting position, 152 setting sequence position, 153 sources of status, 145 symbol type routines, 187 text annotation, 174 transparent, 171 type, 177 type, definition, 140 varietys, 140 synchronizing maps, 128

309

Index
web application integration, 251 web applications security, 247 session model, 247 user model, 247 web components CGI programs, 249 services and files, 247 web launcher registration file, 251 web UI session, 247 windows presentation of submaps, 105 reusing, 118 submap arrangement on display, 107 X xnmappmon, 45

310