SPECTRUM Data Export (SDE) User s Guide

Transcription

1 Titlepage SPECTRUM Data Export (SDE) User s Guide Document 0971 SPECTRUM Management

2 Copyright Notice Document Copyright present Aprisma Management Technologies, Inc., 273 Corporate Drive, Portsmouth, NH USA. All rights reserved worldwide. Use, duplication, or disclosure by the United States government is subject to the restrictions set forth in DFARS (c)(1)(ii) and FAR Liability Disclaimer Aprisma Management Technologies, Inc. ("Aprisma") reserves the right to make changes in specifications and other information contained in this document without prior notice. In all cases, the reader should contact Aprisma to inquire if any 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, HAS KNOWN, OR SHOULD HAVE KNOWN, THE POSSIBILITY OF SUCH DAMAGES. Trademark, Service Mark, and Logo Information SPECTRUM, IMT, and the SPECTRUM IMT/VNM logo are registered trademarks of Aprisma Management Technologies, Inc., or its affiliates. APRISMA, APRISMA MANAGEMENT TECHNOLOGIES, the APRISMA MANAGEMENT TECHNOLOGIES logo, MANAGE WHAT MATTERS, DCM, VNM, SpectroGRAPH, SpectroSERVER, Inductive Modeling Technology, Device Communications Manager, SPECTRUM Security Manager, and Virtual Network Machine are unregistered trademarks of Aprisma Management Technologies, Inc., or its affiliates. For a complete list of Aprisma trademarks, service marks, and trade names, go to All referenced trademarks, service marks, and trade names identified in this document, whether registered or unregistered, are the intellectual property of their respective owners. No rights are granted by Aprisma Management Technologies, Inc., to use such marks, whether by implication, estoppel, or otherwise. If you have comments or concerns about trademark or copyright references, please send an to spectrum-docs@aprisma.com; we will do our best to help. SPECTRUM Data Export (SDE) User s Guide Page 1

3 Restricted Rights Notice (Applicable to licenses to the United States government only.) This software and/or user documentation is/are provided with RESTRICTED AND LIMITED RIGHTS. Use, duplication, or disclosure by the government is subject to restrictions as set forth in FAR (June 1987) Alternate III (g)(3) (June 1987), FAR (June 1987), or DFARS (c)(1)(ii) (June 1988), and/or in similar or successor clauses in the FAR or DFARS, or in the DOD or NASA FAR Supplement, as applicable. Contractor/manufacturer is Aprisma Management Technologies, Inc., 273 Corporate Drive, Portsmouth, NH In the event the government seeks to obtain the software pursuant to standard commercial practice, this software agreement, instead of the noted regulatory clauses, shall control the terms of the government's license. 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 percent effective, we strongly recommend that you write-protect the licensed software and verify (with an anti-virus system in which you have confidence) that the licensed software, prior to installation, is virus-free. Contact Information Aprisma Management Technologies, Inc. 273 Corporate Drive Portsmouth, NH Phone: U.S. toll-free: Web site: SPECTRUM Data Export (SDE) User s Guide Page 2

4 Contents Preface 8 Getting Started with Data Export 11 Overview...11 SPECTRUM Data Types You Can Export...12 Current Data Types...12 Historical Data...12 Data Export Files...13 Definition (.sde) Files...13 Data Export Script (dtxscript) File...14 Resource File (SDE)...14 The Data Export Process...14 Special Considerations...15 For All Users Landscape Handles and Definition Files...15 General Error Handling...15 Accessing Data Export...16 Describing the Data Export Window 18 Overview...18 Commands Section...20 Menus...20 File Menu Options...20 Edit Menu Options...21 Help Menu Options...21 Icons...21 General Information Section...22 Historical Data Section...24 Current Data...26 Configuring Export Definition Files 28 Overview...28 Opening and Saving Definition Files...29 Opening a Definition File...29 Data Export User s Guide Page 3

5 Contents Saving a Definition File...30 Setting General Information Parameters...32 Specifying Landscapes...32 Specifying an Output Directory...35 Specifying a Post Export Script...36 Setting ASCII Format Options...37 Setting Historical Data Parameters...40 Specifying Events Data...40 Specifying Models...42 Locating Model Types in the Model Types/Models List...42 Selecting Models...43 Selecting Filter Criteria...44 Selecting Event Codes...45 Selecting Alarms...46 Specifying Statistics Data...47 Specifying Models and Common Attributes...47 Specifying Output Parameters...49 Specifying an Output File Name...50 Specifying an Output Mode...50 Specifying an Export Range...50 Custom Range...51 Day Range...54 Week Range...55 Month Range...56 Setting Current Data Parameters...57 Exporting Data 58 Overview...58 Starting an Export Now...59 Scheduling an Export...59 Working with the Scheduler...60 Creating Scheduled Export Commands...61 Describing Scheduled Export Command Entries...63 Modifying Scheduled Export Commands...64 Removing Scheduled Export Commands...64 Checking Export Output...65 Log File...65 Data Export User s Guide Page 4

6 Contents Output Files...67 Sample ASCII Output...67 Data Structure of ASCII Files 68 SPECTRUM Data Types...69 Associations...69 Attributes...69 Events...70 Extended Attributes...71 Model Type Hierarchy...72 Model Types...72 Models...73 Relations...73 Statistics...74 Schema Format...77 Data Export Resource File 79 Exporting To Other Databases 84 Organization Of The Post-Export Parameter File...85 Index 87 Data Export User s Guide Page 5

