Titlepage. Database Management. SPECTRUM Enterprise Manager SPECTRUM Management

Transcription

1 Titlepage Database Management SPECTRUM Enterprise Manager SPECTRUM Management

2 Notice Aprisma Management Technologies, Inc. (Aprisma) 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 Aprisma 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 APRISMA, ITS EMPLOYEES, OFFICERS, DIRECTORS, AGENTS, OR AFFILIATES 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 APRISMA HAS BEEN ADVISED OF, KNOWN, OR SHOULD HAVE KNOWN, THE POSSIBILITY OF SUCH DAMAGES. Copyright January 2001 by Aprisma Management Technologies, Inc. All rights reserved. Printed in the United States of America. Order Number: Aprisma Management Technologies, Inc. 121 Technology Drive Durham 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 Aprisma or its affiliates. C++ is a trademark of American Telephone and Telegraph, Inc. UNIX is a trademark of UNIX System Laboratories, Inc. 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. Virus Disclaimer Aprisma makes no representations or warranties to the effect that the Licensed Software is virusfree. Aprisma 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. Database Management Page 2

3 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 Aprisma Management Technologies, Inc. 121 Technology Drive Durham 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 archival 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) 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. (d) 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. (e) This Notice shall be marked on any reproduction of this computer software, in whole or in part. Database Management Page 3

4 Contents Contents Contents Overview 6 SpectroSERVER Database...6 Database Manager...7 Database Access...7 Distributed Data Manager Database...10 Archive Manager...10 SpectroSERVER Database Maintenance 13 Database Backups...13 Online Backup...13 Online Backup Disk Requirements...14 Backup File Maintenance...15 Configuring Online Backup...15 Restoring Your Database with Online Backup Files...19 Online Backup Events and Alarms...20 Manual Backup...22 Creating a Complete Backup...22 Creating a Split Backup...23 Restoring Your Database...24 Loading a Database...24 Initializing and Loading a Database...26 Loading Developer Information...28 Removing a Database Lock...29 Importing and Exporting Model Types...30 Recovering from Database Corruption...32 SpectroSERVER Database Troubleshooting...33 SPECTRUM Database Tools...36 db_remove...37 dbtool...40 MapUpdate...42 HostUpdate...42 reports...43 SSdbcompact...48 Database Management Page 4

5 Contents Contents SSdbload...49 SSdbsave...55 DDM Database Maintenance 57 Database Backup...57 post_olb_script...58 ddm_save...59 ddm_backup...59 Points To Remember about Backups...59 Database Restoration...60 ddm_load...60 Points To Remember about Restorations:...61 Archive Manager Resources...62 DDM and Archive Manager Troubleshooting...64 Reports and Data Export Applications...64 Other Applications and Views That Access Events Data...66 Error Messages in ARCHMGR.OUT...67 Index 68 Database Management Page 5

6 Overview This section provides an overview of SPECTRUM database maintenance and discusses both the SpectroSERVER (SS) and Distributed Data Manager (DDM) databases. This document discusses SPECTRUM database management in terms of a distributed network environment involving multiple SpectroSERVERs. Although distributed computing is becoming an industry standard, the information provided here can be adapted for non-distributed environments as well. Distributed database management in SPECTRUM includes several levels of SPECTRUM database maintenance. Various modeling rules and procedures must be followed, and numerous applications can be used to manage a distributed SPECTRUM network and its associated databases. This document describes maintaining both the local database that is part of each SpectroSERVER and the historical databases that represent multiple SpectroSEVERs. SpectroSERVER Database The SpectroSERVER database is located in SPECTRUM s SS directory and contains the following: a modeling catalog (model types and relations) that is the structure for all network information created models belonging to this SpectroSERVER a storage area for network events and statistics When you open a SpectroGRAPH view and see an icon representing a network device, the information provided through the icon is retrieved from a model (i.e., a software simulation) of the actual device. The model is maintained within the SpectrioSERVER database with information Database Management Page 6

7 Overview from several sources. Model types, rules, relations, and attributes are defined through the Model Type Editor. Models and associations are defined using SpectroGRAPH. Information that is to be retained from one execution of SpectroSERVER to the next is also stored in this database. Database Manager As shown in Figure 1, SpectroSERVER s Database Manager controls communications between client applications, such as SpectroGRAPH, and the modeling layer surrounding a network model database management system (DBMS). The model types, models, relations, and associations of SpectroSERVER provide an object model over this network database, thus forming a highly efficient object-oriented database. The development of this shell architecture provides an object-oriented database while retaining the performance advantages offered by a network model database. Database Access As shown in Figure 1, the SpectroSERVER database is accessible at three different levels: At the lowest level, there is a database management system (DBMS), which can be accessed by the SpectroSERVER Database Manager, the Model Type Editor, and a limited set of database tools. At the middle level, the SpectroSERVER Database Manager provides access to the modeling layer of the database for SpectroGRAPH, applications, and other SpectroSERVER features, such as Inference Handlers and the Archive Manager. At the highest level are the specific applications such as SpectroGRAPH and Alarm Manager that provide a user interface for human access to database information. Database Management Page 7

