Network Manager IP Edition Version 3 Release 9. Language Reference IBM R2E2

Transcription

1 Network Manager IP Edition Version 3 Release 9 Language Reference IBM R2E2

2

3 Network Manager IP Edition Version 3 Release 9 Language Reference IBM R2E2

4 Note Before using this information and the product it supports, read the information in Notices on page 111. This edition applies to version 3 release 9 of IBM Tivoli Network Manager IP Edition (product number 5724-S45) and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright IBM Corporation 2006, US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents About this publication v Intended audience v What this publication contains v Publications v Accessibility ix Tivoli technical training ix Support information x Conventions used in this publication x Chapter 1. Active Object Class files... 1 Device class hierarchy EndNode class InferredDevice class NetworkDevice class AOC syntax Components of an AOC file Chapter 2. Object Query Language... 5 Conventions and sample databases Features of OQL General rules of OQL Quotes in OQL OQL punctuation Logical operators of OQL Precedence and association of operators Use of regular expressions Key differences between OQL and SQL Database and table creation Datatypes Column constraints s of database and table creation Inserting data into a table of inserting data into a database Selecting data from a table Counting rows in a table Conditional tests in OQL s of the like operator use of the and Operator use of the or operator selection based on part of an object.. 20 Use of select to perform subqueries of using subqueries to search a list.. 22 s of selecting based on part of a list.. 22 Selection of data into another table s of using any, *, and all to perform table joins Updates to records in tables s of updating a list of updating an object Database and table listings Deletion of a record from a database table Deletion of a database or table The eval statement Scope of the eval statement Quotation marks in eval statements Single straight back quotes s of the eval statement Extraction of record values and fields Character escape sequences Multibyte data type Eval statement keywords Chapter 3. Stitchers and stitcher language Stitcher formats Stitcher structure Stitcher triggers Stitcher rules Stitcher language Stitcher text file structure Stitcher trigger conditions Stitcher rules Stitcher language building blocks Comments Precedence and association of operators OQL quotes in the stitcher language Appendix. Network Manager glossary 107 Notices Trademarks Index Copyright IBM Corp. 2006, 2016 iii

6 iv IBM Tivoli Network Manager IP Edition: Language Reference

7 About this publication Intended audience IBM Tivoli Network Manager IP Edition provides detailed network discovery, device monitoring, topology visualization, and root cause analysis (RCA) capabilities. Network Manager can be extensively customized and configured to manage different networks. Network Manager also provides extensive reporting features, and integration with other IBM products, such as IBM Tivoli Application Dependency Discovery Manager, IBM Tivoli Business Service Manager and IBM Systems Director. The IBM Tivoli Network Manager IP Edition Language Reference describes the system languages used by Network Manager IP Edition, such as the Stitcher language, and the Object Query Language. This publication is for advanced users who need to customize the operation of Network Manager IP Edition. This publication is intended for system and network administrators who are responsible for configuring IBM Tivoli Network Manager IP Edition. IBM Tivoli Network Manager IP Edition works in conjunction with IBM Tivoli Netcool/OMNIbus; this publication assumes that you understand how IBM Tivoli Netcool/OMNIbus works. For more information on IBM Tivoli Netcool/OMNIbus, see the publications described in Publications. What this publication contains Publications This publication contains the following sections: v Chapter 1, Active Object Class files, on page 1 Describes the syntax of Active Object Class (AOC) files, which are used to classify network devices after the completion of a discovery. v Chapter 2, Object Query Language, on page 5 Describes how to use Object Query Language (OQL) to create new databases, insert data into existing databases, and issue OQL statements by using the OQL Service Provider. v Chapter 3, Stitchers and stitcher language, on page 37 Describes the functions, formats, structure, triggers, and rules of the stitchers used for the transfer of data during the discovery process. This section lists publications in the Network Manager library and related documents. The section also describes how to access Tivoli publications online and how to order Tivoli publications. Your Network Manager library The following documents are available in the Network Manager library: v IBM Tivoli Network Manager IP Edition Release Notes, GI Copyright IBM Corp. 2006, 2016 v