7 Figures Figure 1: Data Export from the SpectroGRAPH Tools Menu...16 Figure 2: Data Export Window...17 Figure 3: Data Export Window Sections...19 Figure 4: General Information Section...22 Figure 5: Historical Data Section...24 Figure 6: Current Data Section...26 Figure 7: Open File Dialog Box...30 Figure 8: File Selection Dialog Box...31 Figure 9: Landscapes Dialog Box...33 Figure 10: Output Directory Dialog Box...35 Figure 11: Post Export Script Dialog Box...36 Figure 12: ASCII Format Options Dialog Box...38 Figure 13: Events Filter Dialog Box...41 Figure 14: Model Types/Models List...42 Figure 15: Select Event Code(s) Dialog Box...45 Figure 16: Alarm Filter Options Dialog Box...46 Figure 17: Statistics Filter Dialog Box...47 Figure 18: Model Types/Models and Common Attribute Lists from the Statistics Filter Dialog Box 49 Figure 19: Events/Statistics Data Range Dialog Box...52 Figure 20: Events/Statistics Day Range Dialog Box...54 Figure 21: Events/Statistics Week Range Dialog Box...55 Figure 22: Events/Statistics Month Range Dialog Box...56 Figure 23: Scheduler Window...60 Figure 24: Scheduled Export Frequency Options...62 Figure 25: Sample Log File...66 Data Export User s Guide Page 6

8 Tables Table 1: ASCII File Format for Associations...69 Table 2: ASCII File Format for Attributes...69 Table 3: ASCII File Format for Events...70 Table 4: ASCII File Format for Extended Attributes...71 Table 5: ASCII File Format for Model Type Hierarchy...72 Table 6: ASCII File Format for Model Types...72 Table 7: ASCII File Format for Models...73 Table 8: ASCII File Format for Relations...73 Table 9: ASCII File Format for Statistics (Standard Format)...74 Table 10: ASCII File Format for Statistics (List Attribute Format)...74 Table 11: Attribute Types...75 Data Export User s Guide Page 7

9 Preface Describes this manual s audience and user prerequisites, its organizational structure, and its typographical conventions. Welcome to the Data Export User s Guide. This guide describes how to use Data Export to extract SPECTRUM data from SPECTRUM databases and save it to an output directory in ASCII data format. Who Should Read This Guide This guide is intended for network-management personnel who want to extract data from SPECTRUM databases. Prerequisites for Users Data Export users should be familiar with the following elements involved in a SPECTRUM data export: SPECTRUM Distributed Data Manager database concepts. SPECTRUM Model Types and Models. SPECTRUM Data Types. The scheduled tasks application supported by the SPECTRUM host platform (Solaris or Windows NT). Data Export User s Guide Page 8

10 Preface How This Guide Is Organized This guide is organized as follows: Section Description Getting Started with Data Export Describing the Data Export Window Configuring Export Definition Files Exporting Data Data Structure of ASCII Files Describes Data Export capabilities, SPECTRUM data types that can be exported, important Data Export files, special considerations related to using Data Export, and how to access Data Export. Describes the SPECTRUM Data Export window. Describes how to create and save Data Export definition files. Describes how to immediately start an export and how to schedule an export with the Scheduler utility; briefly discusses Windows NT scheduling requirements; describes the output file format. Describes output file format specifications for SPECTRUM data types. Data Export Resource File Describes the Data Export resource file. Exporting To Other Databases Describes how a post-export script can be used to export data to other databases. Typographical Conventions This manual uses the following typographical conventions: Referenced sections of this document appear in italics (hypertext-blue italics for on-line readers). For example: See Icons for more information on the Data Export window icons. Referenced SPECTRUM manuals appear in bold italics. For example: Data Export User s Guide Page 9

11 Preface See the SPECTRUM Installation Guide for SPECTRUM installation procedures. System input, output, parameters, filenames, and directories appear in Courier font. For example: The default database name is specified by the DBDefaultName resource file parameter in the SDE resource file. Referenced application window fields, buttons, and menus and menu options appear in bold. For example: Click the Export Now icon. Note: Calls your attention to information of special importance. Caution: Calls your attention to any action that may adversely effect application performance. Data Export User s Guide Page 10

12 Getting Started with Data Export Describes Data Export capabilities, SPECTRUM data types that can be exported, important Data Export files, special considerations related to using Data Export, and how to access Data Export. Overview Data Export extracts archived events and statistics data from SPECTRUM DDM (Distributed Data Manager) databases and current data for object entities stored in VNM databases. Data Export converts extracted data to an ASCII file format. Data Export connects to a single SpectroSERVER in a distributed server environment and can extract data from any of the landscapes registered with that SpectroSERVER. The data can then be imported into a report generator, database, spreadsheet, or statisticsanalysis application of your choice. Data Export User s Guide Page 11

13 Getting Started with Data Export SPECTRUM Data Types You Can Export SPECTRUM Data Types You Can Export This section briefly describes the SPECTRUM data types that you can export from the SpectroSERVER database and the DDM database. Current Data Types Current data types you can export from a SpectroSERVER database include: Model Types Objects in a SPECTRUM database that represent the different types of network and SPECTRUM elements that can be modeled in SPECTRUM. Model Type Hierarchy A model type s parent and child model types. Models Discrete instances of model types modeled in SPECTRUM. Attributes Characteristics that define the structure of a model type. Extended Attributes Additional attributes that relate models to the SNMP OIDs supported by those models. Associations Instances of relationships between models. Relations Objects that identify the types of associations that can occur between models. Historical Data Archived data types you can export from a DDM database include: Events Model status changes that are logged to a DDM database. Statistics Model performance indices that are logged to a DDM database. Data Export User s Guide Page 12

14 Getting Started with Data Export Data Export Files Note: Historical data for models is logged to the DDM database by the Archive Manager, which administers DDM functions. When Data Export requests DDM data from a landscape, that landscape server s Archive Manager fulfills the request. The Archive Manager, therefore, must be running for the historical-data export to succeed. Data Export Files This section briefly describes important Data Export files you either can or must configure to define Data Export objectives and operational characteristics: Definition files Data Export Script file Resource file Definition (.sde) Files Before you can export data with Data Export, you must first create and save a definition file for the export. A definition file specifies the following export parameters: The landscapes from which to export data. The output format options and the output directory. The types of data to export current data or historical data or both. The historical period from which to export data. Data Export User s Guide Page 13