8 Overview Concurrent access to the SpectroSERVER database by multiple users of Aprisma-developed programs is not permitted. SPECTRUM applies a soft lock file (.VNMDB.LOCK) to prevent access from more than one Aprismadeveloped application at the same time. Under certain circumstances (for example, recovering from an abnormal shutdown), the soft lock file can be removed. Refer to Removing a Database Lock (Page 29) for more information on removing the lock. Caution: When Aprisma-developed applications encounter a database lock file, an error message is generated to alert you to the situation. However, non-aprisma tools/applications may not check for this lock and thus will not generate any message. Furthermore, if these non-aprisma entities are able to bypass the lock, database corruption may result. Therefore, before allowing any non- Aprisma tools/applications to access a SPECTRUM database, you should make sure that all SPECTRUM processes are shut down. Database Management Page 8

9 Overview Figure 1: Database Access Model Type Editor Modeling Catalog DDM Database Archive Manager Applications SpectroGRAPH Views Icons Model Types Attributes Relations Rules S SA P I SpectroSERVER Events Manager Statistics Manager Inference Handlers Database Manager DCM I P n r t o e t r o f c a o c l e s SNMP ICMP EPI Other Keys DB Tools Save/Restore Model Information DBMS Modeling Layer SpectroSERVER Database Model Information -Alarms - Events - Modeling Catalog Report Applications Reports Your Network dbtool db_remove HostUpdate MapUpdate reports SSdbcompact SSdbload SSdbsave Import and export model types. Remove obsolete model types from the database. Remove host entry from landscape map. Removes database. Display modeling catalog information. Compress history files. Restore database from a backup file. Save database to a backup file. Database Management Page 9

10 Overview Distributed Data Manager Database Distributed Data Manager Database Each SpectroSERVER has a Distributed Data Manager (DDM) database (located in the server s SS/DDM directory) for storage of SPECTRUM events and statistics data that can be used across multiple landscapes (see Distributed SpectroSERVER for more information). Client applications, such as SPECTRUM Reports and SPECTRUM Data Export, can then request, receive, and collate the data by landscape. Like the SpectroSERVER database, the DDM database cannot be accessed concurrently by multiple users of Aprisma-developed programs. SPECTRUM applies a soft lock file (.DDMDB.LOCK) to prevent access from more than one Aprisma-developed application at the same time. Under certain circumstances (for example, recovering from an abnormal shutdown), the soft lock file can be removed. Refer to Removing a Database Lock (Page 29) for more information on removing the lock. Caution: When Aprisma-developed applications encounter a database lock file, an error message is generated to alert you to the situation. However, non-aprisma tools/applications may not check for this lock and thus will not generate any message. Furthermore, if these non-aprisma entities are able to bypass the lock, database corruption may result. Therefore, before allowing any non- Aprisma tools/applications to access a SPECTRUM database, you should make sure that all SPECTRUM processes are shut down. All communications between the DDM and SpectroSERVER databases and between the DDM database and client applications are controlled by the Archive Manager, which is described in the following section. Archive Manager Each landscape has an Archive Manager server that retrieves events and statistics data from the SpectroSERVER, compresses them, and stores them in the DDM database. Compressed data allows more performance Database Management Page 10

11 Overview data to be kept online, as well as decreasing the network traffic between the applications and the DDM database. As shown in Figure 2, if the SpectroSERVER cannot contact the Archive Manager, events and statistics data will be stored by the SpectroSERVER until contact is reestablished. The SpectroSERVER will then send the data to the Archive Manager to be compressed and stored. The amount of data that will be stored by the SpectroSERVER is determined by the Events and Statistics Archive options in the.vnmrc file (see Defining SPECTRUM Resources). The length of time historical data will be stored in the DDM database is determined by options in the.configrc file (see Archive Manager Resources on Page 62). The Archive Manager can also provide the following information in response to requests from client applications: A list of landscapes on which information is available. For each landscape, the time range of the information available on the landscape and a list of model types for which information is available. For each model type, a list of models for which information is available. For each model, a list of attributes for which information is available. Statistical data in the specified time range. Event data in the specified time range. Database Management Page 11