8 Gives important and late-breaking information about IBM Tivoli Network Manager IP Edition. This publication is for deployers and administrators, and should be read first. v IBM Tivoli Network Manager Getting Started Guide, GI Describes how to set up IBM Tivoli Network Manager IP Edition after you have installed the product. This guide describes how to start the product, make sure it is running correctly, and discover the network. Getting a good network discovery is central to using Network Manager IP Edition successfully. This guide describes how to configure and monitor a first discovery, verify the results of the discovery, configure a production discovery, and how to keep the network topology up to date. Once you have an up-to-date network topology, this guide describes how to make the network topology available to Network Operators, and how to monitor the network. The essential tasks are covered in this short guide, with references to the more detailed, optional, or advanced tasks and reference material in the rest of the documentation set. v IBM Tivoli Network Manager IP Edition Product Overview, GC Gives an overview of IBM Tivoli Network Manager IP Edition. It describes the product architecture, components and functionality. This publication is for anyone interested in IBM Tivoli Network Manager IP Edition. v IBM Tivoli Network Manager IP Edition Installation and Configuration Guide, SC Describes how to install IBM Tivoli Network Manager IP Edition. It also describes necessary and optional post-installation configuration tasks. This publication is for administrators who need to install and set up IBM Tivoli Network Manager IP Edition. v IBM Tivoli Network Manager IP Edition Administration Guide, SC Describes administration tasks for IBM Tivoli Network Manager IP Edition, such as how to administer processes, query databases and start and stop the product. This publication is for administrators who are responsible for the maintenance and availability of IBM Tivoli Network Manager IP Edition. v IBM Tivoli Network Manager IP Edition Discovery Guide, SC Describes how to use IBM Tivoli Network Manager IP Edition to discover your network. This publication is for administrators who are responsible for configuring and running network discovery. v IBM Tivoli Network Manager IP Edition Event Management Guide, SC Describes how to use IBM Tivoli Network Manager IP Edition to poll network devices, to configure the enrichment of events from network devices, and to manage plug-ins to the Tivoli Netcool/OMNIbus Event Gateway, including configuration of the RCA plug-in for root-cause analysis purposes. This publication is for administrators who are responsible for configuring and running network polling, event enrichment, root-cause analysis, and Event Gateway plug-ins. v IBM Tivoli Network Manager IP Edition Network Troubleshooting Guide, GC Describes how to use IBM Tivoli Network Manager IP Edition to troubleshoot network problems identified by the product. This publication is for network operators who are responsible for identifying or resolving network problems. v IBM Tivoli Network Manager IP Edition Network Visualization Setup Guide, SC Describes how to configure the IBM Tivoli Network Manager IP Edition network visualization tools to give your network operators a customized working vi IBM Tivoli Network Manager IP Edition: Language Reference

9 environment. This publication is for product administrators or team leaders who are responsible for facilitating the work of network operators. v IBM Tivoli Network Manager IP Edition Management Database Reference, SC Describes the schemas of the component databases in IBM Tivoli Network Manager IP Edition. This publication is for advanced users who need to query the component databases directly. v IBM Tivoli Network Manager IP Edition Topology Database Reference, SC Describes the schemas of the database used for storing topology data in IBM Tivoli Network Manager IP Edition. This publication is for advanced users who need to query the topology database directly. v IBM Tivoli Network Manager IP Edition Language Reference, SC Describes the system languages used by IBM Tivoli Network Manager IP Edition, such as the Stitcher language, and the Object Query Language. This publication is for advanced users who need to customize the operation of IBM Tivoli Network Manager IP Edition. v IBM Tivoli Network Manager IP Edition Perl API Guide, SC Describes the Perl modules that allow developers to write custom applications that interact with the IBM Tivoli Network Manager IP Edition. s of custom applications that developers can write include Polling and Discovery Agents. This publication is for advanced Perl developers who need to write such custom applications. v IBM Tivoli Monitoring for Tivoli Network Manager IP User's Guide, SC Provides information about installing and using IBM Tivoli Monitoring for IBM Tivoli Network Manager IP Edition. This publication is for system administrators who install and use IBM Tivoli Monitoring for IBM Tivoli Network Manager IP Edition to monitor and manage IBM Tivoli Network Manager IP Edition resources. Prerequisite publications To use the information in this publication effectively, you must have some prerequisite knowledge, which you can obtain from the following publications: v IBM Tivoli Netcool/OMNIbus Installation and Deployment Guide, SC Includes installation and upgrade procedures for Tivoli Netcool/OMNIbus, and describes how to configure security and component communications. The publication also includes examples of Tivoli Netcool/OMNIbus architectures and describes how to implement them. v IBM Tivoli Netcool/OMNIbus User's Guide, SC Provides an overview of the desktop tools and describes the operator tasks related to event management using these tools. v IBM Tivoli Netcool/OMNIbus Administration Guide, SC Describes how to perform administrative tasks using the Tivoli Netcool/OMNIbus Administrator GUI, command-line tools, and process control. The publication also contains descriptions and examples of ObjectServer SQL syntax and automations. v IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide, SC Contains introductory and reference information about probes and gateways, including probe rules file syntax and gateway commands. v IBM Tivoli Netcool/OMNIbus Web GUI Administration and User's Guide SC About this publication vii