15 Getting Started with Data Export Data Export Script (dtxscript) File The Data Export Process The dtxscript file enables you to specify the environment variables that may need to be adjusted to influence the behavior of exports. Resource File (SDE) The Data Export resource file, SDE, specifies various Data Export operational settings, such as color schemes, text fonts, and default field values in Data Export windows. You can modify default SDE settings directly with any text editor (vi for example), or you can override particular default field values in the Data Export definition file window for a definition file using configuration procedures provided or permitted by the window (see Configuring Export Definition Files). Changes you make to field values in a Data Export definition file window do not, of course, change the default values specified in the SDE file. See Data Export Resource File for more information on the SDE resource file. The Data Export Process The data export process is summarized as follows: Access Data Export. See Accessing Data Export. It describes how to access the Data Export window from various locations on Solaris and Windows NT GUIs as well as from the SpectroGRAPH. Create and save a definition file. See Configuring Export Definition Files. It describes how to create or modify a file that specifies export parameters. Start the export immediately or schedule an export. See Exporting Data. It describes how to use the Export Now and Schedule Export commands. Data Export User s Guide Page 14

16 Getting Started with Data Export Special Considerations Special Considerations This section discusses special considerations you should note before using Data Export. For All Users Landscape Handles and Definition Files The model handles for the models rather than the names of the models you specify in a Data Export definition file for a historical-data export in are saved to the file. Data Export then requests the historical data for each model handle from the DDM for each landscape (that is for each landscape handle) also specified in the definition file. Users typically identify models and landscapes by name; Data Export and other SPECTRUM operations typically identify models and landscapes by their handles. Additionally, all model handles are derived from the landscape handle for the landscape server on which they (the models) have been instantiated. Therefore, it is important to note that any particular definition file that specifies a historical-data export accurately identifies the models for which data is requested and the landscape where those models are located as long as the landscape handle for the landscape remains unchanged. If a landscape handle is changed, then all the model handles for the models on that landscape change as well and a another definition file must be created and saved that specifies the new model handles. General Error Handling All error messages (along with other event messages) associated with an export are written to a log file created in the export.output directory during the export. These messages identify or help identify the causes of problems that may arise during an export. System (Solaris or Windows NT) error codes may also be included in the log file whenever applicable. Check your system s errno.h file for more information about system error messages. Data Export User s Guide Page 15

17 Getting Started with Data Export Accessing Data Export See Checking Export Output for information on log files and other indicators that chart the success or failure of an export. Accessing Data Export To access Data Export: 1 Select the SpectroGRAPH Tools menu (Figure 1). 2 Choose the Data Export option. Data Export connects to the initial SpectroSERVER specified when SpectroGRAPH was started. Figure 1: Data Export from the SpectroGRAPH Tools Menu For information about Data Export application window sections and fields, see Describing the Data Export Window. Data Export User s Guide Page 16

18 Getting Started with Data Export For information about setting export parameters in the Data Export application window, see Configuring Export Definition Files. Note: If Data Export fails to start and the system displays a message stating that there has been an error connecting to the selected landscape, try again. If this problem occurs repeatedly, increase the SDE resource file s Default Mail Service time-out value parameter, Mailtimeout. See Data Export Resource File for information about the SDE resource file. Figure 2: Data Export Window Data Export User s Guide Page 17

19 Describing the Data Export Window Describing the Data Export Window Describes the SPECTRUM Data Export window. Overview The Data Export window enables you to create, save, open, and modify definition files for data exports. It also enables you to start an export immediately or schedule an export. The window (Figure 3) is organized into the following sections: Commands Includes pull-down menu options and command icons that enable you to open and save an export definition file, start a data export, schedule a data export, clear or restore default definition file parameters, and access the Data Export User s Guide in the.pdf format. See Commands Section. General Information Enables you to enter a description or comments about a definition file, specify the landscapes from which data is exported, specify format options for ASCII output, specify a data-output directory, and specify a post-output script or executable file. See General Information Section. Data Export User s Guide Page 18

20 Historical Data Enables you to specify the data to export from the SPECTRUM events and statistics database. See Historical Data Section. Current Data Enables you to specify the SPECTRUM data types to export. See Current Data. Figure 3: Data Export Window Sections Commands General Information Historical Data Current Data Data Export User s Guide Page 19

21 Describing the Data Export Window Commands Section Commands Section This section describes the application command options you can access from either the pull-down menus or the command icons. Menus The File and Edit menus include the complete set of commands for the Data Export application. This section describes the commands available from each menu. File Menu Options The File menu includes the following commands: Open Save Save As Opens a definition file selection window, where you can select a definition file to load to the window. Saves a new file or changes made to a file. Saves a version of a file under a different name. See Configuring Export Definition Files for information on opening and saving definition files. Export Now Schedule Export Executes an immediate data export. Opens the Scheduler window, where you can schedule an export for a future time. See Exporting Data for information on starting and scheduling exports. Close Closes the Data Export window. Data Export User s Guide Page 20

22 Describing the Data Export Window Edit Menu Options The Edit menu includes the following command options: Clear All Entries Reset To Defaults Clears all entries, including all default entries except Landscapes, in the Data Export window. Restores default settings for all entries. See Data Export Resource File for information on modifying default settings. Help Menu Options The Help menu includes the following options: About Data Export User s Guide Opens a dialog box listing the Data Export version number and a copyright notice. Opens a copy of this manual (if the documentation CD is installed with SPECTRUM). Icons Icons provide you with an another way to issue most of the application commands available from the application command menus. The Open icon opens a definition file selection window. See Opening a Definition File for details. The Save icon saves a new file or changes you have made to a file. See Saving a Definition File for details. The Export Now icon starts an export. See Starting an Export Now for details. The Schedule Export icon opens the Scheduler window. It enables you to schedule an export at a future time. See Scheduling an Export for details. Data Export User s Guide Page 21

