Command Line Interface Software Release Notice 5.0rev1

Transcription

1 Command Line Interface Software Release Notice 5.0rev1

2 Summary of Changes Version Date Reason/Rational Nature of Changes E17 8/25/98 Technical accuracy. Updated Platform Requirements in Chapter 1. Command Line Interface Software Release Notice 5.0rev1

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 August, 1998 by Cabletron Systems, Inc. All rights reserved. Printed in the United States of America. Order Number: E18 Cabletron Systems, Inc. P.O. Box 5005 Rochester, NH SPECTRUM, SpectroGRAPH, and SpectroSERVER are trademarks of Cabletron Systems, Inc. C++ is a trademark of American Telephone and Telegraph, Inc. UNIX is a trademark of UNIX System Laboratories, Inc. Microsoft, Windows & Windows NT are trademarks of Microsoft, Inc. Intel and Pentium are trademarks of Intel Corporation. OSF/Motif and Motif are trademarks of the Open Software Foundation, Inc. X Window System is a trademark of X Consortium, Inc. Ethernet is a trademark of Xerox Corporation E18 i

4 Virus Disclaimer 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. 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. ii Command Line Interface Software Release Notice 5.0rev1

5 Contents Preface How to Use This Guide...v Typographical Conventions... vi Version Control... vii Questions About SPECTRUM Documentation... viii Chapter 1 System Requirements Product Description Platform Requirements Software and Hardware Requirements Chapter 2 Considerations and Known Anomalies CLI Considerations CLI/SpectroSERVER Considerations To Avoid Corrupting the Database: To Ensure Reliable Performance: CLI Anomalies Anomalies For NT Only E18 iii

6 Contents iv Command Line Interface Software Release Notice 5.0rev1

7 Preface This chapter describes the purpose and content of this document, the SPECTRUM version control scheme, and additional information about SPECTRUM documentation. How to Use This Guide This Software Release Notice (SRN) accompanies each copy of the release package of the SPECTRUM Command Line Interface (CLI) application. The SRN is organized as follows: Chapter Description Chapter 1 System Requirements Chapter 2 Considerations and Known Anomalies This chapter describes the hardware and software requirements for this release of the Command Line Interface. This chapter lists considerations and software problems with their solutions. A new SRN will be 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 SPECTRUM products, consult the SPECTRUM Installation Guide and any README file(s) and/or hardcopy instructions included with the installation CD(s) E18 Preface v

8 Typographical Conventions Typographical Conventions The following typographical conventions are used in this guide: Convention Description Monospaced typeface Bold monospaced typeface Italic monospaced typeface Italic typeface Bold italic typeface Command names, file names, code examples, and text displayed on-screen appear in monospace typeface. In anomaly descriptions, a bold monospaced typeface is used to emphasize the name of the command or process involved. In error message examples, a monospaced italic typeface is used to indicate parameters that vary depending on the circumstances. For example: connect: landscape_handle: not responding or not permitting access. Referenced chapter titles and section headings appear in italics (hypertext-blue italics for on-line readers). Referenced SPECTRUM publications appear in bold italics. Preface vi Command Line Interface Software Release Notice 5.0rev1

9 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. Major Release Minor Release Descriptor Revision Build 2.0 rev 3.17 Major Release. Increments to the number in this field represent major changes in the product s design, functionality, or user interface. Major releases are planned well in advance and occur no more frequently than once per year. Minor Release. 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 may occur one or more times per year. Descriptor. 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). Revision. This field is incremented for subsequent revisions to a release and is reset to zero for each new major/minor release. Build. This field is primarily used for internal tracking of individual builds under a particular revision and is not usually visible to the customer. You will encounter build numbers only in conjunction with alpha and beta test releases or special, limited distribution support releases E18 Preface vii

10 Questions About SPECTRUM Documentation Questions About SPECTRUM Documentation Send your questions, comments or suggestions regarding SPECTRUM documentation to the Technical Communications Department directly via the following internet address: You can download SPECTRUM documentation from: Preface viii Command Line Interface Software Release Notice 5.0rev1

11 Chapter 1 System Requirements This chapter describes the hardware and software requirements for this release of the Command Line Interface. Product Description The SPECTRUM Command Line Interface (CLI) provides access to SpectroSERVER in situations where it is not possible or desirable to use SpectroGRAPH. For example, CLI allows users who have character-based terminals to remotely access SpectroSERVER. The Command Line Interface provides a set of commands which enable a user to perform many operations that otherwise can be performed only through SpectroGRAPH. Furthermore, programmers can incorporate CLI commands into shell scripts or menu systems to give the user an even more powerful and versatile interface. Platform Requirements CLI runs on all SPECTRUM 5.0rev1 platforms, which include: Intel-based PCs running Microsoft Windows NT 4.0 with Service Pack 3 and 150 MHz (or greater) Pentium P6 CPU. Sun SPARCstations running Solaris (or greater) with X11R5 or Sun SPARCstations running Solaris 2.6 with X11R6. For more information about platforms, see the SPECTRUM 5.0rev1 Software Release Notice E18 1-1