10 Describes how to perform administrative and event visualization tasks using the Tivoli Netcool/OMNIbus Web GUI. Accessing terminology online The IBM Terminology Web site consolidates the terminology from IBM product libraries in one convenient location. You can access the Terminology Web site at the following Web address: Accessing publications online IBM posts publications for this and all other Tivoli products, as they become available and whenever they are updated, to the IBM Knowledge Center Web site at: Network Manager documentation is located under the Cloud & Smarter Infrastructure node on that Web site. Note: If you print PDF documents on other than letter-sized paper, set the option in the File > Print window that allows your PDF reading application to print letter-sized pages on your local paper. Ordering publications You can order many Tivoli publications online at the following Web site: You can also order by telephone by calling one of these numbers: v In the United States: v In Canada: In other countries, contact your software account representative to order Tivoli publications. To locate the telephone number of your local representative, perform the following steps: 1. Go to the following Web site: 2. Select your country from the list and click Go. The Welcome to the IBM Publications Center page is displayed for your country. 3. On the left side of the page, click About this site to see an information page that includes the telephone number of your local representative. viii IBM Tivoli Network Manager IP Edition: Language Reference

11 Accessibility Accessibility features help users with a physical disability, such as restricted mobility or limited vision, to use software products successfully. Accessibility features Tivoli technical training The following list includes the major accessibility features in Network Manager: v The console-based installer supports keyboard-only operation. v The console-based installer supports screen reader use. v Network Manager provides the following features suitable for low vision users: All non-text content used in the GUI has associated alternative text. Low-vision users can adjust the system display settings, including high contrast mode, and can control the font sizes using the browser settings. Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element. v Network Manager provides the following features suitable for photosensitive epileptic users: Web pages do not contain anything that flashes more than two times in any one second period. The accessibility of the Network Manager Knowledge Center is described in the Knowledge Center itself. Extra steps to configure Internet Explorer for accessibility If you are using Internet Explorer as your web browser, you might need to perform extra configuration steps to enable accessibility features. To enable high contrast mode, complete the following steps: 1. Click Tools > Internet Options > Accessibility. 2. Select all the check boxes in the Formatting section. If clicking View > Text Size > Largest does not increase the font size, click Ctrl + and Ctrl -. IBM and accessibility See the IBM Human Ability and Accessibility Center for more information about the commitment that IBM has to accessibility. For Tivoli technical training information, refer to the following IBM Tivoli Education Web site: About this publication ix

12 Support information If you have a problem with your IBM software, you want to resolve it quickly. IBM provides the following ways for you to obtain the support you need: Online Go to the IBM Software Support site at support/probsub.html and follow the instructions. IBM Support Assistant The IBM Support Assistant (ISA) is a free local software serviceability workbench that helps you resolve questions and problems with IBM software products. The ISA provides quick access to support-related information and serviceability tools for problem determination. To install the ISA software, go to Conventions used in this publication This publication uses several conventions for special terms and actions and operating system-dependent commands and paths. Typeface conventions This publication uses the following typeface conventions: Bold Italic Monospace v Lowercase commands and mixed case commands that are otherwise difficult to distinguish from surrounding text v Interface controls (check boxes, push buttons, radio buttons, spin buttons, fields, folders, icons, list boxes, items inside list boxes, multicolumn lists, containers, menu choices, menu names, tabs, property sheets), labels (such as Tip: and Operating system considerations:) v Keywords and parameters in text v Citations (examples: titles of publications, diskettes, and CDs) v Words defined in text (example: a nonswitched line is called a point-to-point line) v Emphasis of words and letters (words as words example: "Use the word that to introduce a restrictive clause."; letters as letters example: "The LUN address must start with the letter L.") v New terms in text (except in a definition list): a view is a frame in a workspace that contains data v Variables and values you must provide:... where myname represents... v s and code examples v File names, programming keywords, and other elements that are difficult to distinguish from surrounding text v Message text and prompts addressed to the user v Text that the user must type v Values for arguments or command options x IBM Tivoli Network Manager IP Edition: Language Reference

13 Operating system-dependent variables and paths This publication uses environment variables without platform-specific prefixes and suffixes, unless the command applies only to specific platforms. For example, the directory where the Network Manager core components are installed is represented as NCHOME. When using the Windows command line, preface and suffix environment variables with the percentage sign %, and replace each forward slash (/) with a backslash (\) in directory paths. For example, on Windows systems, NCHOME is %NCHOME%. On UNIX systems, preface environment variables with the dollar sign $. For example, on UNIX, NCHOME is $NCHOME. The names of environment variables are not always the same in the Windows and UNIX environments. For example, %TEMP% in Windows environments is equivalent to $TMPDIR in UNIX environments. If you are using the bash shell on a Windows system, you can use the UNIX conventions. About this publication xi

14 xii IBM Tivoli Network Manager IP Edition: Language Reference

15 Chapter 1. Active Object Class files Device class hierarchy Active Object Class (AOC) files are used to define the device class hierarchy upon which Network Manager automatically classifies all discovered network devices after the completion of a discovery. By default, AOC files are stored in the NCHOME/precision/aoc directory. The following topics describe AOC syntax. Network Manager IP Edition uses a class hierarchy to model network devices. The following figure shows an example class hierarchy. Core EndNode InferredDevice NetworkDevice Sun Windows Cisco Bay Cisco 4500 Cisco 7500 Figure 1. Class hierarchy of network devices The management policies specified in the class hierarchy describe how to handle instances of devices and how to handle events related to them. The class hierarchy is available for polling operations. You can specify which classes to include in each polling operation through the poll policy settings. Copyright IBM Corp. 2006,

