Level II Developer s Tools Software Release Notice 5.0 Rev 1

Transcription

1 Level II Developer s Tools Software Release Notice 5.0 Rev 1

2 E19 Level II Developer s Tools SPECTRUM Software Release Notice 5.0 Rev 1

3 Notice Cabletron Systems reserves the right to make changes in specifications and other information contained in this document without prior notice. The reader should in all cases consult Cabletron Systems to determine whether any such changes have been made. The hardware, firmware, or software described in this manual is subject to change without notice. IN NO EVENT SHALL CABLETRON SYSTEMS BE LIABLE FOR ANY INCIDENTAL, INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING BUT NOT LIMITED TO LOST PROFITS) ARISING OUT OF OR RELATED TO THIS MANUAL OR THE INFORMATION CONTAINED IN IT, EVEN IF CABLETRON SYSTEMS HAS BEEN ADVISED OF, KNOWN, OR SHOULD HAVE KNOWN, THE POSSIBILITY OF SUCH DAMAGES. Copyright September 1998, by Cabletron Systems, Inc. All rights reserved. Printed in the United States of America. Order Number: E19 Cabletron Systems, Inc. P.O. Box 5005 Rochester, NH SPECTRUM, the SPECTRUM IMT/VNM logo, DCM, IMT, and VNM are registered trademarks, and SpectroGRAPH, SpectroSERVER, Inductive Modeling Technology, Device Communications Manager, and Virtual Network Machine are trademarks of Cabletron Systems, Inc. Adobe and Acrobat are trademarks of Adobe Systems, Inc. C++ is a trademark of American Telephone and Telegraph, Inc. UNIX, OSF/1 and Motif are registered trademarks of The Open Group. X Window System is a trademark of the X Consortium. Ethernet is a trademark of Xerox Corporation. Virus Disclaimer Cabletron Systems makes no representations or warranties to the effect that the Licensed Software is virus-free. Cabletron has tested its software with current virus checking technologies. However, because no anti-virus system is 100% reliable, we strongly caution you to write protect and then verify that the Licensed Software, prior to installing it, is virus-free with an anti-virus system in which you have confidence E19 i

4 Restricted Rights Notice (Applicable to licenses to the United States Government only.) 1. Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS Cabletron Systems, Inc., 35 Industrial Way, Rochester, New Hampshire (a) This computer software is submitted with restricted rights. It may not be used, reproduced, or disclosed by the Government except as provided in paragraph (b) of this Notice or as otherwise expressly stated in the contract. (b) This computer software may be: (1) Used or copied for use in or with the computer or computers for which it was acquired, including use at any Government installation to which such computer or computers may be transferred; (2) Used or copied for use in a backup computer if any computer for which it was acquired is inoperative; (3) Reproduced for safekeeping (archives) or backup purposes; (4) Modified, adapted, or combined with other computer software, provided that the modified, combined, or adapted portions of the derivative software incorporating restricted computer software are made subject to the same restricted rights; (5) Disclosed to and reproduced for use by support service contractors in accordance with subparagraphs (b) (1) through (4) of this clause, provided the Government makes such disclosure or reproduction subject to these restricted rights; and (6) Used or copied for use in or transferred to a replacement computer. (c) (d) (e) Notwithstanding the foregoing, if this computer software is published copyrighted computer software, it is licensed to the Government, without disclosure prohibitions, with the minimum rights set forth in paragraph (b) of this clause. Any other rights or limitations regarding the use, duplication, or disclosure of this computer software are to be expressly stated in, or incorporated in, the contract. This Notice shall be marked on any reproduction of this computer software, in whole or in part. Level II Developer s Tools ii Software Release Notice 5.0 Rev 1

5 Contents Preface What Is in This Chapter...v Purpose of This Document...v Version Control... vi Who Should Read This Guide... vii How to Use This Guide... vii Typographic Conventions... vii Introductory Reading... viii Other Related Documentation... viii Questions about SPECTRUM Documentation... viii Chapter 1 Overview What Is in This Chapter Product Description System Requirements New Features Management Station Access Provider External Protocol Interface (MSAP/EPI) SpectroSERVER Application Program Interface (SSAPI) Inference Handler Application Program Interface (IHAPI) SSAPI and IHAPI VnmParmBlock Application Program Interface (VPAPI) Other Toolkit Information Chapter 2 Corrected Anomalies What Is in This Chapter SpectroSERVER API (SSAPI) Toolkit Chapter 3 Known Anomalies What Is in This Chapter Inference Handler Application Program Interface (IHAPI) SpectroSERVER Application Program Interface (SSAPI)/View Application Program Interface (VWAPI) E19 iii