23 Describing the Data Export Window General Information Section General Information Section The General Information section (Figure 4) enables you to provide comments about the definition file, specify the landscapes from which you want to export data, specify the data s output format options, specify the directory to which you want to save exported data, and specify a postexport script or executable file. See Setting General Information Parameters for information on specifying general information parameters Figure 4: General Information Section Fields and buttons included in the General Information section are described as follows: Description Landscapes Format Options Output Directory Enables you to enter comments (optional) about a definition file. Opens a Landscapes Dialog box, where you can select the landscape(s) from which to export data. The adjacent field lists default landscapes. Opens the Format Options dialog box, where you can select the format options for an ASCII output file (see Configuring Export Definition Files for details). Opens the Output Directory dialog box, where you can specify an output directory other than the Data Export User s Guide Page 22

24 Describing the Data Export Window Post Export Script default directory. The adjacent field lists the current output directory where exported data is stored. Opens a file selection dialog box, where you can specify a script or executable file that is invoked after an export is completed. The adjacent field lists the script you specify. There is no default script for this field. (On the Windows NT platform, the file you specify must be a script file; on Solaris, this file can be either a script file or a compiled executable file.) Data Export User s Guide Page 23

25 Describing the Data Export Window Historical Data Section Historical Data Section The Historical Data section (Figure 5) enables you to specify events data or statistics data or both to export from the SPECTRUM DDM database for the model types or models you specify from the landscapes you specify. It also enables you to specify the historical period from which to export data, the previous day, week, or month, or a more precise range. For events and statistics output files, you can specify whether to overwrite data in or append data to existing files, or create new files with the date and time the file was created concatenated to the file name. Figure 5 shows a Historical Data section of the Data Export window. See Setting Historical Data Parameters for information specifying historical data parameters. Figure 5: Historical Data Section Fields and buttons included in the Historical Data section are described as follows: Data Type The Events button opens the Events Filter Dialog box, where you can specify the events data to export. The Statistics button opens the Statistics Filter Dialog box, where you can specify the statistics data to export. Output File Enables you to provide the name for the output file where data is saved. The default names are event for events data and stat for statistics data. Data Export User s Guide Page 24

26 Describing the Data Export Window Historical Data Section Note: Data Export provides a default name for the Output File field, which you can change in the resource file (see Data Export Resource File). Output Mode The toggle button enables you to specify whether to overwrite, append data to, or create a new output file with the creation date and time included in the file name. Each button provides the following selections: Overwrite Overwrites the file you specify in the Output File field. Append Appends the exported data to the file you specify in the Output File field. Date Creates a new file with a date and time stamp added to the file name you specify in the Output File field. Note: If you attempt to overwrite or append data to a nonexistent file, Data Export creates a new file. The Append output mode should only be used in a statistics export when you are exporting the same type and number of attributes as previously exported to a file. Export Range The toggle button for each category enables you to specify a time range from which to export events and statistics data. Each button offers the following selections: Custom Opens the Events Data Range dialog box, where you can specify a precise export time range. See Custom Range for details. Day Specifies the preceding 24-hour period. Data Export User s Guide Page 25

27 Describing the Data Export Window Current Data Current Data Week Specifies the preceding 7-day period. Month Specifies the preceding calendar month. The Current Data section (Figure 6) enables you to specify the types of data you want to export from the Model Types and Models catalogs in a SpectroSERVER database. It also enables you to specify an output file name other than the default names listed next to each Data Type category. See Setting Current Data Parameters for information on specifying current data parameters. Figure 6: Current Data Section Fields and buttons in the Current Data section are described as follows. Data Type Enables you to specify the types of data you want to export. Data Export User s Guide Page 26

28 Describing the Data Export Window Current Data Note: For a models export, Data Export acknowledges only the first 32 characters of model names by default. If you require display of more than 32 characters, you must change the value of the SDE_OUTPUT_MODEL_LEN variable in the dtxscript file (located in the SG-Tools directory). You can specify display of up to 1024 characters. Output File Enables you to provide the name for the output file where data is saved. You must accept the default name or enter a name for each data type you specify. Data Export User s Guide Page 27

29 Configuring Export Definition Files Configuring Export Definition Files Describes how to create and save Data Export definition files. Overview Before you can start an export, you must first establish export parameters in a new definition file or revise export parameters in an existing definition file and then save the file. See Opening and Saving Definition Files. The definition file specifies the type(s) of data to export, the format of the extracted data, and whether or not you want a post-export script executed after the export. To create a definition file, you specify export parameters in the following sections of the Data Export window: General Information the landscapes to import data from, the output format options for the exported data, and an optional post-export script See Setting General Information Parameters. Historical Data SPECTRUM events and statistics data See Setting Historical Data Parameters. Current Data model, relations, associations, and attribute data types See Setting Current Data Parameters. If you are unfamiliar with the Data Export window, see Describing the Data Export Window. Data Export User s Guide Page 28

30 Note: Default settings for the Data Export window and other windows and dialog boxes you can invoke from it are specified in the Data Export resource file, SDE. See Data Export Resource File for information on SDE parameters. Opening and Saving Definition Files This section describes how to open and save definition files. Opening a Definition File To open a new file: Invoke Data Export (see Accessing Data Export). The Data Export window appears. It displays default or empty settings that you can configure and save for the export. Until you name the file, the default filename, Unnamed.sde, appears on the window s title banner. To open an existing file: 1 Click the Open icon, or select Open from the File menu. An Open File dialog box (Figure 7) appears. Use the Filter option to navigate to the correct directory, select a file, and click the OK button. The Data Export window displays the configuration settings for the selected file. 2 Configure the file as desired. 3 Save the modified definition file as described in Saving a Definition File. Data Export User s Guide Page 29

31 Configuring Export Definition Files Figure 7: Open File Dialog Box Saving a Definition File To save a definition file: 1 Click the Save icon, or select Save or Save As from the File menu. Select Save if you want to save an original file or changes to an existing file. Select Save As if you want to save another version of the original file and retain the original file. Whenever you select Save As or select Save to initially save a new file, the Save As dialog box (Figure 8) appears. It enables you to enter the name of the new file (original file or modified version of an existing file). Data Export User s Guide Page 30