16 AOC syntax Network Manager IP Edition does not permit multiple inheritance, which is the ability of a new class to inherit the characteristics from more than one class. The following topics describe the classes contained in the hierarchy. EndNode class The EndNode class contains devices such as workstations and printers. Within the EndNode class, the NoSNMPAccess class contains devices that were discovered and added to the topology even though Network Manager IP Edition had no SNMP access to them, such as workstations. Devices might not have SNMP access for one of the following reasons: v The device does not have SNMP capabilities. v Network Manager IP Edition does not have the SNMP credentials to access the device. InferredDevice class The InferredDevice class contains devices that Network Manager IP Edition could not discover directly, although they are considered to exist on the network. You might infer the existence of CE routers for your customer, for example, by specifying the CE routers in the advanced discovery configuration options. NetworkDevice class The NetworkDevice class contains all device types grouped into subclasses according to their manufacturer. All Cisco devices, for example, are contained within the Cisco subclass. The default poll policies are usually defined for network devices and their derived classes. Use this information to understand the structure of AOC files. In addition to the information in this topic, you should also read the OQL language syntax information, in particular, the eval statement. The syntax and naming conventions described in the following table are used throughout the AOCs. Table 1. characters used in AOCs Character Name Meaning [ ] Square brackets Typically defines a list of items. There can be zero or more items within the brackets and each item must be separated by a single comma. Curly brackets Typically defines an object. " " Double quotes Typically used to enclose assignments to various attributes (of datatype text) within an AOC. As a general rule all assignments use double quotes. ' ' Single quotes Typically used to enclose evaluations of column names or system variables within an eval statement. Single quotes can be used within double quotes, but double quotes cannot be used within single quotes. 2 IBM Tivoli Network Manager IP Edition: Language Reference

17 Table 1. characters used in AOCs (continued) Character Name Meaning, Single comma Typically used either as a separator between elements of a list or to terminate an assignment to a particular attribute. ; Semi colon Typically used to terminate assignments to the major components listed below. Components of an AOC file Use this generic description of the structure of an AOC to help you write new AOC files and understand existing AOC files. AOC components The major components of the AOC and descriptions of the components are provided below. v Name of the active object class (active object) v Super class (super_class) v Instantiate rule (instantiate_rule) v Icon used in GUI to represent the device class Name In the active object attribute, you declare the name of the current class. You can specify any unique text string between the double quotes. The entire AOC file is contained within the first pair of curly brackets. A semicolon follows the final bracket to terminate the AOC. active object Linux super_class = EndNode ; instantiate_rule = "EntityOID = OR EntityOID = OR EntityOID = "; ; visual_icon = EndNode ; Super class You can configure the Super class to define the name of the AOC from which the current class inherits. The name between the double quotes must be the name of an already-defined AOC. In the AOC hierarchy, Core is the only class that has an unassigned super_class. When editing any other class, the super_class must never be left empty. super_class = "Core"; Chapter 1. AOC files 3

18 Instantiate rule You code the instantiate rule as a logical test against the attributes of the record of an entity in themaster.entitybyname database of MODEL that defines how the system determines which class an object belongs to. The schema of the master.entitybyname database is defined in the ModelSchema.cfg configuration file. If an object meets the instantiation criteria for more than one class, it automatically instantiates to the lowest leftmost class in the hierarchy. The following example shows a specification of the rule that instantiates everything by default. instantiate_rule = "EntityOID like.* "; Visual icon You can assign icons to device classes. These icons represent devices of that class in the network visuulization GUIs, including the Network Views and the Network Hop View. For information on how to assign icons to device classes, see the IBM Tivoli Network Manager IP Edition Installation and Configuration Guide. 4 IBM Tivoli Network Manager IP Edition: Language Reference

19 Chapter 2. Object Query Language Object Query Language (OQL) is a version of the Structured Query Language (SQL) that has been designed for use in Network Manager IP Edition. The components create and interact with their databases using OQL. Use OQL to create new databases or insert data into existing databases (to configure the operation of Network Manager IP Edition components) by amending the component schema files. You can also issue OQL statements using the OQL Service Provider, for example, to create or modify databases, insert data into databases and retrieve data. For more information about the OQL schema used by Network Manager IP Edition, see the IBM Tivoli Network Manager IP Edition Management Database Reference. The OQL Service Provider is described in the IBM Tivoli Network Manager IP Edition Administration Guide. Conventions and sample databases To illustrate the OQL keywords in use, a sample database has been used, the staff database, which contains three tables: managers, employees, and contractors. Conventions The following conventions have been used to explain the OQL syntax: v OQL keywords and their required punctuation are shown in bold in examples. v Parameters are shown in italics. v Optional parameters are shown enclosed by square brackets []. v OQL commands are terminated with a semicolon. v An ellipsis (...) following a list of parameters indicates that you can continue the list if necessary. v OQL Service Provider command lines are shown with the example command line prompt phoenix:1.> followed by relevant sample output. v The system name within the prompt appears as phoenix within this manual. This is replaced by an appropriate value for your system, such as the host name. Sample databases The following tables contain data in the staff databases. Table 2. Data in the staff.managers database table EmployeeID Name Department Gender Age 1 Matt Development M 28 2 Irene Customer Services F 52 3 Ernie Sales M 23 4 Paul Marketing M 26 Copyright IBM Corp. 2006,