12 Overview Figure 2: Interaction Between SpectroSERVER and DDM Databases SpectroSERVER Model Name Landscape SPECTRUM Reports SPECTRUM Data Export Client application(s) request data from the Archive Manager Archive Manager retrieves historical data from the SpectroSERVER If the Archive Manager cannot be contacted, SpectroSERVER stores historical data temporarily Archive Manager Archive Manager retrieves ÿ data from the DDM database and forwards the data to the requesting application(s) ÿ Archive Manager retrieves stores retrieved data in the DDM database Modeling Catalog Model Data Historical Data Historical Data SpectroSERVER Database When contact with the Archive Manager is reestablished, the data is forwarded to the Archive Manager for storage DDM Database Database Management Page 12

13 SpectroSERVER Database Maintenance This section describes database maintenance procedures for the SpectroSERVER database. Maintenance procedures for the Distributed Data Manager (DDM) database are covered separately in a subsequent section. Database Backups Creating regular backup copies of your database is the foundation of database maintenance. A reliable backup copy of your database can help you restore the integrity of your database following power failures or other system interruptions. SPECTRUM offers two main ways of performing backups of the SpectroSERVER database: automatically, with the SpectroSERVER running (see Online Backup) manually, with the SpectroSERVER shut down (see Manual Backup on Page 22) Caution: The database backup methods described in this section (Online Backup and the SSdbsave utility) are the only supported methods of backing up your SpectroSERVER database. Use of third-party backup software may result in database corruption. Online Backup SPECTRUM s Online Backup feature lets you create a backup copy of your SpectroSERVER database without having to shut down the SpectroSERVER. Depending on the requirements of your particular network environment, you can perform online backups on demand, or you can schedule backups to be performed automatically on a regular Database Management Page 13

14 basis. Where disk space is limited, Online Backup can be configured to automatically compress backup files using the GNU gzip utility. Note that Online Backup saves the entire database, including the modeling catalog and models. Online Backup does NOT save: Cached Event information Cached Statistics information Historical records in the DDM database (see note below) SpectroSERVER resource file (.vnmrc) Activity associated with Online Backup is recorded as events associated with the VNM model. SPECTRUM reports errors encountered during backup as alarms (see Online Backup Events and Alarms on Page 20). Online Backup performs a save in two major steps: a copy is made to preserve a snapshot of your database files, then this copy is saved (and compressed if required) using the same format as the manual database save utility, SSdbsave. Polling, trap handling, and network management activities are suspended during the first step (copying database files). While this is a relatively short process, you should still consider these interruptions to determine how often and when to schedule automatic save operations. The time required to perform copy depends on your workstation hardware and the size of the database. Note: Although the Online Backup does not, by itself, save the DDM database, you can configure the post_olb_script (Page 58) to execute automatically and save the DDM database whenever an Online Backup of the SpectroSERVER database is performed. Online Backup Disk Requirements The minimum disk space threshold for Online Backup is established by the value of the attribute MinimumDiskSpaceMB. The default threshold value is 20 MB. If an automatic backup is initiated when the available Database Management Page 14

15 disk space is less than the threshold (20 MB), a yellow alarm is generated with a probable cause that indicates a backup failure due to low disk space. Backup File Maintenance When automatic backups are enabled, backup files can accumulate in your backup directory and deplete available disk space. To avoid backup failures, files must be deleted occasionally or else moved to a more permanent storage medium. Configuring Online Backup All of the Online Backup configuration parameters are available from the Online Database Backup Configuration View (Figure 3). To access this view: 1 Navigate into the Universe Topology view and select the VNM icon. 2 From the VNM icon s Icon Subviews menu, select Backup Database. The Online Database Backup Configuration view appears. Database Management Page 15

16 Figure 3: Online Database Backup Configuration View Landscape 0x VNM Scape#1 - On-LineBackup of type On-LineBackup * File View ÿþýüþûúùø øöøõûúôøóòñðúïîþíüìñëø üîþúêüûé Begin Backup Now! Backup Configuration Backup Compression... Disable Prefix for Backup File Name... db Backup Directory... /usr/spectrum/ss-db/backup Minimum Required Disk Space (MB) 20 Automatic Backup Setup Automatic Backups... Backup Interval (Hours) Disable 24 (Minutes) Next Backup Date & Time Mon Aug 07 19:00: Time Zone EDT 0 Status Ready Events Alarms The following buttons and settings appear in the Online Database Backup Configuration View: Begin Backup Now! Clicking this button starts a database backup immediately, assuming you have not changed any of the settings within this view; if so, you will be prompted to either save or discard the changes via the File menu. The button label changes to Working... while the backup is in progress. The backup utility first pauses SpectroSERVER operations, then copies and saves the database. Files created by backups are saved according to the configuration parameters specified. Database Management Page 16