12 Software and Hardware Requirements Software and Hardware Requirements There are no additional software or hardware requirements for the SPECTRUM Command Line Interface over and above the requirements for SpectroGRAPH and SpectroSERVER. CLI 5.0rev1 requires network access to SpectroSERVER 5.0rev1 or greater. SpectroGRAPH 5.0rev1 or greater must be installed on the system running CLI for expanded event and alarm information to be available. System Requirements Command Line Interface 1-2 Software Release Notice 5.0rev1

13 Considerations and Known Anomalies Chapter 2 This chapter lists considerations and software problems with their solutions. CLI Considerations You should be aware of the following CLI characteristics and requirements: CLISESSID When you execute a CLI command on a workstation and OpenWindows, CLI may display the following error message: connect: variable CLISESSID not set If you receive this message, set the environment variable CLISESSID to a unique numeric value for each CLI user. One way of doing this is to set CLISESSID to $$ (the process ID of the current shell) either from the command line or from within a CLI script. See the synopsis for the connect command in the Command Line Interface User s Guide for an explanation of the CLISESSID variable. show Because some output for the show commands is longer than 80 characters, output may wrap to the next line. If you do not want output to wrap, increase the window size. \ If you have a command line greater than 256 characters, use the command line continuation character \ to enter the full command E18 2-1

14 CLI/SpectroSERVER Considerations model handle If you enter an invalid model handle, CLI may display the error message: 0: Invalid landscape handle In CLI, the landscape handle is part of the model handle. If you receive an error message about a landscape handle after you enter a model handle, the error message is indicating that the landscape portion of the model handle is invalid. Verify the landscape portion of the model handle and then enter the correct model handle. CLI/SpectroSERVER Considerations You should be aware of the following CLI/SpectroSERVER considerations when using CLI. Because CLI allows a user to make changes directly to the SPECTRUM knowledge-base, information that is incorrectly entered can cause problems for SPECTRUM. As with other UNIX command-line functions, the user must exercise caution to prevent unexpected and undesired results. To Avoid Corrupting the Database: Do not create associations that are inconsistent with SPECTRUM rules. For example, do not associate a device to the World. Do not use the create or update command to write an incorrect type of attribute value to the database. For example, do not write an integer for a string. Do not enter incorrect attribute values while using the create or update command. Be especially careful about attribute values with octet strings; some of these have arbitrarily complicated internal structures. These should only be written to if you fully understand the structure. You can determine the structure by running a describe request using the SSAPI or by using the MTE or the show attributes command to check that the attribute value is not shared. Do not create an association between a model and itself. For example, do not locate a room in itself. Considerations and Known Anomalies Command Line Interface 2-2 Software Release Notice 5.0rev1

15 CLI/SpectroSERVER Considerations Do not create circular or recursive associations. For example, do not associate room1 to room2, room2 to room3, and then room3 to room1. Do not create duplicates of the models at the top of the hierarchies. For example, do not create another Top_Org, Universe, or World model. Do not create a duplicate VNM model. Do not write to locked models. Check to see if models are locked before you write to them. It is important to note that the SPECTRUM Level II Developer s Tools allow users to lock models. Therefore, exercise caution when you run CLI against a SpectroSERVER host that has other applications using Level II development tools running against it. To Ensure Reliable Performance: Do not relate more components to a model than its design allows. Be aware of the characteristics and limitations of a model before creating associations. For example, do not associate more than 8 MIMs to an MMAC8. Do not remove ADMIN, 0 community strings from all user models. This leaves the database without any system user, including the user who could add or update system privileges. Do not clear alarms that are defined as not user-clearable. This can cause unreliable alarm determinations. For example, yellow duplicate IP alarms are user-clearable, but red disconnect ones are not except with CLI. Do not clear red disconnect alarms with CLI. Do not delete many models in one request. This can cause the SpectroSERVER to timeout. Limit deletion requests to fewer than 50 models. On Windows NT, limit the number of models you delete at one time or wait for each deletion to be completed before deleting another model. When you delete many models in sequence, you may receive conflicting responses. CLI indicates that the destroy command has been successful with the message, destroy model: successful. However, if you then use the show models command, you may still see the models in the SPECTRUM knowledge base. This occurs because CLI hasn t finished deleting the models E18 Considerations and Known Anomalies 2-3