20 Table 2. Data in the staff.managers database table (continued) EmployeeID Name Department Gender Age 5 Jim Support M 27 Table 3. Data in the staff.employees database table EmployeeID Name Skills Gender Age 6 Paul HTML, C++, Java M 26 7 Carl Perl M 32 8 Rob UNIX, Perl M 23 9 Sarah Java, C++ F Lisa UNIX, HTML F 25 Table 4. Data in the staff.contractors database table EmployeeID Name Gender Age ExtraInfo 11 James M 22 ContractLength = 6 months; Department = Marketing; 12 Karen F 25 ContractLength = 5 months; Department = Sales; 13 Jane F 26 ContractLength = 7 months; Department = Development; 14 Richard M 23 ContractLength = 1 month; Department = Operations; 15 Glenn M 28 ContractLength = 2 months; Department = Operations; Features of OQL The following topics describe the features of Object Query Language (OQL). Related reference: Comments on page 104 Comments are introduced by -- or //. If a comment requires a carriage return, the characters on the next line must also be commented out. General rules of OQL OQL has rules that must be applied to all statements. The following rules apply to OQL statements: v All complete statements must be terminated by a semi-colon. v A list of entries in OQL is usually separated by commas but not terminated by a comma. v Strings of text are enclosed by matching quotation marks. The rules for quotation mark usage are described below. 6 IBM Tivoli Network Manager IP Edition: Language Reference

21 Quotes in OQL In OQL the TEXT datatype must be enclosed by matching quotation marks (either single or double quotes). The following example is a standard OQL insert into the CTRL services.intray table, showing values of the TEXT data type enclosed in double quotes, an integer value that is not enclosed in any quotation marks, and a LIST OF TYPE TEXT that is enclosed in square brackets. The comma separated data within the list is enclosed in double quotes. insert into services.intray ( servicename, binaryname, servicepath, domainname, arglist, retrycount ) values ( "ncp_disco", "ncp_disco", "/opt/netcool/precision/solaris2/bin", "MYDOMAIN", [ "-domain", "NCOMS", "-latency", "60000" ], 5 ); Related reference: Stitcher language building blocks on page 102 To construct statements in the stitcher language, use the programming constructs, relational operators, and datatypes. OQL punctuation OQL has a set of punctuation marks that you use to structure OQL statements. The following table describes the punctuation used in the OQL syntax. Table 5. Punctuation used in the OQL syntax Symbol Meaning - Subtraction, negative. + Addition, positive. * Multiplication or a wild card that matches any characters within its expression. ( Encloses items in a list, for example, preceding the insert into statement. ) Encloses items in a list, for example, following the insert into statement., Separates entries in a list. [ ] Encloses items of the list datatype. Encloses items of the object datatype.. Separates database, table and column names. ; Terminates OQL statements. ~ Matches regular expressions. -> Retrieves a sub value of an object. Chapter 2. Object Query Language 7

22 Logical operators of OQL These logical operators are used for OQL: AND and OR. The following table describes the logical operators to use in OQL. Table 6. Logical operators of OQL Keyword AND OR Brief description Combines search conditions, all of which must be true for the condition to be passed. Combines search conditions, one of which must be true for the condition to be passed. Precedence and association of operators The rules for precedence and association of operators determine the grouping of operators with operands, and indicate the order in which the operators in an expression are executed. For complex expressions, use parentheses to avoid ambiguity. The following table describes the operators. Table 7. OQL operators in order of decreasing precedence Operator Description Associativity Precedence - Negative sign Non-associative 1 (highest) * Multiplication Left 2 / Division Left 2 OR Logical OR Left 3 AND Logical AND Left 4 NOT Logical NOT Left 5 = Equal to Left 6 <> Not equal to Left 6 < Less than Left 6 > Greater than Left 6 <= Less than or equal to Left 6 >= Greater than or equal to Left 6 + Addition Left 7 - Subtraction Left 7 (lowest) 8 IBM Tivoli Network Manager IP Edition: Language Reference