17 Backup Compression When this button reads Enabled, backup files are compressed using the compress utility before being written to disk. Compressed files are saved with a.gz suffix appended to the file name. When set to Disabled, the default setting, files are saved uncompressed. Prefix for Backup File Name This parameter is the user-defined portion of the backup file name. SPECTRUM assigns a db_ prefix to backup files by default. However, you can change this to any character string that creates a legal filename for the system where you are running SpectroSERVER. (no entry means that no prefix appears in the filename). The filename suffix indicates the date and time when the backup was executed in the following format: yyyymmdd_hhmm.ssdb [.gz] where: yyyy 4-digit year mm month dd day of the month 1 through 31 hh hour of the day - 1 through 24 mm minute - 00 through 59.gz indicates a compressed backup (compressed files only).ssdb default suffix for all database save files Backup Directory This parameter defines the directory where backup files are stored. It is recommended that you backup to a local directory. The default backup directory path is <SPECTRUM Installation Directory>/SS-DB-backup. Automatic Backups This button enables/disables automatic initiation of the Online Backup feature. If this button is set to Disabled, the Next Backup Date & Time field is blank. Backup Interval When automatic backups are enabled, these entries determine, in Hours & Minutes, the interval between automatic backups. The default interval, which is recommended, is 24 hours and 0 (zero) minutes. Any value can Database Management Page 17

18 be entered for hours and minutes. For example, a one week interval would be 24 X 7 = 168 hours, 0 minutes or, you could enter the same interval as any combination of hours and minutes (0 hours, 10,080 minutes.) Next Backup Date & Time This parameter shows the date and time for the next scheduled backup, when automatic backups are enabled. You can enter a date and time for the first backup; however, subsequent backups will be performed at the interval set by the Backup Interval parameters (Hours and Minutes). To have automatic backups occur at the same time each day, set the interval to 24 hours and 00 (zero) minutes. Date & Time entries are separated by spaces using the following format: ddd mmm nn hh:mm:ss yyyy where: ddd day of the week - Mon, Tue, Wed, etc. mmm month of the year - Jan, Feb, Mar, etc. nn day of the month - 1 through 31 hh hour of the day - 01 through 24 mm minutes - 00 through 59 ss seconds - 00 through 59 yyyy year - e.g., 2001 Note: After entering automatic backup scheduling information, you must select File > Save All Changes in order to put the schedule into effect. Otherwise, the scheduled backup(s) will not occur. Time Zone This read-only parameter indicates the applicable time zone for the specified next backup time. Status This read-only parameter indicates the database backup status as one of the following: Database Management Page 18

19 - Checking setup. - Copying database. SpectroSERVER paused. - Saving copied database. SpectroSERVER resuming normal activity. - Primary backup Successful. Database Synchronization in Progress. - Last backup successful. - Backup failed! (see log file). Events Click this button to open the Event Log. Alarms Click this button to open the Enterprise Alarm Manager. Restoring Your Database with Online Backup Files Uncompressed backup files generated by Online Backup are stored in the same format as files saved using the SSdbsave utility with the -cm option. To restore your database using these files, refer to Restoring Your Database (Page 24). To restore compressed files (i.e., those having a.gz suffix), use the GNU gzip utility to restore the files to the format used by SPECTRUM s SSdbsave utility, then refer to Restoring Your Database. Database Management Page 19

20 Online Backup Events and Alarms The following Events and Alarms are associated with Online Backup. Event Code Event Event Cause 0x OB_EVENT_GEN_FAILURE Database open failure 0x OB_EVENT_GEN_FAILURE Database close failure 0x OB_EVENT_GEN_FAILURE Any other reason causing backup failure 0x OB_EVENT_BACKUP_ON Automatic backups have just been enabled by the user 0x OB_EVENT_BACKUP_STARTED Online Backup started 0x OB_EVENT_BACKUP_COMPLETED Online Backup successfully completed 0x OB_EVENT_NO_FILE_OR_DIRECTORY File/directory does not exist, or does not have read and execute permissions Create Alarm RED RED ORANGE No No No YELLOW ORANGE Database Management Page 20

21 Event Code Event Event Cause 0x a OB_EVENT_NO_CREATE_BACKUP_DIR Can t create backup directory 0x b OB_EVENT_LOW_DISK_SPACE Low disk space, backup failed 0x c OB_EVENT_COPY_FAILED Database copy failure 0x e OB_EVENT_DB_INCONSISTENT Database inconsistency found 0x OB_EVENT_OFFLINE_SAVE_FAILED Off-line portion of the save process failed 0x OB_EVENT_VNM_RESUMED Resuming normal operation, SpectroSERV ER was paused 0x OB_EVENT_BAD_FILENAME Filename specified is not a valid Posix directory name 0x OB_EVENT_DBSYNC_FAILED Attempts to synchronize backup server failed. Create Alarm ORANGE YELLOW RED ORANGE RED No ORANGE ORANGE Database Management Page 21