6 Level II Developer s Tools iv Software Release Notice 5.0 Rev 1

7 Preface What Is in This Chapter This chapter describes the purpose and content of the SPECTRUM Level II Developer s Toolkit Software Release Notes, explains the SPECTRUM version control scheme, and identifies additional sources of information about SPECTRUM products. Purpose of This Document A Software Release Notice (SRN) accompanies each distribution of version 5.0 rev 1 of the SPECTRUM Level II Developer s Tools. The SRN is intended to: Alert the user to product enhancements or changes List hardware and software requirements for the current version Identify any operational anomalies corrected since the previous release Explain any remaining anomalies and offer solutions or workarounds wherever feasible Identify any updates or corrections to related documentation A new SRN is issued and packaged with each subsequent release of this product. It is strongly recommended that you read the accompanying SRN each time you receive an updated version of the software so that you will be aware of any changes in the product or the associated documentation. This document does not contain installation instructions. To install any of the Level II toolkits, consult the latest version of the Installation Guide and any README file(s) and/or hardcopy instructions included with the installation media E19 v

8 Version Control Version Control SPECTRUM s numbering scheme for version control consists of up to four numeric fields as well as an alphabetic descriptor as shown in the following diagram. 5.0 rev 1.00 Major Release Minor Release Descriptor Revision Build Major Release Minor Release Descriptor Revision Build Increments to the number in this field represent major changes in the product s design, functionality, or user interface. Major releases are planned several months in advance. Minor releases are scheduled product upgrades that provide new or enhanced features but do not represent functionality changes as significant as those involved in a major release. Minor releases can occur one or more times per year. This field identifies the current version as either a revision to a major/minor release (rev) or a revision to a test release (alpha or beta). This field is incremented for subsequent revisions to a release and is reset to zero for each new major/ minor release. This field is primarily used for internal tracking of individual builds under a particular revision and is not usually visible to the customer. Build numbers are encountered only in conjunction with alpha and beta test releases or special, limited distribution support releases. Preface Level II Developer s Tools vi Software Release Notice 5.0 Rev 1

9 Who Should Read This Guide Who Should Read This Guide This guide is intended for developers who want to create, modify, or convert applications for use with SPECTRUM. How to Use This Guide This guide is organized as follows: Chapter Chapter 1 Chapter 2 Chapter 3 Description Introduces the Level II Developer s Tools Software release Notice (SRN) document, and describes the various release levels available. Describes the known irregularities or anomalies that have been corrected. Lists the currently known anomalies for the Level II Developer s Tools. Typographic Conventions Certain typographical conventions are used throughout the SPECTRUM Developer s Tools documentation to distinguish between classes, objects, executables, and examples of code. Names of all Cabletron-developed classes begin with Cs and appear in the courier font. Executable names appear in bold italics. For example, an executable named Application appears as Application. Examples of code appear in a different font (courier 10 pt) and are set apart from the rest of the text. For example: (New save_if_needed() new()) E19 Preface vii

10 Introductory Reading Introductory Reading Refer to the following Level II toollkit documentation initially: Level II Toolkit Overview Generic SNMP Management Module Guide Refer to the following documentation for more information: SPECTRUM Knowledge Based Guide SPECTRUM Concepts Guide Other Related Documentation Refer to the following documentation for more information on managing TCP/ IP-based networks: Martin, James, Kathleen Kavanagh Chapman, Joe Leben. Local Area Networks: Architectures and Implementations, 2d ed. Englewood Cliffs, NJ: Prentice Hall, Rose, Marshall T. The Simple Book: An Introduction to Management of TCP/IP-based Internets. Englewood Cliffs, NJ: Prentice Hall, Stallings, William. Data and Computer Communications, 4th ed. New York: Macmillan Publishing Company, Tanenbaum, Andrew S. Computer Networks, 3d ed. Englewood Cliffs, NJ: Prentice Hall, Questions about SPECTRUM Documentation Send your questions, comments or suggestions regarding SPECTRUM documentation to the Technical Communications Department directly via the following internet address: Preface Level II Developer s Tools viii Software Release Notice 5.0 Rev 1