23 Use of regular expressions You can use regular expressions in OQL and in stitcher language code. Regular expressions are particularly useful for defining filters. Regular expressions contain a series of characters that define a pattern of text to be matched to make a filter more specialized, or general. For example, the regular expression ^AL[.]* searches for all items beginning with AL. The filter condition EntityName Like ^..N[.]* filters for all devices which have an N as the third letter of their name, and EntityName Like [.]*G filters for all devices whose name ends with the letter G. The following table describes the most common characters used in regular expressions. Table 8. Regular expression characters Character Description \ The backslash (or escape character) quotes the character after it, both special and ordinary.. The dot represents any single character. * Like the dot, an asterisk can represent any character. However, whereas the dot can only represent a single character, the asterisk represents anywhere from zero to an infinite amount of characters. $ The dollar sign at the end of a regular expression signifies the end of a line, and, therefore, any character immediately before it must be located at the end of the string. Anywhere else in a regular expression, it matches itself. Use the backslash to specify a. (normally a special character) in a file name, for example. To select all.sys files you would state, ^*\.sys$, where the backslash specifies that the dot following it is actually a real dot, not just a character representing any single character. A dot can be anything. If you want to select five letter device names that begin with T and end with R, you would state, ^T...R$, where the three dots in the middle mean that the three middle letters of the word can be any letter. *.*, returns strings beginning with any combination and any amount of characters (the first asterisk), and can end with any combination and any amount of characters (the last asterisk). This selects every single string available. [.]*G$ selects every string which ends in G, regardless of the number of characters or types of characters in the string. Chapter 2. Object Query Language 9

24 Table 8. Regular expression characters (continued) Character Description ^ [set] A hat (circumflex) at the beginning of a regular expression means that it is the beginning of a line, and any characters immediately following it must be located at the very beginning of the string. Anywhere else in a regular expression, it matches itself. A set of characters in square parentheses matches any single character from a set. ^AL[.]* returns strings beginning with AL. ^..N[.]* returns strings beginning (^) with any two characters and the third character is an N. ^[abc].[def]$ selects all three character strings that begin with either a or b or c and end in either d or e or f. Key differences between OQL and SQL OQL differs from SQL in several ways. Database and table creation v OQL supports object referencing within tables. Objects can be nested within objects. v Not all SQL keywords are supported within OQL. Keywords that are not relevant to Network Manager IP Edition have been removed from the syntax. v OQL can perform mathematical computations within OQL statements. You can create databases and tables with the create command. You can issue the create command to create a database. create database database_name ; You can issue the create command to create a table. When you create a table, you must define all the columns of the table as well as a datatype, such as text or integer, and if applicable, the column constraints and any default values. create table database_name.table_name ( column_name [ constraints ] [ default default ], [ column_name [ constraints ] [ default default ], ] [ additional_columns ] [ unique ( column_name ), ] [ counter ( column_name ), ] [ timestamp ( column_name ) ] ); The entries within the brackets are separated by commas, although the last entry is not terminated by a comma. The following topics describe how to use the create command. 10 IBM Tivoli Network Manager IP Edition: Language Reference

25 Datatypes All columns must have an associated datatype that indicates the acceptable input for that column. The following table describes the datatypes that are used in OQL: Table 9. Datatypes of OQL Datatype TEXT INT UINT FLOAT LONG64 ULONG64 DATA LIST TYPE datatype OBJECT TYPE datatype TIME Description Holds plain text. Holds integer values. Holds a 32-bit unsigned integer value. Holds decimal values. Holds a 64-bit numerical value. Holds a 64-bit unsigned numerical value. Holds opaque data, typically of the binary format. Holds a list of particular datatypes. The list is enclosed in square brackets, []. Holds objects of particular datatypes. The object is enclosed in curly braces,. Objects hold a list of varbinds (name/value pairs). Holds information pertaining to time. Objects and varbinds An object is a comma-separated list of varbinds enclosed by curly braces, whereas a varbind is a name/value pair, for example, ifindex=20 or ifdescr="utp10/100". You can perform operations on one of the varbinds in an object using the -> symbol. Related reference: selection based on part of an object on page 20 Use this example to orient yourself when retrieving records from tables based on criteria that apply to parts of a table row. of updating an object on page 26 Use this example to learn how to use the update keyword in an object. External datatypes It is possible to define additional datatypes that map integers to the possible values of a column; these datatypes are called external datatypes, because they are defined externally to the present schema. In order to use a datatype that has been defined in a previously loaded schema, the current schema must contain a statement of the following structure. data type datatype is external datatype ; s The following examples show the datatype declaration. data type boolean is external boolean data type entitytypes is external entitytypes Chapter 2. Object Query Language 11