22 Events generated by a failure, have the exact cause of the failure appended in the event log. For example; If the executable, ob_dbsave, is not found in the SS directory, an event 0x , OB_EVENT_NO_FILE_OR_DIR is generated and ob_dbsave is referenced within the text of the event. Manual Backup You can create a backup of your database manually using the SSdbsave database utility, which is one of the database tools supplied with SPECTRUM (see SSdbsave on Page 55 for a complete listing of options). Your database contains both a catalog of template information used to create models (model types, relations, and rules) as well as models themselves. You can create a backup copy of your database that includes either or both of these components using SSdbsave. A complete save, containing both the modeling catalog and the models, is recommended. Creating a Complete Backup To make a complete backup of your database, including both the modeling catalog (model type hierarchy, relations, and rules) and the models themselves: 1 Navigate to the SpectroSERVER (SS) directory. 2 Make sure that neither SpectroSERVER nor any other program that accesses the SpectroSERVER database is running. Note: When first installed, SSdbsave is located in the SS-Tools directory. If its location is not set in a system path statement, you must use a full path, a relative path, move it, or link it to the same directory with the SpectroSERVER database. 3 Enter the following command to save both the modeling catalog and models:../ss-tools/ssdbsave -cm <save_file> Database Management Page 22

23 The suggested naming scheme for save files is to incorporate a date stamp as well as the flags used for the save. In this case, you are using both the c (catalog) and m (models) flags; therefore, assuming it is October 14, 2000, you would enter db_ _cm as the save file name. A file named db_ _cm.ssdb will then be created, with the.ssdb suffix added automatically. Creating a Split Backup Although the models in your SpectroSERVER database may change on a daily basis, the modeling catalog changes only when you perform an upgrade installation, add new management modules, or make changes directly via the Model Type Editor. Therefore, if you have a very large database, you may wish to save some time by splitting your backups i.e., saving your models on a regular basis, but saving the modeling catalog only after it changes. You then store the backup of the modeling catalog in a safe place, and together with the most recent save of your model information, it provides a complete database backup. The following procedure assumes you wish to perform a split backup of your database on October 14, 2000, creating one save file for your modeling catalog and a separate save file for your models. 1 Navigate to the SpectroSERVER (SS) directory. 2 Make sure that neither SpectroSERVER nor any other program that accesses the SpectroSERVER database is running. Note: When first installed, SSdbsave is located in the SS-Tools directory. If its location is not set in a system path statement, you must use a full path, a relative path, move it, or link it to the same directory with the SpectroSERVER database. 3 Enter the following command to save only the modeling catalog:../ss-tools/ssdbsave -c db_ _c Database Management Page 23

24 Restoring Your Database 4 Enter the following command to save only your models:../ss-tools/ssdbsave -m db_ _m Your modeling catalog will be saved in a file named db_ _c.ssdb and your models in a file named db_ _m.ssdb. Remember that your models should be saved on a regular basis or whenever you make a significant change to your network model. Your modeling catalog should be saved anytime you install a new version of SPECTRUM, add new management modules, or make any catalog changes with the Model Type Editor. Restoring Your Database Your SPECTRUM database consists of a modeling catalog containing the model type hierarchy and relations, models representing entities in your network, and developer information. The SSdbload database utility program is used to: Load previously backed up database files Initialize the database and load previously backed up database file containing a modeling catalog. Load developer information Loading a Database If there is no database corruption, SSdbload -l can be used to load a backup file without first initializing the database. The contents of a file created by the SSdbsave utility and uncompressed files saved using SPECTRUM s Online Backup can be loaded into a database using the SSdbload utility. Note: To restore compressed files (.gz suffix), use the GNU gzip utility to restore the files to the format used by SSdbsave, then continue with the procedures for using SSdbload. Database Management Page 24

25 Restoring Your Database SSdbload reads the save file to determine the types of information saved (modeling catalog and models), removes all the corresponding information from the database, then loads the backup information into the database. For example, when loading a save file containing only models (saved using only the -m option), SSdbload first deletes all model information from the database, then loads the model information from the save file. Similarly, loading a save file containing only the catalog deletes the catalog from the database, then loads the catalog from the save file. If you created separate backup files, with one for the modeling catalog and another containing model information, you must load the catalog (model type and relation) information first, then load the model information. Caution: The -l option CANNOT be used to load additional catalogs or models into an existing database. The -l option does not augment the contents of the database, but determines the content of the save file being loaded and removes any existing information of the same type before loading. To load the database: 1 Navigate to the directory containing the database. 2 Make sure that neither SpectroSERVER nor any other program that accesses the SpectroSERVER database is running. 3 Execute the SSdbload command line providing the name of the file to be loaded into the database structure:./ss-tools/ssdbload -l <filename> Note: When first installed, SSdbload is located in the SS-Tools directory. If its location is not set in a system path statement, you must use a full path, a relative path, move it, or link it to the same directory with the SpectroSERVER database. Database Management Page 25