11 Chapter 1 Overview What Is in This Chapter Chapter One provides a description of the SPECTRUM Level II Developer s Tools for 5.0 rev 1. This chapter also identifies new features, platform and compiler resources required to operate SPECTRUM, and any operational constraints that pertain to the last major release (5.0 rev 0). Product Description The SPECTRUM Level II Developer s Tools provide C/C++ programming interfaces for developing advanced extensions to SPECTRUM. These tools include header files, object libraries, sample source code, complete documentation, and direct developer training and support from Cabletron. The following Level II Developer s Tools are available: SPECTRUM SpectroSERVER Application Program Interface (SSAPI) -- The SpectroSERVER API is the primary communications interface between the SpectroSERVER and client processes such as SpectroGRAPH. The API provides both an asynchronous interface (for interactive and windowed applications) and an synchronous interface (for query and report requests to SPECTRUM). SPECTRUM View Application Program Interface (VAPI) -- The View API helps developers integrate new or modified views into the SPECTRUM environment. Full cut-and-paste functionality is supported, and generic views detailing aspects of the model state are accomplished with the View API. Views from non-cabletron products can be accessed or external processes can be initiated from SPECTRUM with this toolkit E19 1-1

12 Product Description SPECTRUM Virtual Network Machine Parameter Block API (VPAPI) -- This toolkit includes the VnmParmBlock C++ Class Libraries, which are essential to the development of C++ objects and programs that integrate with SpectroSERVER. The VnmParmBlock classes are used to define objects that allow access to specific SPECTRUM model types, attributes, aspects, and processes. VPAPI is used with the Inference Handler API, View API, and SpectroSERVER API s. SPECTRUM Inference Handler API (IHAPI) -- This toolkit provides source code and documentation for the development of Inference Handlers, which add artificial intelligence to user/var-developed model types within SPECTRUM. Inference Handlers can be created that allow SPECTRUM to manage entirely new objects and devices by defining their possible interactions between SPECTRUM and the objects or devices. The IHAPI Toolkit includes C++ object libraries, header files, and tutorials based on sample source code, to guide developers through the process of creating new Inference Handlers. Also included is a discussion of debugging techniques applicable to the SPECTRUM multi-threaded environment. SPECTRUM Management Station Access Provider External Protocol Interface (MSAP/EPI) -- This toolkit allows developers to map generic interfaces to a device s protocol. MSAP/EPI provides an object with access to a SpectroSERVER or other management station. Protocols can be written in C and Assembler, and integrated through a straight-forward interface layer, with no need to access or modify SPECTRUM internals. This toolkit also defines the requirements for building management modules for device and MSAP model types. SPECTRUM Map API-- This toolkit allows modification of the attributes that control map-type views (Topology, Location, and Organization). The following can be changed: icon or annotation positions or groupings, the size of the view, and the icon or annotation s zoom level. Additionally, either the view s background color or raster can be changed with the Map API toolkit. Annotations can be added/removed, and models or connections can be read within the view or via the relations. A personalized map-type view containing specific data-types can also be created with this toolkit. Global Classes -- The Global C++ class library is used to create and manipulate buffers for the Inference Handler API, the View API, and SpectroSERVER APIs. Refer to the SPECTRUM Global Classes Reference for more information. Overview Level II Developer s Tools 1-2 Software Release Notice 5.0 Rev 1

13 Product Description With the SPECTRUM Level II Developer s Tools, customers and VAR developers can create more advanced extensions than with the Level I tools, by integrating new objects and programs into the SPECTRUM knowledgebase. These additions range from providing management information for third party applications, to a VAR-developed management module that can be sold to multiple customer sites. Several of the most common types of Level II extensions are listed below: Development of a new physical or logical device view, using the Asynchronous SpectroSERVER API and the View API. Although a device management module can be developed with just the Level I Developer s Tools, appropriate physical or logical device view information is missing. The Asynchronous SpectroSERVER API allows the new view complete read and write access to the model of the device contained within the SpectroSERVER process, including all that is known about the current state of the model. The View API allows the new view to appear integrated with the SpectroGRAPH process. Full copy, cut, and paste functionality is supported, as well as the starting of other views within SPECTRUM. Of particular note, the View API provides a way for a new device view to bring up generic views detailing particular aspects of the model s state. The addition of different protocols to SPECTRUM to manage devices that do not support SNMP using the EPI API. Each new protocol leads to an additional EPI process, which translates SpectroSERVER EPI requests into the appropriate proprietary requests. Integration of new or existing applications onto the SPECTRUM Platform. Depending on the type of application being integrated, and the level of integration needed, this may require the use of one or more of the Level II Developer s Tools. For example, to allow the application to access SPECTRUM data, use either the Synchronous or Asynchronous SpectroSERVER APIs.To allow an application to appear integrated at the user interface, use the View API. If the application requires that intelligence be added to the SpectroSERVER, then the Inference Handler API is needed. Implementation of a Gateway between SPECTRUM and another Network Management System using the Asynchronous SpectroSERVER API. A Gateway allows the sharing of alarm information between network management systems, and allows centralized management of a network whose subcomponents are managed by different network management systems. Development of new intelligence circuits that add new or customized management functions to SPECTRUM, using the Inference Handler API. Inference handlers provide the procedural knowledge that controls how a model type reacts to changes in its environment. Creating an inference handler requires the development of C++ code that registers the inference handler to monitor environmental conditions and defines the model type s reaction to changes in these conditions E19 Overview 1-3