26 After you have made these declarations you can use the datatypes boolean and entitytypes in the current schema, provided that they have also been defined in a previously loaded schema. Column constraints Column constraints are restrictions on the data that can be inserted into a given column. The following table describes the column constraints. Any of these constraints can be applied to any column. Table 10. Column constraints Constraint NOT NULL Description Indicates that the column must be assigned a value. PRIMARY KEY NULL is not the same as zero or white space. Denotes that the column is a primary key for the table. The primary keys can be used to join related tables in a multiple table query. The combination of data in the PRIMARY KEY columns of a given table must be unique, although the data in each individual column does not necessarily have to be unique. For example, the primary key might comprise the multiple fields of forename, surname, and age. The primary key is internally indexed and so provides faster query times, but slower insert and delete times. Unique and indexed fields are also internally indexed. List and object fields cannot be indexed, thus they cannot be set as primary keys, unique fields, nor as part of an index definition. If multiple constraints are specified for a single column, NOT NULL must be specified before PRIMARY KEY. Default values A default value can be applied to a column when it is created with the default keyword. If an explicit value is not provided for that column when data is inserted, the specified default value is used. Unique The optional unique column constraint ensures that all entries in the specified column are unique. The unique column is internally indexed and so provides faster query times, but slower insert and delete times. List and object fields cannot be indexed, thus they cannot be set as unique fields, nor as part of an index definition. 12 IBM Tivoli Network Manager IP Edition: Language Reference

27 Counter The optional counter column constraint delegates the responsibility of counting duplicate records to the specified column. If you attempt to insert a duplicate record into the table, the insertion of the duplicate entry is suppressed and the value of the specified column is incremented in the record that already exists. Timestamp The optional timestamp column constraint stores the date and time information for the creation of the record in the specified column of the database table. The timestamp properties are: v Format: YYYY-MM-DD HH:MM:SS.nnnnn... v Range: :00:00...to :59: s of database and table creation The following examples use the create keyword to create the sample staff database and define the tables. These example OQL statements illustrate the use of the column constraints and the default keyword. 1 create database staff; // creates the staff database The following insert defines the managers table. create table staff.managers ( EmployeeID int NOT NULL PRIMARY KEY, Name text NOT NULL, Department text default "Sales", Gender text, ); Age unique ( EmployeeID ) For the managers table: v The EmployeeID and Name columns cannot be NULL. int, // indicates that the data in the // EmployeeID column must be unique. v The EmployeeID column is the primary key and must be unique. v If no value is inserted into the Department column for a given record it takes the value "Sales". 2 The following insert creates the staff.employees table. create table staff.employees ( EmployeeID int NOT NULL PRIMARY KEY, Name text NOT NULL, Skills list type text, Gender text, Age int // There is no comma here because this // is the last entry. ); Chapter 2. Object Query Language 13

28 For the staff.employees table: v The EmployeeID and Name columns cannot be NULL. v The Skills column is a list of text strings. 3 The following insert creates the staff.contractors table. create table staff.contractors ( EmployeeID Name Gender Age ExtraInfo volatile ); Inserting data into a table For the staff.contractors table: int NOT NULL PRIMARY KEY, text NOT NULL, text, int, object type vblist, v The ExtraInfo column contains a list of varbinds. Use the insert keyword to insert data into a table. The following example shows how to use the insert keyword: insert into ( ) values ( ); column [, column ] [, column ] [... ] data [, data ] [, data ] [... ] database_name.table_name Each data value is inserted into the corresponding column name, so the number of data values (and the data types) must correspond with the number of column names specified. Although it is not good practice, it is acceptable to omit the list of column names. If you choose to omit the column names, the first value specified after the values keyword is inserted into the first column of the database, the second value into the second column, and so on. Additionally, if you omit the column names, the number of values must correspond to the number of columns in the database, so you must either insert a value into each database column or explicitly specify NULL for columns into which you do not wish to insert a value. The following topics provide further examples of the insert keyword. 14 IBM Tivoli Network Manager IP Edition: Language Reference