32 Configuring Export Definition Files Figure 8: File Selection Dialog Box 2 Enter a name for the definition file. Use the Filter option to navigate to the correct directory path. Enter a file name at the end of the path in the Selection field. Data Export appends the definition file extension,.sde, when you execute the save. 3 Click the OK button to save the file. The filename appears on the Data Export window s title banner, and the file is saved to the Data Export default definition file directory, export.output, or another directory that you have specified. Data Export User s Guide Page 31

33 Configuring Export Definition Files Setting General Information Parameters Setting General Information Parameters To specify General Information parameters: Enter information (optional) about the file in the Description field. You can use this field to describe the purpose or scope of the definition file. This information appears in the field whenever you re-open the file and in the log file (chronicle of export activities) Data Export writes to the output directory when you export data with the file. Select the landscapes from which to export data. Either accept the landscape(s) listed in the Landscapes... field or modify the list as described in Specifying Landscapes. Specify the output directory for exported data files. Either accept the default directory displayed in the Output Directory... field or specify another directory as described in Specifying an Output Directory. Specify a post export script (optional). Either accept the default post export script (if one is displayed) or select another script that you want run after the export has been completed as described in Specifying a Post Export Script. Specify format options for ASCII data. Either accept default ASCII format options or change format options as described in Setting ASCII Format Options. Specifying Landscapes The Landscapes... field lists the default landscape(s) specified by the PreferredLandscapes parameter in the SDE resource file. To modify the default landscapes list, click the Landscapes... button to open the Landscapes dialog box (Figure 9). The dialog box enables you to add or remove landscapes from the list. Data Export User s Guide Page 32

34 Configuring Export Definition Files Setting General Information Parameters Figure 9: Landscapes Dialog Box How to work with the Landscapes dialog box: To select the landscape(s) you want to include, click on the landscape(s). Deselect the landscape(s) you want to remove. To specify that models of a selected model type for all preferred landscapes are automatically listed when specifying events or statistics filter criteria (see Setting Historical Data Parameters), select the Automatically Expand Preferred Landscapes button. Deselect the option if you do not want to expand preferred landscapes. To locate landscapes, use the Search or Filter utilities. With Search, you type the name or the first few characters of the item you are searching for in the list. As you type characters, the list scrolls until the item or the closest match appears at the top of the list. With Filter, you type the name or a character string contained in the item you are searching for. As you type characters, all items in the list that do not contain the characters are temporarily deleted. Unlike a Data Export User s Guide Page 33

35 Configuring Export Definition Files Setting General Information Parameters search operation, the characters you are filtering on do not have to be at the beginning of an item. By default, the Search and Filter operations are case sensitive. To specify a case insensitive operation, deselect the Case Sensitive option. To put the specifications into effect, click the OK button. To dismiss the operation, click the Cancel button. Data Export User s Guide Page 34

36 Configuring Export Definition Files Specifying an Output Directory Setting General Information Parameters The Output Directory... field displays the default output directory specified by the DefFileDefaultDir parameter in the SDE resource file. To specify another output directory, click the Output Directory... button to open the Output Directory dialog box (Figure 10). The dialog box enables you to select a directory for exported data files. Figure 10: Output Directory Dialog Box Data Export User s Guide Page 35

37 Configuring Export Definition Files Specifying a Post Export Script Setting General Information Parameters The Post Export Script... field displays a default script if one has been specified for the PostExportDefault parameter in the SDE resource file. To specify another script, click the Post Export Script... button to open the Post Export Script dialog box (Figure 11). It enables you to select a script. Figure 11: Post Export Script Dialog Box (See Exporting To Other Databases for an example of how a post-export script is used to export data to a third-party database.) Data Export User s Guide Page 36

38 Configuring Export Definition Files Setting General Information Parameters If you use perl scripts as post-export scripts, please be aware that SPECTRUM includes as part of its installation a subset of the perl executables, and sets the PERLLIB environment variable. This setting can override the standard PERLLIB environment variable and cause some perl scripts to malfunction. Caution: To avoid this, the PERLLIB environment variable should be unset prior to executing the post-export script. The following example uses a shell script to unset the variable and execute the perl post-export script: #! /bin/sh unset PERLLIB exec <your_perl_post_export_script> ${1+ $@ } Setting ASCII Format Options Exported data saved in the ASCII delimited file format can be used as input for a variety of report generators, databases, and spreadsheets. Depending on the requirements for whichever of these you are using, you may have to define the format of the ASCII files. You can customize the file format using the Format Options feature. When you click the Format Options button, the ASCII Format Options dialog box shown in Figure 12 appears. Data Export User s Guide Page 37

39 Configuring Export Definition Files Setting General Information Parameters Figure 12: ASCII Format Options Dialog Box The ASCII Format Options dialog box includes the following sections: Field Separator Record Separator The buttons included in this section let you specify how you want the fields in the ASCII output file to be separated: with a space, tab, comma, semicolon, colon, or some other character that you define (User Defined). The buttons in this section let you specify how you want the records in the ASCII output file to be separated: with a carriage return (CR), line feed (LF), carriage return and line feed (CR/LF), tab, or some other character that you define (User Defined). Data Export User s Guide Page 38

40 Configuring Export Definition Files Setting General Information Parameters Note: The field separator and record separator can be any single keyboard character,including space or tab do not use a control character (Ctrl A, etc.). The record separator must be different from the field separator. Also, do not use a character that your application may use to represent data. Date/Time Format The buttons in this section let you specify how you want the date/time data to appear in the ASCII output file. If you select Separate, the time and date are split into two fields, one for date and one for time. If you select Combined, the time and date (separated by a space) are represented in one field. If you select Time Ticks, the time and date are represented in UNIX time ticks in one field. Note: If Combined is selected, do not use space as a delimiter. Space is used with the Combined field to separate the date and time. Data and Schema String Format The buttons in this section let you specify whether to combine ASCII data and schema files either into one file or separate files. If you select Combined, the data and schema files are stored in the same file with the schema first. If you select Separate, schema files will have the same names as the ASCII data files along with the.sch extension appended to them. See Data Structure of ASCII Files for more information on ASCII data files and schema format. The buttons in this section let you specify whether or not to enclose character data fields in the ASCII output file in double quotation marks. Data Export User s Guide Page 39