14 System Requirements System Requirements In addition to the basic SPECTRUM Network Management package and all its general and platform-specific prerequisites, the SPECTRUM Level II Developer s Tools require an appropriate version of a C++ Compiler, as shown in the chart below, and a development environment (e.g., the Motif development environment if OSF/MOTIF mwm is currently being used). For more information on Solaris hardware requirements, or specific Solaris patches, refer to the Solaris Platform section of the Core Software Release Notes. * Platform/OS Window Mgr Compiler Solaris with patches (for SPECTRUM) Solaris 2.6 with patches (for SPECTRUM RunTime) NT 4.0 with Service Pack 3 Open Windows WindowMgr, CDE (Sun Enhanced X11R5 Window System) Open Windows 3.6 Window Mgr, CDE 1.2 (Sun Enhanced X11R5 Window System) C++4.1 (and OS patches) SPARCworks Professional C SPARCompiler C SPARCworks 3.1 C++4.1 (and OS patches) N/A Visual C SPARCworks Professional C SPARCompiler C SPARCworks 3.1 ** DataFocus NuTCRACKER 1.6b SDK (required for EPAPI and IHAPI Level II development work on NT) NOTE *Although vendors version numbering systems may vary, all of the supported platforms have native C++ compilers that are based on AT&T s 3.0 cfront. In order to ensure portability, all C++ code written using the toolkits should conform to the 3.0 standards as defined in either The Annotated C++ Reference Manual (commonly known as the ARM ), Ellis/Stroustrup or The C++ Programming Language - Second Edition, Stroustrup, both published by Addison Wesley. NOTE ** It is necessary to contact DataFocus to purchase NuTCRACKER 1.6b SDK, necessary for EPAPI and IHAPI Level II tools development work. Overview Level II Developer s Tools 1-4 Software Release Notice 5.0 Rev 1

15 New Features New Features These sections describe new features incorporated into the Level 2 Toolkits. Management Station Access Provider External Protocol Interface (MSAP/EPI) 1. The EPI is used to change model status in the VNM, via unsolicited messages. SpectroSERVER Application Program Interface (SSAPI) 1. Attribute extensions no longer have to be declared DB_KEYED or MEM_KEYED to be seen by searches. 2. An enhanced protocol in SSAPI has been developed to negotiate the highest VPAPI version with the server. 3. SSAPI supports three new functions to acknowledge alarms. Use function CsUIAlarm::ack_alarm_async() or: CsUIAlarm::ack_alarm() to take advantage of the new alarm acknowledgment functionality when using asynchronous SSAPI. Use function CsSYAlarm::ack_alarm_sync() to acknowledge alarms when using synchronous SSAPI. 4. It is now possible to return only primary alarms for each model. A primary alarm is the first alarm that determines the overall condition of the model. 5. A time filter (CsDateTimeFilterNode) can be placed on a SSAPI event log attachment that filters out all events not within the specified range. The filter node interface is defined in vpapi/include/csdatfnode.h. 6. New list handling functionality now exists; LIST type attributes function as arrays. In previous versions of SPECTRUM, only a single value could be stored in a LIST attribute. Now, multiple values can be stored in a LIST attribute. Furthermore, the LIST flag can be used for attributes other than external attributes. 7. Functionality now exists allowing SS API to connect to older version servers. 8. To avoid request time-outs during sophisticated filtering of events, a limit to the number of events or stats searched now exists. If the limit is hit, a new error code is returned. The application sends a follow-on request if more data is needed to complete the search E19 Overview 1-5