29 of inserting data into a database Use this example to orient yourself when you insert data into your own databases. The population of the sample databases with data is shown in the following examples, which highlight some of the different valid forms of the insert statement. The following example specifies all the column names. insert into staff.managers ( EmployeeID, Name, Department, Gender, Age ) values ( 1, "Matt", "Development", "M", 28 ); The following example does not specify column names, but is still a valid insert because a value has been specified for each column of the database. insert into staff.managers values ( 2, "Janet", "Customer Services", "F", 27 // no column names are specified, so the values are inserted // into the columns in order. ); The following example specifies no value for the Department column, which is populated with the default value instead: insert into staff.managers ( EmployeeID, Name, Gender, Age ) values ( 3, "Phil", "M", 25 // No value for Department has been specified. The column // therefore takes the default value "Sales" that was specified // when the table was created. ); Related reference: Conventions and sample databases on page 5 To illustrate the OQL keywords in use, a sample database has been used, the staff database, which contains three tables: managers, employees, and contractors. of an invalid insert Use this example to troubleshoot problems and errors if any occur when you insert data into your databases. Since staff.managers is unique on the EmployeeID column, the following insert is invalid, and therefore rejected, because there is already a record with EmployeeID=3. insert into staff.managers ( EmployeeID, Name, Department, Gender, Age ) values ( 3, "John", "Marketing", "M", 26 ); Related reference: Chapter 2. Object Query Language 15

30 Conventions and sample databases on page 5 To illustrate the OQL keywords in use, a sample database has been used, the staff database, which contains three tables: managers, employees, and contractors. list and object datatypes Use this example to orient yourself when using list and object datatypes. The following example is an insert into the staff.employees table, where the Skills column has been defined as list type text. insert into staff.employees ( EmployeeID, Name, Skills, Gender, Age ) values ( 6, "Matt", [ "HTML", "C++", "Java" ], "M", 24 ); The following example is an insert into the staff.contractors table, where the ExtraInfo column has been defined as object type vblist: insert into staff.contractors ( EmployeeID, Name, Gender, Age, ExtraInfo ) values ( 11, "James", "M", 22, ContractLength=6, Department="Marketing" ); Related reference: Selecting data from a table Conventions and sample databases on page 5 To illustrate the OQL keywords in use, a sample database has been used, the staff database, which contains three tables: managers, employees, and contractors. You can query the data in a table using the select keyword. Use these examples to help you use the select keyword. 1 on page 17 2 on page 17 3 on page 17 The following syntax shows how to use the select keyword to retrieve data from a table. select comma_separated_column_list_or_wildcard from database_name.table_name [ where conditional_test ] [ order by field_name [asc desc] ]; The * symbol can be used as a wildcard in a select statement to return all the columns of the table. Alternatively a comma-separated list of columns can be specified. If you specify an order by clause, then results are returned in ascending order by default. NULL values are returned first when the results are in ascending order. 16 IBM Tivoli Network Manager IP Edition: Language Reference

31 Ordering of results in descending order is the exact opposite of the ordering of results in ascending order. 1 The following example shows how to use the select statement within the OQL Service Provider to query the staff.managers table (the following example output is abbreviated). phoenix:1.> select * from staff.managers; phoenix:2.> go... EmployeeID=1; Name= Matt ; Department= Development ; Gender= M ; Age=28; EmployeeID=2; ( 5 record(s) : Transaction complete ) 2 The following example shows a select statement that retrieves only specific fields from the staff.managers table. phoenix:1.> select Name, Gender from staff.managers; phoenix:2.> go... Name= Matt ; Gender= M ; Name= Irene ; Gender= F ; Name= Ernie ; ( 5 record(s) : Transaction complete ) 3 The following example uses a where clause to restrict the results. phoenix:1.> select EmployeeID, Name from staff.managers phoenix:2.> where Department = "Marketing"; phoenix:3.> go. EmployeeID=4; Name= John ; ( 1 record(s) : Transaction complete ) Chapter 2. Object Query Language 17

32 Counting rows in a table You can count the number of rows in a table using the select keyword. The following syntax shows how to use the select keyword to count the number of rows in a table. select count(*) from database_name.table_name [ where conditional_test ] 1 Conditional tests in OQL The following example shows how to use the select statement within the OQL Service Provider to count the number of rows in the staff.managers table. phoenix:1.> select count(*) from staff.managers; phoenix:2.> go... Count=5; ( 1 record(s) : Transaction complete ) Use comparison operators in OQL, for example in a select where statement, to perform conditional tests. The following table describes the comparison operators that you can use. Table 11. Comparison operators in OQL Symbol Description = Equal to. <> Not equal to. < Less than. > Greater than. <= Less than or equal to. >= Greater than or equal to. like in Compares for similarity using UNIX-style regular expressions. The like operator is more powerful than the traditional SQL implementations that use the more limited token matching for comparison. Searches for the presence of a record within a specified table (using a subquery). is null is not null The in operator can also be used to determine whether a specified value is contained in a list field. Tests whether the specified column is null (that is, has not been assigned a value). Tests whether the specified column is not null (that is, has been assigned a value). 18 IBM Tivoli Network Manager IP Edition: Language Reference

33 s of the like operator Use these examples to help you use the like operator in search criteria. v 1 v 2 v 3 1 The following example query identifies the records in the employees table that contain the lowercase letter r in the Name column. phoenix:1.> select Name from staff.employees phoenix:2.> where Name like ".*[r].*"; phoenix:3.> go.. Name= Carl ; Name= Sarah ; ( 2 record(s) : Transaction complete ) 2 The following example query identifies the records in the employees table for which the Name column begins with an uppercase C or upper R. phoenix:1.> select Name from staff.employees phoenix:2.> where Name like "^[CR]"; phoenix:3.> go.. Name= Carl ; Name= Rob ; ( 2 record(s) : Transaction complete ) 3 The following example query would return the complete records of all employees listed in the contractors table whose name begins with an uppercase letter J. phoenix:1.> select EmployeeID, Name from staff.contractors phoenix:2.> where Name like "J"; phoenix:3.> go.. EmployeeID=11; Name= James ; EmployeeID=13; Name= Jane ; ( 2 record(s) : Transaction complete ) Related reference: Conventions and sample databases on page 5 To illustrate the OQL keywords in use, a sample database has been used, the staff database, which contains three tables: managers, employees, and contractors. Chapter 2. Object Query Language 19