41 Configuring Export Definition Files Setting Historical Data Parameters Handle Format The buttons in this section let you specify whether to represent handles (model handles, attribute IDs, etc.) in either hexadecimal or decimal notation in the ASCII output file. After you have made your selections in the ASCII Format Options dialog box, click the OK button to establish your specifications. Setting Historical Data Parameters This section describes how to use the Historical Data section of the Data Export window to perform the following tasks: Specifying the SPECTRUM events data to include in the export. See Specifying Events Data. Specifying the SPECTRUM statistics data to include in the export. See Specifying Statistics Data. Specifying the output parameters for both types of historical data. See Specifying Output Parameters. Specifying Events Data The Events Filter dialog box (Figure 13) enables you to define events data for an export. To open the dialog box: Click the Events... button in the Historical Data section (Figure 5) of the Data Export window. Data Export User s Guide Page 40

42 Configuring Export Definition Files Setting Historical Data Parameters Figure 13: Events Filter Dialog Box Note: Model names followed by a (D) indicate models that have been deleted from the SPECTRUM modeling database. They are visible only to users with Admin 0 privileges for as long as statistics and events data for those models exist. Data Export User s Guide Page 41

43 Configuring Export Definition Files Setting Historical Data Parameters Specifying Models This section describes how to specify the models for which you want to export events data in the Model Types/Models list (Figure 14) in the Events Filter dialog box. Figure 14: Model Types/Models List Locating Model Types in the Model Types/Models List You can either manually scroll through the list to find the model types you want or use the Search and Filter utilities to find them. See Figure 14. Model Types are listed in alphabetical order. To find a name manually: Use the scroll bar adjoining the list, or use the sliding window on the list indicator located to the left of the list. To use the Search utility to find a name: Toggle the Search/Filter button, if necessary, to the default Search option. Start typing the model type name in the adjacent text-entry field. As soon as Search finds a match for the name the Model Types/Models list automatically scrolls so that the name you are seeking appears at the top of the list. Data Export User s Guide Page 42

44 Configuring Export Definition Files Setting Historical Data Parameters To use the Filter utility to find a name: Toggle the Search/Filter button to the Filter option. Start typing any of the letters in the model type name in the adjoining field. As soon as Filter matches the letters you entered with letters included in model type names in the list, those names only appear in the list. For example, if you type erne, the list displays model type names that include the letter string, such as the EthernetApp and EthernetIfApp. By default, the Search and Filter operations are case sensitive. To specify a case insensitive operation, click on the Case Sensitive button to deselect the option. Also by default, the Search and Filter operations are enabled when you open the Events Filter dialog box, as indicated by the selected flashlight icon located in the lower right-hand corner of the Model Types/Models list and the yellow box around the list and the text-entry field next to the Search/Filter button. Deselect the flashlight icon if you want to disable Search and Filter operations. Selecting Models The Events Filter dialog box enables you to select as many models as you want from any number of preferred landscapes. Note: If you previously selected the Automatically Expand Preferred Landscapes option (see Specifying Landscapes), the dialog box lists for each preferred landscape all models for the model type name you selected from the Model Types/Models list. If you deselected the option, only the landscape names appear, and you must double-click on each landscape name to display the list of models included in it. Data Export User s Guide Page 43

45 Configuring Export Definition Files Setting Historical Data Parameters To select all models belonging to a particular model type: 1 Double-click on a model type name. 2 Click once again on the model type name. A double asterisk (**) appears in front of the model type name and all landscape names listed under the model type name, indicating that all models for that model type from all preferred landscapes have been selected. To deselect the models, click on the model type name again. To deselect models for a specific landscape only, click on the landscape name. To select specific models: 1 Double-click on a model type name. 2 Click on each model you want to select. To deselect a model, click again on the model name. Selecting Filter Criteria This section describes how to specify the types of SPECTRUM events and alarms data you want to export for the models you have selected. The Select Filter Criteria list includes three filtering options: Select All Events All events and alarms for the selected models are exported. This is the default setting. Filter on Event Codes Only the events that match the codes you select for the selected models are exported. Filter on Alarms Only events with alarms that match the severity level you specify for the selected models are exported. Data Export User s Guide Page 44

46 Configuring Export Definition Files Setting Historical Data Parameters Selecting Event Codes Event Codes are the numeric strings mapped to SPECTRUM events. By specifying event codes you specify the event information you want to export for the models you have selected. To select event codes: 1 Select the Filter on Event Codes button from the Select Filter Criteria list in the Events Filter dialog box (Figure 13). The Select Event Code(s) dialog box (Figure 15) appears. 2 Select the event codes you want from the Files list by clicking on them, and then click on the OK button to return to the Events Filter dialog box. Figure 15: Select Event Code(s) Dialog Box Data Export User s Guide Page 45

47 Configuring Export Definition Files Setting Historical Data Parameters Selecting Alarms Alarm condition color codes indicate the severity of alarms set by SPECTRUM for network models. By specifying alarm codes (Red, Yellow, etc.) you specify the alarm information you want to export for the models you have selected. To select alarms: 1 Select the Filter on Alarms button from the Select Filter Criteria list in the Events Filter dialog box (Figure 13). The Alarm Filter Options dialog box shown in Figure 16 appears. This list contains all possible alarm conditions that can occur for a device. You can either select all alarms or one or more specific alarms. 2 Select the alarm codes you want, and then click on the OK button to return to the Events Filter dialog box. Figure 16: Alarm Filter Options Dialog Box Data Export User s Guide Page 46

48 Configuring Export Definition Files Specifying Statistics Data Setting Historical Data Parameters The Statistics Filter dialog box (Figure 17) enables you to define model statistics data for an export. To open the Statistics Filter dialog box: Click the Statistics... button in the Historical Data section (Figure 5) of the Data Export window. Figure 17: Statistics Filter Dialog Box Specifying Models and Common Attributes This section describes how to specify the models for which you want to export statistics data. You select models from the Model Types/Models list (Figure 18) in the Statistics Filter dialog box. Data Export User s Guide Page 47