16 New Features Inference Handler Application Program Interface (IHAPI) 9. With the addition of the OR operator for filters, and two new filter nodes (CsAlarmListFilterNode and CsEventListFilterNode), it is now possible to build complex filtering expressions. 10. Error messages now contain more information for diagnostic purposes and are more consistent overall. 11. The VNM/landscape map has been extended to include services that are partitioned by the host (the only partition type used to be the landscape handle partition type). An example of such a service would be the processd service. 12. The following changes apply specifically to SSAPI: CsUIModelHandle: read2_async(), read2(), write2_async(), and write2() methods. CsSYModelHandle: read2_sync(), write2_sync() methods. These new read and write pairs process array attributes more efficiently. The new pairs permanently replace the old, original pairs. 13. New infrastructure services include mail service options, SSAPI versioning, security permissions, and SS performance measurements. 14. Improvements on porting, including the addition of a native isolate layer. Inference Handler Application Program Interface (IHAPI) 1. CsVnmModelTypeHandle and CsVnmModelHandle provide new read() and write() methods. 2. A new IHAPI has_group method allows management modules and applications to query whether a given Attribute Group exists (originated/ inherited) as a Model Type. The has_group interface tells the caller if a model type has the specified group. SSAPI and IHAPI 1. The number of bytes stored in an attribute value is now unlimited. Large attribute value writes done through SSAPI and IHAPI will now succeed. 2. Attribute lookup by OID can now be accomplished with IHAPI and SSAPI. 3. Any IHAPI or SSAPI calls that return Attributes will no longer return Attribute Groups. Attribute Groups are now a distinct entity. Overview Level II Developer s Tools 1-6 Software Release Notice 5.0 Rev 1

17 New Features VnmParmBlock Application Program Interface (VPAPI) VnmParmBlock Application Program Interface (VPAPI) 1. VPAPI toolkit supports two new functions to acknowledge alarms: CsAlarm::get_acknowledged() and CsAlarm::set_acknowledged() Use these functions to retrieve and set the acknowledged attribute. 2. VPAPI toolkit adds one new class for filtering alarms: CsBooleanFilterNode. It is used to define an individual element of a filter that compares CsTboolean values. 3. Unlimited length of Events and Stats: There is no longer a limit to the number of CsVarData objects that can be in a single CsEventMessage. The values are no longer truncated. There is no longer a limit to the packed size of the CsEventMessage. Other Toolkit Information Cabletron Systems now ships the gmake executable with Level II Toolkits. Now developers will have the same version of gmake Cabletron uses to test these toolkits. The gmake executable can be found in the $SPECROOT/bin directory. NOTE The SDK developer must use gmake rather than make to build SDK demos or examples. For SPECTRUM 5.0, another new toolkit, Map API, was introduced. Refer to the SPECTRUM Map API Reference for more information on this toolkit E19 Overview 1-7

18 New Features Other Toolkit Information Overview Level II Developer s Tools 1-8 Software Release Notice 5.0 Rev 1

19 Chapter 2 Corrected Anomalies What Is in This Chapter This chapter lists the known irregularities or anomalies that have been corrected for Release 5.0 of the SPECTRUM Level II Developer s Tools. Corrections are listed under the toolkit with which the anomaly was associated. SpectroSERVER API (SSAPI) Toolkit 1. Changes have been made to the Level II toolkit demos; you can now build complete demos with these toolkits E19 2-1

20 SpectroSERVER API (SSAPI) Toolkit Corrected Anomalies Level II Developer s Tools 2-2 Software Release Notice 5.0 Rev 1

21 Chapter 3 Known Anomalies What Is in This Chapter This chapter lists the Level II Developer s Tools known anomalies for this release of SPECTRUM. The anomalies (and solutions or workarounds wherever feasible) are listed under the individual toolkits. Inference Handler Application Program Interface (IHAPI) NOTE DataFocus NuTCRACKER 1.6b SDK is required for IHAPI Level II toolkit development on NT. Contact DataFocus directly to purchase DataFocus NuTCRACKER 1.6b SDK. NOTES The IHAPI demo is not supported on NT, because of DataFocus NuTCRACKER 1.6b SDK compiler issues. However, the demo source code serves as example code for developers who purchase DataFocus NuTCRACKER 1.6b SDK to develop with the IHAPI Level II toolkit E19 3-1

22 What Is in This Chapter SpectroSERVER Application Program Interface (SSAPI)/View Application Program Interface SpectroSERVER Application Program Interface (SSAPI)/View Application Program Interface (VWAPI) Problem 1: AsyncDemo fails on NT. AsyncXDemo, however, does function correctly. Solution: AsyncDemo will be fixed in a future release. Problem 2: DataFocus NuTCRACKER 1.6b SDK should not be installed in C:/Program Files for NT SSAPI. DataFocus NuTCRACKER 1.6b SDK does not interpret the space between Program and Files, and thus cannot read the files. Solution: This problem will be fixed in a future release. External Protocol Application Program Interface (EPAPI) NOTE DataFocus NuTCRACKER 1.6b SDK is required for EPAPI Level II toolkit development on NT. Contact DataFocus directly to purchase DataFocus NuTCRACKER 1.6b SDK. Known Anomalies Level II Developer s Tools 3-2 Software Release Notice 5.0 Rev 1