16 CLI Anomalies Do not make simultaneous requests for responses. This could cause a socket full problem, SpectroSERVER timeout, or an out of memory condition. If you have timeouts or high memory use in the SpectroSERVER, limit the number of CLI scripts running at one time. Do not create an alarm with inconsistencies between alarm conditions and causes. This could result in questionable status reliability. For example, don t create an alarm that is GREEN and CONTACT_LOST. CLI Anomalies The following is a list of the currently known CLI software problems with solutions for dealing with them. 1. Problem: Although output values for the instance ID from the show attributes command appear in hexadecimal notation, you have to input values for the instance ID from the show attributes command in decimal notation. If you input hexadecimal values, CLI displays error messages. cmdp Convert hexadecimal values to decimal before entering instance ID values. 2. Problem: If you use the show attributes command to display the attribute values of specified instance IDs for more than one list attribute and in the process enter an invalid instance ID, you may receive an incorrect error message. When you enter the invalid instance ID, CLI displays the error message, Invalid attribute id, for that attribute. The error message should say, Invalid instance id. cmdp Only use the show attributes command to display the attribute values of specified instance IDs for more than one list attribute when you are certain the instance IDs are valid for the corresponding attribute. Considerations and Known Anomalies Command Line Interface 2-4 Software Release Notice 5.0rev1

17 CLI Anomalies 3. Problem: CLI only updates its copy of the SPECTRUM landscape map every hour. As a result, CLI might not have the most up-to-date copy of the landscape map if the map has just been modified. In this situation, if you use a command that includes the landscape argument, you may receive an error message saying Invalid landscape handle. cmpd If you want to access a landscape that has just been added to the landscape map, first use the show landscapes command to see if the landscape exists. (The show landscapes command displays the up-to-date information about the SPECTRUM landscape map.) Then, if the landscape does exist, disconnect all users and connect again. When the first user enters the connect command, CLI will get an up-to-date copy of the landscape map. However, if you do not want to disconnect all users and then connect, wait until an hour has passed since the first user connected. CLI will update the map at this time. 4. Problem: CLI may not work correctly in fault tolerant environments. cmdp To be fixed in a future release. 5. Problem: If the first user to connect doesn t have a user model on some landscapes in the landscape map, additional users will not be able to connect to those landscapes even if they have user models on those landscapes. CLI users will be able to connect to only the landscapes that the first user can connect to. These additional users will receive the error: cmdp connect: landscape_handle: not responding or not permitting access. Make sure the first user has a user model on all landscapes in the landscape map. If errors occur, run StopShd after warning users that you are going to disconnect them. Then have a user with a user model on all landscapes be the first user to connect E18 Considerations and Known Anomalies 2-5

18 CLI Anomalies 6. Problem: The CLI Local Server (VnmShd) terminates in the following situation: The first user connects to a SpectroSERVER. Then another user who doesn t have a user model in the landscape for the initial SpectroSERVER tries to run a CLI command against the initial SpectroSERVER. The second user receives a No model for user error in response to his request. The first user to connect receives the following error messages in his xterm window: dvbug151 ssapi sscor Landscape 0x : no model in SpectroSERVER to match user. Initial SpectroSERVER: no model in SpectroSERVER to match user. The following error is displayed in the console window where the Local Server is running: VnmShd: Error: Lost connection with SpectroSERVER. Exiting... Make sure landscapes have the correct user models. Then reconnect. 7. Problem: The CLI Local Server (VnmShd) terminates if the SpectroSERVER to which the first user is connected goes down. cmdp Users must reconnect. 8. Problem: On all platforms (and especially NT), if multiple CLI users (whether it be scripts and/or multiple windows running CLI on the same workstation) are executing CLI client commands at the same time, then some of the requests may timeout with errors. These errors are similar to the following two errors returned by the show events command:./show events Nov 15 8:40:56 ERROR at CsCifFrn.cc(949): Handshake timeout show: failed to connect with VnmShd, please run connect first Reduce the number of CLI users running on the same system. Considerations and Known Anomalies Command Line Interface 2-6 Software Release Notice 5.0rev1

19 Anomalies For NT Only Anomalies For NT Only 9. Problem: If the CLI Local Server is connected to a SpectroSERVER that is unexpectedly shut down, the following message may appear continuously in the window where the first connect command was entered: cmdp CsMailServiceInit::is_message_deliverable:unexpected Cif error; errno=58 Kill the CLI Local Server (VnmShd). 10. Problem: The CLI Local Server and the CLI command both echo error messages to the controlling terminal. If they write messages simultaneously, the messages appear garbled. cmdp To be fixed in a future release. 11. Problem: Invoking Ctrl-C during the execution of a CLI command can cause the CLI Local Server to terminate if the command is running in the window where the CLI Local Server was started. cmdp Start the CLI Local Server (VnmShd) in a separate window before using any commands. Then run CLI commands in another window E18 Considerations and Known Anomalies 2-7

20 Anomalies For NT Only Considerations and Known Anomalies Command Line Interface 2-8 Software Release Notice 5.0rev1