49 Configuring Export Definition Files Setting Historical Data Parameters Use the same procedures for selecting models as described in Specifying Models in the Specifying Events Data section. To select model attributes: 1 Select the attributes for which you want statistics from the Common Attributes list. This list contains the attributes common to all the models you have selected. Note that the attributes for any group of models are common only if the attributes have the same attribute IDs; attributes with the same name are not necessarily common. You can select as many attributes as you want from the list, but you must select at least one. An attribute name with a [ ] after it indicates that the attribute is a list attribute. A list attribute contains a set or sequence of values and is stored in a MIB table. See the SPECTRUM Model Type Editor User Guide for more information. When you choose a list attribute, the output format of the expected data will be in a format compatible with attributes of this type. See Data Structure of ASCII Files for information on how standard statistics output and list attribute statistics output differ. You can specify that all statistics output be formatted in the list attribute format by changing the value of the ListAttrFormat parameter in the SDE resource file. See Data Export Resource File for information on the SDE resource file. If you have not specified list attribute format in the SDE resource file, a dialog box warning you of output file format change will appear under the following circumstances: If you selected a list attribute when none had been selected before. In this case, the resulting output file will be in list attribute format. If you deselected all list attributes that had previously been chosen in the definition file. In this case, the resulting output file will be in standard format. 2 Click OK to close the dialog box, or click Cancel to dismiss the operation. Data Export User s Guide Page 48

50 Configuring Export Definition Files Setting Historical Data Parameters Figure 18: Model Types/Models and Common Attribute Lists from the Statistics Filter Dialog Box Specifying Output Parameters This section describes how to specify the following output parameters for events or statistics data or both: Output file Output mode (overwrite or append data to an existing file or create a new file) Export Range (historical period from which to export data) Data Export User s Guide Page 49

51 Configuring Export Definition Files Setting Historical Data Parameters Specifying an Output File Name This section describes how to specify a name for the Output File Name field. If you choose instead, however, to accept the default file name displayed in the field and have already saved data to it, you must specify whether you want Data Export to overwrite or append data to the existing data (see Specifying an Output Mode). You can also change the default file names by modifying the value for the EventsName parameter for events and the StatsName parameter for statistics in the Data Export SDE resource file (see Data Export Resource File). To specify an output file name: Modify or overwrite the default output file name. Specifying an Output Mode This section describes how to use Output Mode button options to specify how you want to save data to a events or statistics file. To specify an output mode select one of the following options: Append Overwrite Date The extracted data is appended to the output file. The extracted data overwrites the data stored in the file. The extracted data is stored in a new file whose name is created by concatenating the date and time to the name you specified in the Output File field. Specifying an Export Range This section describes how to specify a time range for an export, the interval during which events and statistics data were logged to the SPECTRUM DDM database prior to the start of an export. To specify an export range, select one the following options from the Export Range toggle button: Data Export User s Guide Page 50

52 Configuring Export Definition Files Setting Historical Data Parameters Custom Day Lets you specify a precise interval. See Custom Range for details. Lets you specify an interval of up to 24 hours spanning one or two days preceding the start of the export. See Day Range for details. Examples: 7 AM to 11 PM Monday; 9 PM Thursday to 9 AM Friday. Week Lets you specify an interval of up to 24 hours for the days in a one-to-seven day period preceding the start of the export. See Week Range for details. Examples: 6 AM to 11 PM daily Sunday to Saturday; 11 PM on previous day to 7 AM on next day daily Monday to Friday. Month Lets you specify an interval of up to 24 hours for the days in the preceding calendar month. See Month Range for details. Example: 6 AM to 11 PM daily for the month of January. Note: If you attempt to save a definition file with different export ranges, a daily export range for Events and a weekly export range for Statistics for example, Data Export displays a message notifying you of the discrepancy. There is, however, no requirement by Data Export that export ranges must be the same. Custom Range The Custom option opens the Data Range dialog box (Figure 19). It enables you to specify as broad or narrow a range as you want. Use this option to export data from any historical period from which data is currently available (export now option) or will be available in the future (scheduled export option). Data Export User s Guide Page 51

53 Configuring Export Definition Files Setting Historical Data Parameters Figure 19: Events/Statistics Data Range Dialog Box To set a custom range: 1 Click on the Available Range button to display the available range of data. The range is indicated by the Start Date and End Date fields and Start Time and End Time fields after Data Export queries the SPEC- TRUM DDM database. If you accept the available range, proceed to Step 4. To specify another range (a narrower range or a future range for a scheduled export) proceed to Step 2. Note: The maximum available range for events and statistics data is specified by the data-aging variables MAX_STAT_DAYS for statistics data and MAX_EVENT_DAYS for events data in the Archive Manager resource file,.configrc. See SPECTRUM Database Management for information on modifying these aging variables. 2 Specify the Start Date and Start Time using either of the following options: Data Export User s Guide Page 52

54 Configuring Export Definition Files Setting Historical Data Parameters Use the Month button to select the start month and the increment and decrement buttons ( and ) to set values for the Day, Year, Hours, and Minutes fields. Use the Now button to set the current date and time as the start date and time (applicable for an export scheduled to begin on a later date). 3 Specify the End Date and End Time using either of the following options: Use the Month button to select the end month and the increment and decrement buttons ( and ) to set values for the Day, Year, Hours, and Minutes fields. Use the Now button to set the current date and time as the end date and time. 4 Click the OK button to save the settings and return to the Data Export window, or click the Cancel button to dismiss the operation. Data Export User s Guide Page 53