26 Restoring Your Database 4 If the backup file loaded in Step 2 contained only catalog information, repeat Step 2, substituting the name of the backup file containing the model information. The database is now ready for use. Initializing and Loading a Database When initializing and loading a database in one operation, the -i option is used with the -l option. This is the recommended method for loading new database information from a file saved using the SSdbsave options -c and -m. Initializing the database removes the modeling catalog, model information, vendor information, and unarchived Events Log and Statistics Log records and refreshes all the database files. (To keep the databases in sync, when initializing the SpectroSERVER database, you must also initialize the historical databases using ddm_load. You should always initialize the database if you suspect that the database has been corrupted. With the database initialized, the -l option then loads the new database information (modeling catalog and models) according to the SSdbsave options that were used when the backup file was created. Caution: The -i option removes all models, model types, relations, vendor information, and all unarchived events and statistics log records from the database. When running SSdbload using the -i option, you can load the catalog to start the SpectroSERVER with no models, or you can restore the database completely, either by loading one backup file saved using both the SSdbsave -c and - m options, or by loading a split backup (files saved using -c and - m options separately). If split backups are used, you must run SSdbload once for each backup file being loaded. The -i option must be used only once, with the first SSdbload. The catalog must be loaded before the models. Database Management Page 26

27 Restoring Your Database To initialize and load the database: 1 Navigate to the directory containing the database. 2 Make sure that neither SpectroSERVER nor any other program that accesses the SpectroSERVER database is running. Caution: Use caution if using.after files that are older than the current executables when initializing the database. Information that you are expecting may not be present if the.after files are older than the executables. Refer to SSdbload on Page 49 for an explanation of.after files. 3 Type in the following SSdbload command line:../ss-tools/ssdbload -i -l <filename> The database will be initialized and then loaded with the information from the backup file you specify. The database will then be ready for use. Note: The database tool clean_db has been obsoleted. If you are initializing a clean database, use the SSdbload tool on your /SS/legacy.SSdb file. Database Management Page 27

28 Loading Developer Information Restoring Your Database If you are a registered developer, you are permitted to load developer information (basically a file containing your Developer ID) into the SpectroSERVER database using SSdbload with the -d option. You must reload the developer information after any initialization of the database, but you can only load this information one time in between initializtions. Attempting to execute a second SSdbload using the -d option produces an error message and leaves the developer information unchanged. Caution: Developer information should be loaded into only one database, and all modeling catalog editing should be done on that database. Edits can then be propagated to other databases using SSdbload, if desired. However, loading the same developer information on more than one database can result in duplicate model type, attribute, or relation handles, which will make it impossible to correlate historical data across landscapes. To load developer information to a database: 1 Navigate to the SpectroSERVER (SS) directory. 2 Make sure that neither SpectroSERVER nor any other program that accesses the SpectroSERVER database is running. Note: When first installed, SSdbsave is located in the SS-Tools directory. If its location is not set in a system path statement, you must use a full path, a relative path, move it, or link it to the same directory with the SpectroSERVER database. 3 Enter the following command:../ss-tools/ssdbload -d <developer filename> Database Management Page 28

29 Removing a Database Lock Restoring Your Database Whenever an Aprisma-developed program accesses a SPECTRUM database, it creates a lock file within that database directory. The lockfile in the SpectroSERVER database is called.vnmdb.lock and the lockfile in the DDM database is called.ddmdb.lock. The lock file serves as an indicator that the database is currently in use and cannot be accessed by another Aprisma-developed program. Thefollowing Aprisma-developed programs create a lock file: converter dbtool lh_set mte (Model Type Editor) reports SpectroSERVER SSdbcompact SSdbdelete SSdbload SSdbsave When an Aprisma-developed program reaches normal termination, it automatically removes the lock file. Occasionally, however, an Aprismadeveloped program may be abnormally terminated and the lock file will be left behind. If not removed, the lock file inhibits execution of other Aprisma-developed programs that access the database. When a lock file exists and another Aprisma-developed program is started, the following message is displayed: Database already locked by: <user id>, by process: <process name>, with process ID: <process id>, on network node: <node name>, which started at: <date/time stamp> You can manually remove a.vnmdb.lock or DDMDB.LOCK file that you believe was left behind by an abnormally terminated program, but you should first verify that the program is not in fact still running. If it is still Database Management Page 29

30 Restoring Your Database running (and preventing a higher priority program from accessing the database), you should first attempt to terminate the program normally. If that is not possible, you can stop the program using a UNIX kill command (with no options) or the Windows NT/2000 Task Manager dialog s End Process button. Any of these methods will remove the lock file. If the program was indeed abnormally terminated, you can go ahead and remove the lock file manually by navigating to the SS or SS/DDM directory, as appropriate, and entering one of the following commands: rm.vnmdb.lock (to remove lock from SS directory) or rm DDMDB.LOCK (to remove lock from DDM directory) To maintain the integrity of your database, it is recommended that you restore both your SpectroSERVER and DDM databases any time you are forced to remove a lock file from either the SS or SS/DDM directories. For instructions, see Restoring Your Database on Page 24. Caution: Also remember that VNMDB.LOCK and DDMDB.LOCK files do not prevent database access by non-aprisma-developed programs, and no error message is generated when such programs encounter these locks. Therefore, before allowing any non- Aprisma tools/applications to access a SPECTRUM database, you should make sure that all SPECTRUM processes accessing that database are shut down. Importing and Exporting Model Types As your network grows, you may wish to add model types to your database. In some cases, you may want to add these new model types to your database without installing a completely new database. The dbtool utility allows you to import and export model types and dump (display) the contents of a file containing exported model types. A similar function Database Management Page 30

31 Restoring Your Database is provided by the Model Type Editor; however, the dbtool utility is useful if you want to batch-process a series of exports or imports. If you are a registered developer with your vendor information loaded into the current database, you may only export the modeling catalog and rules created with your Developer ID (a unique four-character ID given to each developer registered with Aprisma Management Technologies). The ID protects the developer s modeling catalog and attributes from being edited and exported by other developers. If you are not a registered developer, you can only export the modeling catalog that was created with the default ID. For more information on exporting and importing model types, refer to the Model Type Editor User s Guide. Database Management Page 31

32 Recovering from Database Corruption Restoring Your Database Several conditions, including hardware failures and power interruptions, can result in a corrupted database and generate an error message such as the following one: Sep 18 15:42:39 ERROR at d:\build\s601\ssdbl.2\rep\src\csss- DbRp.cc(642): table open d:\build\s601\dbutl.2\dal\vendors\berkeley\src\tableimpl.cc:674(0x2) Db::open: No such file or directory Could not open the database. VNM exiting. Landscape not initialized. VNM exiting. Database corruption may also have occurred when the SpectroSERVER or other applications generate error messages not readily attributable to specific causes such as the lack of a user model, the presence of a database lock, etc. If you have maintained a schedule of regular backups, you can usually recover from database corruption with minimal loss of information simply by using the SSdbload utility to initialize your database and reload the last known good save of your database i.e., one that includes both the modeling catalog and models and that was created prior to any indications of corruption. For more information on using this utility, see SSdbload on Page 49. If you do not have a known good save of your database, or if application errors persist after you reload what you believe to be a good save, contact your SPECTRUM Support representative. Database Management Page 32

33 SpectroSERVER Database Troubleshooting SpectroSERVER Database Troubleshooting Here are some of the more common problems reported to SPECTRUM Support by customers. Inappropriate use of the -i option of SSdbload It is extremely important to understand the repercussions of using the -i option of the SSdbload tool. When this option is used, all existing objects in the database are removed. This includes model types, models, relations, attributes, rules, unarchived events; and unarchived statistics. Thus, if you execute: SSdbload -i -l somefile_m.ssdb and the somefile_mssdb file contains only models, the load will fail. If you execute the same command with a file containing only a modeling catalog (i.e., one saved with the -c option only), the resulting database will contain only the model types and relations loaded from the file. All other objects that previously existed in the database would be gone, including all user-created models. Using SSdbload to load old objects, after an install/upgrade Using SSdbload to load old models, model types, or relations, after an install/upgrade can cause serious database problems. The best way to avoid these problems is to understand how SSdbload operates. When you attempt to load a file using the -l option, SSdbload looks at the file to determine the types of objects it contains (which depends on the option flags that were used with SSdbsave to create the file). For each object type in the file (modeling catalog and/or models), SSdbload first removes any existing objects of that type from the database. So, for example, if you execute: SSdbload -l somefile_c.ssdb with the intention of updating a newly upgraded database with your old modeling catalog, you would in fact replace the modeling catalog in the database with one from the save file. This could leave you with an unusable database, since the upgraded Modeling Catalog may be needed Database Management Page 33

34 to operate with the new version of SPECTRUM. Also, any modifications made with the Model Type Editor would be lost. Database transaction files The SpectroSERVER database produces sequentially numbered log files (e.g., log , log , etc.) to support its transactional recovery feature. The SpectroSERVER keeps these log files pruned as much as possible, but occasionally, more than one log file may exist at a particular point in time. Do NOT delete log files (even after the server is shut down), as this may cause log sequence numbers to be reused, thus confusing the transaction processing subsystem (i.e., the database would be placed at greater risk for inconsistency). Copying database files between operating systems/platforms The database files (*.db, *.ix, log.*) are operating system/platform specific. Copying a database from one operating system/platform to another is not supported. The only supported method of moving the data contained in these files is by running SSdbsave on the source machine and SSdbload on the destination machine. As long as these tools exist on each machine, and they were compiled for their respective machines, transfer of data in this manner will be successful. Loading order of the modeling catalog and models It is important to understand that models are essentially instances of model types defined within the modeling catalog and that there is a dependency relationship. If the model type for a given model is not present or is not the correct version, then an attempted load of a file containing that model will fail. Always load any prerequisite modeling catalog before loading models created from that modeling catalog. Adding modeling catalog objects to multiple databases with the same Developer ID When modeling catalog objects (model types, relations, attributes) are added to a database using the Model Type Editor, they are assigned a unique handle composed of the active Developer ID plus the next available sequential number for that object type. However, each database maintains/assigns these sequential numbers independently. Therefore, if Database Management Page 34

35 newly developed objects are also being added to another database using the same Developer ID, the same handle could exist in both databases for different objects. In a distributed SpectroSERVER environment, this kind of conflict would make it impossible to correlate historical data across landscapes. To avoid a problem with duplicate handles, make all changes to modeling catalog information in one database, save them using SSdbsave (with the -c option), and then propagate the changes to other databases as required using SSdbload (with the -l option). UNIX file access permissions on database files and directory For proper operation of SpectroSERVER and other database tools, you must have write permission to all database files (*.db, *.ix, log.*) and the directory containing the database files. If you receive a message from one of the database tools, or SpectroSERVER, indicating that the program was Unable to open lock file, check the permissions on the database files and directory. Database Management Page 35

36 SPECTRUM Database Tools SPECTRUM Database Tools This section describes the following database tools, or utility programs, all of which are located in SPECTRUM s SS-Tools directory: db_remove dbtool (Page 40) HostUpdate (Page 42) MapUpdate (Page 42) reports (Page 43) SSdbcompact (Page 48) SSdbload (Page 49) SSdbsave (Page 55) For each tool, the description identifies any prerequisites, provides examples of command syntax and options, and lists possible error messages. Note: When first installed, all of the tools listed above are located in the SS-Tools directory. If a tool s location is not set in a system path statement, you must either use a full path when using it, or else move it into the same directory with the SpectroSERVER database. Database Management Page 36

37 db_remove This utility program is used to remove obsolete model types (and their associated originating attributes and meta-rules) from the modeling catalog portion of the SpectroSERVER database. Note: This tool is not intended for general customer usage and should not be run except in conjunction with specific instructions/technical bulletins issued by Aprisma Management Technologies. For additional information, contact your SPECTRUM Support representative. Syntax: db_remove [-debug] [<MTH_FILE>] -debug Enables verbose informational message output. <MTH_FILE> Specifie the text file containing a whitespace-separated list of the model type handles to remove from the database. Database Management Page 37

38 Errors: Error Message Warning: Model Type 0x???????? - model type name here could not be removed. Explanation You would see this message in the unlikely event that you (or another vendor/partner) had derived new model types from the model types that are now being removed. If so, you would run the Model Type Editor to see what is derived from this model type, and then move the derived model type(s) to a different, non-obsolete derivation point. You would then rerun the dbremove tool with the original MTH_FILE. Database Management Page 38

39 Error Message Warning: Model Type 0x???????? - model type name here is currently referenced in a default Attribute value. The reference occurs in Attribute 0x???????? - attribute name here, at Model Type 0x???????? - model type name here. Explanation You will see this message if you (or a vendor/partner) added a reference from a default value of an attribute (of MODELTYPE_HANDLE or list-of MODELTYPE_HANDLE to the value of the model type handle being removed. This message does not stop the model type from being removed, but you should investigate the attribute s default value, and depending what it is being used for, remove the reference, or replace it with an appropriate non-obsolete model type handle. Database Management Page 39

40 dbtool This utility program can be used to export or import model types and display (dump) the contents of an export file. Whenever dbtool is run, it loads the database so that symbolic names can be used whenever possible. The export function of the dbtool utility uses one or more files to define the model types to be exported. These files must be created, using a shell text editor such as vi, prior to running export. You must shut down SpectroSERVER and any other program that accesses the SpectroSERVER database before executing dbtool. Syntax: dbtool [dbpart <file>.e [ <file>.e...] ] dbtool [dump <file>.e [ <file>.e...] ] dbtool [dump_mt <file>.e [ <file>.e...] ] dbtool [import <file>.e [ <file>.e...] ] dbtool [export <file>.m [ <file>.m...] ] dbpart Displays a list of octet strings that are not inherited. dump Displays the contents of an export file (either exported from the MTE or a.e-file from a dbtool export operation) in a human-readable form. filename_1.e The name of the file containing model type information to be displayed. Multiple files can be dumped by a single command. These files can be.e-files from a previous export operation or files created using the MTE output file Defines an alternative destination for the dump output (file, printer, etc.). dump_mt - export Creates a file containing model types to be exported. Database Management Page 40