55 Configuring Export Definition Files Setting Historical Data Parameters Day Range The Day option opens the Day Range dialog box (Figure 20). It enables you to specify a range of up to 24 hours. The range can span either one or two calendar days. Figure 20: Events/Statistics Day Range Dialog Box When the Day range option is selected, Data Export extracts events or statistics logged during the most recently transpired range. For example, to export data from the range 11:00 PM on Monday and 6:00 AM on Tuesday, the export must be started any time after 6:00 AM on Tuesday. If the export instead is started before 6:00 AM on Tuesday, Data Export exports data from the most recently transpired 11:00 PM to 6:00 AM range, which in this example would be data from 11:00 PM on Sunday to 6:00 AM on Monday. Data Export User s Guide Page 54

56 Configuring Export Definition Files Setting Historical Data Parameters To set a day range: 1 Specify the Start Time and End Time, using the buttons ( and ) next to the Hours and Minutes fields. 2 Click the OK button to save the settings and return to the Data Export window, or click the Cancel button to dismiss the operation. Week Range The Week option opens the Week Export Range dialog box (Figure 21). It enables you to specify a range of up to 24 hours (across two calendar days, 23:00 until 07:00 Monday through Saturday for example) for any number of days up to a week (seven-day period) preceding the start of the export. Figure 21: Events/Statistics Week Range Dialog Box Data Export User s Guide Page 55

57 Configuring Export Definition Files Setting Historical Data Parameters To set a week range: 1 Specify the start of the range using the Start Day button and the end of the range using the End Day button. 2 Specify the Start Time and End Time, using the buttons ( and ) next to the Hours and Minutes fields. 3 Click the OK button to save the settings and return to the Data Export window, or click the Cancel button to dismiss the operation. Month Range When you select Month, the Month Range dialog box (Figure 22) appears. It enables you to specify an interval of up to 24 hours for each day in the calendar month preceding the start of the export. Figure 22: Events/Statistics Month Range Dialog Box Data Export User s Guide Page 56

58 Configuring Export Definition Files Setting Current Data Parameters To set a month range: 1 Specify the Start Time and End Time, using the buttons ( and ) next to the Hours and Minutes fields. 2 Click the OK button to save the settings and return to the Data Export window, or click the Cancel button to dismiss the operation. Setting Current Data Parameters To specify current data: 1 Select the Data Type you want to export Model Types, Model Type Hierarchy, Models, Attributes, Associations, Relations, and Extended Attributes. You can select as many data types as you want for a definition file. Notice that a default file name is provided for each data type. 2 Accept the default output name, as specified in the SDE resource file, for each data type selected, or specify another in the current file by modifying or overwriting the name in the output field. Note: Each name must be unique because Data Export stores each data type in a separate file. Data Export User s Guide Page 57

59 Exporting Data Describes how to immediately start an export and how to schedule an export with the Scheduler utility; briefly discusses Windows 2000/NT scheduling requirements; describes the output produced from ASCII data exports. Overview This chapter describes the two methods available from the Data Export window (Figure 2) for starting an export: Using the Export Now command to start an export immediately. See Starting an Export Now. Using the Schedule Export command to invoke the scheduler utility that you can use to schedule an export for a future time. See Scheduling an Export. If you are unfamiliar with the Data Export window, see Describing the Data Export Window. Sample export output. See Checking Export Output. Data Export User s Guide Page 58

60 Exporting Data Starting an Export Now Starting an Export Now You can export data immediately with the Export Now command once you have created and saved a definition file (see Configuring Export Definition Files) for the export. To start an export: 1 Open a definition file in the Data Export window. 2 Click on the Export Now icon, or select Export Now from the File menu to start the export. Scheduling an Export The Scheduler option enables you to schedule an export at off-peak times, when bandwidth or system resources or both are more readily available for instance. For information on creating a definition file (see Configuring Export Definition Files). Note: Windows 2000/NT Considerations Before using the Scheduler, Windows 2000/NT users should make sure that the Schedule Service is setup properly. See the Scheduler Requirements for Windows 2000/NT in the After Installing SPECTRUM section of the Installation Guide. To schedule an export: 1 Open a definition file in the Data Export window. 2 Click on the Schedule Export icon, or select Schedule Export from the File menu. The Scheduler window (Figure 23) opens. The window s Command field displays the entire command specification: the path for the Data Export executable and the path for the definition file opened in the Data Export window when you invoked the Scheduler. Data Export User s Guide Page 59

61 Exporting Data Scheduling an Export 3 Specify the scheduled export in the Scheduler window. See Working with the Scheduler for details about working with the Scheduler window. Figure 23: Scheduler Window Working with the Scheduler The Scheduler window enables you to configure export commands and include them in the scheduled command queue on your system. The commands are executed by the cron utility on UNIX systems and the Task Scheduler Service on Windows NT systems. See the SPECTRUM Installation Guide (0675) for information on setting up the Windows NT/2000 Schedule Task service. Data Export User s Guide Page 60

62 Exporting Data Scheduling an Export The window enables you to perform the following tasks: Create and include in a scheduled queue export commands that specify the definition file for each export and when and how often you want the data export to occur See Creating Scheduled Export Commands. Change scheduled export command parameters See Modifying Scheduled Export Commands. Delete scheduled export commands See Removing Scheduled Export Commands. Creating Scheduled Export Commands To create a scheduled export command: 1 Specify the export frequency (when and how often you want the export executed). Select one of the following frequency options (Figure 24) from the Frequency toggle button: Once Lets you specify the date and time for a single export. Daily Lets you specify the time for a daily export. Weekly Lets you specify the day and time for a weekly export. Monthly Lets you specify the date and time for a monthly export. Note: When exporting events or statistics data or both on a periodic scheduled basis, the export range specified in the definition file should correspond to the selected schedule frequency option (Daily, Weekly, Monthly). See Setting Historical Data Parameters for information on specifying events and statistics data. Data Export User s Guide Page 61

63 Exporting Data Scheduling an Export 2 Add and save the scheduled export command entry to the Scheduled Entries list. Click Add to include the entry in the list; then click Save to save the entry to the scheduled queue. Repeat these procedures for subsequent entries. If you exit without saving, your command entries will not be executed. See Describing Scheduled Export Command Entries for more information. Figure 24: Scheduled Export Frequency Options Data Export User s Guide Page 62