Tivoli Management Solution for Microsoft SQL. Rules Syntax. Version 1.1

Transcription

1 Tivoli Management Solution for Microsoft SQL Rules Syntax Version 1.1

2

3 Tivoli Management Solution for Microsoft SQL Rules Syntax Version 1.1

4 Tivoli Management Solution for Microsoft SQL Copyright Notice Copyright IBM Corporation 2000 All rights reserved. May only be used pursuant to a Tivoli Systems Software License Agreement, an IBM Software License Agreement, or Addendum for Tivoli Products to IBM Customer or License Agreement. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without prior written permission of IBM Corporation. IBM Corporation grants you limited permission to make hardcopy or other reproductions of any machine-readable documentation for your own use, provided that each such reproduction shall carry the IBM Corporation copyright notice. No other rights under copyright are granted without prior written permission of IBM Corporation. The document is not intended for production and is furnished as is without warranty of any kind. All warranties on this document are hereby disclaimed, including the warranties of merchantability and fitness for a particular purpose. U.S. Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corporation. Trademarks IBM, the IBM logo, Tivoli, the Tivoli logo, AIX, Cross-Site, NetView, OS/2, Planet Tivoli, RS/6000, Tivoli Certified, Tivoli Enterprise, Tivoli Ready, and TME are trademarks or registered trademarks of International Business Machines Corporation or Tivoli Systems Inc. in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Other company, product, and service names may be trademarks or service marks of others. Notices References in this publication to Tivoli Systems or IBM products, programs, or services do not imply that they will be available in all countries in which Tivoli Systems or IBM operates. Any reference to these products, programs, or services is not intended to imply that only Tivoli Systems or IBM products, programs, or services can be used. Subject to valid intellectual property or other legally protectable right of Tivoli Systems or IBM, any functionally equivalent product, program, or service can be used instead of the referenced product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by Tivoli Systems or IBM, are the responsibility of the user. Tivoli Systems or IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, New York , U.S.A.

5 Contents Chapter 1. Tivoli Management Solution for Microsoft SQL Tivoli Rules Additional Information Section I: The Structure of Rules Section II: Rule Syntax Chapter 2. Section I Structure of the Rules Conditions The CONDITION Statement Expressions Expression Functions Expression Operators Actions Action Blocks The ACTION Statement Built In Actions Symbol Substitution in Actions Schedules Selections Chapter 3. Section II Rule Syntax.. 23 Rule Context Metacharacters Case Sensitivity Quoted Text General File Statements Including Statements from Another File Macros Symbol Substitution Object Definitions Predefined Symbols Predefined Variables Default Variable File Text Blocks Variables Schedules Selections Rules Actions Chapter 4. Action List APPEND CALCULATE CHECK_BOUNDS CLOSE COPY CREATE DECREMENT DELETE DISABLE ENABLE EVENT EVENT TYPE=TEXT EVENT TYPE=MESSAGE EVENT TYPE=PROBLEM EVENT TYPE=WINDOWS EXECUTE EXECUTE_SQL EXIT EXPORT IF INCREMENT LOG MAIL MODIFY PRIORITY READ REMOVE SNMP_SET SNMP_TRAP TERMINATE WAIT WORKING_SET WRITE ZERO iii

6 iv Tivoli Management Solution for Microsoft SQL: Rules Syntax

7 Chapter 1. Tivoli Management Solution for Microsoft SQL Tivoli Management Solution for Microsoft SQL for Windows NT is a BackOffice certified software product that monitors a running Windows NT system, emulating the intelligence and reasoning abilities of a human expert as it proactively detects and corrects system and application problems. Tivoli Management Solution for Microsoft SQL capabilities include problem detection, problem resolution, staff notification, remote site management, and centralized event monitoring. By automating these functions and correcting problems before they interfere with system use, Tivoli Management Solution for Microsoft SQL ensures the highest level of service to users while allowing staff the time to focus on more complex planning and problem-solving activities. Tivoli Rules Tivoli rules monitor for conditions of interest on your system and take actions based on the conditions found. The Solutions rules provided with Tivoli Management Solution for Microsoft SQL are based on years of Windows NT experience and have been designed to address the monitoring needs of most users. You may also wish to embody your own site-specific expertise by using Tivoli s Rule Development System to add additional rules. Rules are written using a simple English-like rule definition language. The flexibility of Tivoli s rule architecture provides virtually unlimited problem detection capabilities. This manual provides the information you will need to access Tivoli s Rule domain, which is responsible for the organization and execution of rules written by Tivoli Management Solution for Microsoft SQL users. Additional Information This manual is designed for users who are familiar with the basic operation of Tivoli Management Solution for Microsoft SQL and wish to write new rules to satisfy unique requirements. The sections included in this manual are presented below. The entire manual may be stepped through using the browse buttons. Topics may be directly accessed by clicking on the highlighted text Section I: The Structure of Rules Section II: Rule Syntax Section I describes the features and capabilities of Tivoli rules and the Rule Development System. A Tivoli rule is generally composed of a condition to look for on the system and at least one action to perform based on evaluation of the condition. The schedule and selection of a rule determine when and on which entities the rule will be executed. These basic elements are the building blocks of every rule, from the simplest to the most sophisticated. Rules are written in rule files. You may place all rules in a single rule file or use several rule files to organize your rules. Section II provides a detailed presentation of Tivoli s rule syntax, including examples of how the syntax is used. This section also contains a keyword list. 1

8 2 Tivoli Management Solution for Microsoft SQL: Rules Syntax

9 Chapter 2. Section I Structure of the Rules Conditions This section describes the features and capabilities of Tivoli Rules. A Tivoli rule is generally composed of a condition to look for on the system and at least one action to perform based on evaluation of the condition. The schedule and selection of a rule determine when and on which entities the rule will be executed. These basic elements are the building blocks of every rule, from the simplest to the most sophisticated. Rules are written in rule files. You may place all rules in a single rule file or use several rule files to organize your rules. Section I covers the following subjects: v Conditions v Actions v Schedules v Selections The condition statement defines a condition expression to be evaluated by Tivoli Management Solution for Microsoft SQL. If a rule does not include a condition statement, the specified action is always performed. conditions range from simple statements to highly sophisticated tests based on a variety of statistics, variables, operators, and functions. Examples of simple conditions include: v CPU busy percentage exceeds a threshold. v A named process is missing. v Free space is below a minimum value. v A file is growing rapidly. The flexibility of condition statements allows Tivoli Management Solution for Microsoft SQL to accurately diagnose a broad range of site-specific problems, measure the urgency of a situation, and implement corrective actions appropriate to specific circumstances. If a rule evaluates entities such as processes or files, Tivoli Management Solution for Microsoft SQL automatically performs iteration to evaluate the condition for each entity. Event Correlation Tivoli Management Solution for Microsoft SQL is also capable of event correlation, which allows the software to diagnose a problem by evaluating multiple conditions with logical and relational operators. For example, suppose that a database server process experiences heavy CPU usage at the same time that the network experiences excessive traffic. This may indicate an excessive number of remote clients. Tivoli Management Solution for Microsoft SQL can evaluate both conditions and perform a specified series of actions to correct the problem. Event correlation can also be implemented through rules which interact with one another. For example, the action of one rule can execute another rule that evaluates a related problem. 3

10 Statistics Tivoli Management Solution for Microsoft SQL provides over 1400 statistics that can be used in condition testing to monitor conditions and events on your system. Variables Unlike a statistic, a variable s value can be set to a specific value or according to a formula specified in a rule. Variables provide programming capabilities, pass information between different rules, and allow you to save information across reboots. Variables are global in nature; the value of any variable in one rule is available to all other rules. Operators In condition expressions, arithmetic (+,-,*,/,%), logical (NOT, AND, OR, XOR ), and relational (=,>,>=,<,<=,<>)operators are used to perform calculations, determine percentages, test multiple or compound conditions (event correlation), compare statistics to a numerical value, etc. A few examples of condition expressions are shown below: v A few examples of condition expressions are shown below: v Variable X exceeds the value of variable Y. v Statistic B equals zero AND variable Z exceeds a threshold. v Statistics A and B added together exceed twenty. v Variable X OR variable Y equals or exceeds value of statistic C. Functions In addition to operators, functions are also available for manipulation of statistics and variables. Functions provide capabilities such as: sums, averages, and other cumulative values across multiple entities; sums and averages across time; and manipulation of string statistics such as file specifications. The CONDITION Statement Description: The CONDITION statement defines a rule condition for Tivoli Management Solution for Microsoft SQL to monitor. In order to evaluate a rule, Tivoli Management Solution for Microsoft SQL evaluates its CONDITION expression. When expressions are evaluated, a non-zero value is interpreted as TRUE and a zero value is interpreted as FALSE. CONDITION statements are optional. If the rule does not include a CONDITION statement, it is interpreted as having a CONDITION expression that always evaluates to TRUE. conditions statements can olny appear within RULE defintions. They cannot be named. When the condition evaluates to TRUE, all actions which follow the ACTION or TRUE_ACTION statement are executed. If the condition evaluates to FALSE, all actions which follow the FALSE_ACTION statement are executed. The actions which follow the NEW_ACTION, UPDATE_ACTION and CLOSE_ACTION are executed based on the state of the rule. NEW_ACTION is executed the first time the rule is true, UPDATE_ACTION is executed the second time and each subsequent time the rule is true and CLOSE_ACTION is executed the first time the rule is false after being true. The actions which follow the PROLOGUE_ACTION are executed before anything else executes for the rule. The actions that follow the EPILOGUE_ACTION are executed after everything else executes for the rule. Both the PROLOGUE_ACTION and EPILOGUE_ACTION execute whether the condition is true or false. Note that PROLOGUE_ACTION and EPILOGUE_ACTION execute 4 Tivoli Management Solution for Microsoft SQL: Rules Syntax

11 once per rule whereas the other actions execute once per entity per rule. An entity is dependent on what is being collected, for example a file or a process. Syntax [CONDITION Expression] Examples CONDITION FILE_DACL_EXISTS = 0 This condition tests for the value of the statistic FILE_DACL_EXISTS to be equal to 0. CONDITION FILE_SIZE_BYTES > AVG$(FILE_SIZE_BYTES) This condition tests for the size of a file to be greater than the average size of all of the files collected See the following topics for additional Information: v Expressions v Object Definitions v Keyword List v Rule Syntax Expressions Expressions are used in the CONDITION, CALCULATE, IF and STATISTIC statements. See Expression Functions and Expression Oeprators. Data types: There are three basic data types which may be used: integer, floating point and string. When a string is used in an expression position that requires a number, the string is converted to a numeric value according to the following rules: 1. If the string is an ASCII number that number is used. 2. If the string is not an ASCII number, the first letter is checked. If the letter is one of Y, y, T, or t a value of 1 is used; otherwise a value of 0 is used. If a floating point number is used when an integer is required, the floating point number is converted to an integer. If the floating point value is outside the legal range of values for an integer, a value of 1 or -1 will be used (dependent on whether the original value is positive or negative respectively). If a number is used when a string is required, the ASCII representation of the number is used as the string value. Symbols: All items in the expression are assumed to be statistics, user-defined statistics, variables (which should already be in memory), or constants. The operands should be statistic names, user-defined statistic names, variable names, numeric constants, or string constants which are contained in quotes. The statistic and variable names should not be enclosed in the curly brackets {}. Variable values will be retrieved from the rule engine memory structures. If the variable does not exist in these structures, it will be looked for in the default variable file. If it is not in the default file, a value of zero will be used. Examples: v FILE_SIZE_BYTES > AVG$(FILE_SIZE_BYTES) Chapter 2. Section I Structure of the Rules 5

12 This expression is true if the size of a file is greater than the average size of all of the files collected See the following topics for more information: v Expression Operators v Expression Functions v Object Definitions v Keyword List v Rule Syntax Expression Functions The following functions may be used in expressions. ASCII$(string) Returns the ASCII value of the first character in the passed string. Example: ASCII$("ABC") evaluates to 65 AVG$(statistic [,context]) Computes the average value of the specified statistic across all entities which match the specified context. Context may be a single value or may include wildcards and lists. If the context results in a single value, the AVG$ is the same as the original value. The context should contain a list or wildcards (or not be specified at all) in order for this function to provide any service. Examples: AVG$(DISK_SIZE_BYTES) returns the average size in bytes of all disks. AVG$(DISK_SIZE_BYTES, "0,1") returns the average size in bytes of disks 0 and 1. CHAR$(integer-value) Returns a string consisting of one character equal to the passed ASCII integer value. If the passed integer value is not in the range 0 to 255 then a null string is returned. Examples: CHAR$(66) evaluates to B CUM$(statistic, type [,context]) Computes the requested type of value across all intervals, for the specified statistic. Type is AVERAGE, MINIMUM, MAXIMUM, SUM and context may be a single value or may include wildcards and lists). Examples: CUM$(DISK_SIZE, MINIMUM ) returns the minimum number of bytes for all disks across all intervals CUM$(DISK_SIZE, AVERAGE) returns the average number of bytes for all disks across all intervals CUR_DATE$(component) Returns specified component from the current date and time. Component should be a variable name or a quoted string. The legal values for component include: DAY, MONTH, MONTH_NAME, YEAR, HOUR, 6 Tivoli Management Solution for Microsoft SQL: Rules Syntax

13 MINUTE, SECOND, DAY_OF_WEEK, DAY_OF_WEEK_NAME, DATE, TIME, DATE_TIME, DATE_ASCII, TIME_ASCII, DATE_TIME_ASCII Examples: CUR_DATE$("MONTH") evaluates to 8 (assuming that the current date is August 1, 1993) CUR_DATE$("MONTH_NAME") evaluates to AUGUST CVTFI$(number) Converts a floating point number to an integer. If the floating point number exceeds the limits of an integer value, the return value will be 1 when the floating point number is positive and -1 when the floating point number is negative. Example: CVTFI$(123.45) evaluates to 123 CVTFS$(number) Converts a floating point number to a string. The number is formatted with a maximum of 10 decimal places. Example: CVTFS$( ) evaluates to the string CVTIF$(number) Converts an integer to a floating point number. Example: CVTIF$(1023) evaluates to CVTIS$ Converts an integer to a string. Example: CVTIS$(2034) evaluates to the string 2034 CVTSF$(string) Converts a string to a floating point number. If the string is a valid ASCII floating point number, the number is the return value. If the string is not a valid ASCII number, the first character of the string is examined. If the first character is T, t, Y, or y, the return value is 1.0; if the first character is any other character, the return value is 0.0. Examples: CVTSF$(" ") evaluates to CVTSF$("TEST") evaluates to 1.0 CVTSF$("STRING") evaluates to 0.0 CVTSI$(string) Converts a string to an integer. If the string is a valid ASCII integer number, the number is the return value. If the string is not a valid ASCII number, the first character of the string is examined. If the first character is T, t, Y, or y, the return value is 1; if the first character is any other character, the return value is 0. Examples: CVTSF$("123") evaluates to 123 Chapter 2. Section I Structure of the Rules 7

14 CVTSF$("TEST") evaluates to 1 CVTSF$("STRING") evaluates to 0 DATE$(number, component) Returns specified component from passed date Component should be a variable name or a quoted string. The legal values for component include: DAY, MONTH, MONTH_NAME, YEAR, HOUR, MINUTE, SECOND, DAY_OF_WEEK, DAY_OF_WEEK_NAME, DATE, TIME, DATE_TIME, DATE_ASCII, TIME_ASCII, DATE_TIME_ASCII. The value of number would be a Tivoli numeric date (such as the value of the DATE statistic). Example: DATE$(34812, "DAY") evaluates to 25 (when is the value of the DATE statistic on April 25, 1995) EDIT$(string, edit-options Returns a string that is an edited version of the passed string. The edit options are specified as string containing a comma separated list. In the case of conflicting options, the last option specified is used. The legal edit options are: LOWER_CASE, UPPER_CASE, NO_LEADING_SPACES, NO_TRAILING_SPACES, ONE_SPACE, NO_SPACES. Example: EDIT$("A B C D", "UPPER_CASE,NO_SPACES") evaluates to ABCD ENVIRONMENT$(name) Returns the value of the specified environment variable. Name should be a variable name or a quoted string. Example: ENVIRONMENT$( HOME ) evaluates to the value of the HOME registry entry FIELD$(string, delimiter, number) Returns a string which is the field specified by the integer field number for the passed string and delimiter. The delimiter can be more than a single character. Example: FIELD$("MON\TUE\WED\THU\FRI\SAT\SUN", "\", 3) returns Wed FIELD_COUNT$(string, delimiter) Returns an integer which is the number of fields in the passed string based on the passed field delimiter. The delimiter can be more than a single character. If the delimiter does not appear in the string and the string is not null then 1 is returned. Examples: FIELD_COUNT$("MON\TUE\WED\THU\FRI\SAT\SUN", "\") evaluates to 7 FIELD_COUNT$("\MON\TUE\WED\THU\FRI\SAT\SUN", "\") evaluates to 8 due to the leading delimiter FIELD_POSITION$(string, delimiter, number) Returns an integer which is the beginning byte position of the field specified by the integer field number for the passed string and delimiter. The delimiter can be more than a single character. Byte positions begin at 1. 8 Tivoli Management Solution for Microsoft SQL: Rules Syntax

15 Example: FIELD_POSITION$("MON\TUE\WED\THU\FRI\SAT\SUN", "\", 3) evaluates to 9 FIND$(string, substring) Returns a number which is the position within string where substring is located. Positions begin at 1. Example: FIND$("ROBOMON_SERVER", "MON") evaluates to 5 FINDB$(string, substring) Returns a number which is the position within string where substring begins. Positions begin at 1. (This is the same as FIND$.) Example: FINDB$("ROBOMON_SERVER", "MON") evaluates to 5 FINDE$(string, substring) Returns a number which is the position within string where substring ends. Positions begin at 1. Example: FIND$("ROBOMON_SERVER", "MON") evaluates to 7 LENGTH$(string) Returns a number which is the length of string. Example: LENGTH$("ROBOMON_SERVER") evaluates to 14 MAX$(statistic [,context]) Computes the maximum value of the specified statistic across all of the entities which match the specified context (context may be a single value or may include wildcards and lists). If the context results in a single value, the MAX$ is the same as the original value. The context should contain a list or wildcards (or not be specified at all) in order for this function to provide any service. Examples: MAX$(FILE_SIZE_BYTES) returns the size of the biggest file collected. MAX$(FILE_SIZE_BYTES, "file1") returns the size of file1. Not at all useful) MAX$(FILE_SIZE_BYTES, "abc*") returns the size of the biggest file collected beginning with the letters abc MIN$(statistic [,context]) Computes the minimum value of the specified statistic across all of the entities which match the specified context (context may be a single value or may include wildcards and lists). If the context results in a single value, the MIN$ is the same as the original value. The context should contain a list or wildcards (or not be specified at all) in order for this function to provide any service. Examples MIN$(FILE_SIZE_BYTES) returns the size of the smallest file collected. MIN$(FILE_SIZE_BYTES, "file1") returns the size of file1. Not at all useful) Chapter 2. Section I Structure of the Rules 9

16 MIN$(FILE_SIZE_BYTES, "abc*") returns the size of the smallest file collected beginning with the letters abc PADL$(string, padchars, length) Returns the passed string left padded with the passed padchars to the specified length. If the passed string is already equal or longer than the specified length then the string is simply returned as is. The padchars string will be repeated until the desired length is reached. If necessary, a leading portion of padchars will be used to get to the specified length. Examples: PADL$("SAMPLE", "*", 11) evaluates to *****SAMPLE PADL$("SAMPLE", "/*", 11) evaluates to /*/*/SAMPLE PADR$(string, padchars, length) Returns the passed string right padded with the passed padchars to the specified length. If the passed string is already equal or longer than the specified length then the string is simply returned as is. The padchars string will be repeated until the desired length is reached. If necessary, a leading portion of padchars will be used to get to the specified length. Examples: PADR$("SAMPLE", "*", 11) evaluates to SAMPLE***** PADR$("SAMPLE", "/*", 11) evaluates to SAMPLE/*/*/ REMOVE$(string, remove-string) Removes all characters from the input string that appear in the remove string. Note that the remove string is a list of characters, not a pattern to be matched. Example: REMOVE$("AyBzCyDzE F G", "y z") evaluates to ABCDEFG REPLACE$(string, replace-string) Replaces all unprintable characters in the string argument with the characters in the replace-string argument. Please note that <27> indicates an escape character) Example: REPLACE$("SAMPLE<27>REPLACEMENT<27>STRING", "***") evaluates to SAMPLE***REPLACEMENT***STRING ROUND$(number, precision) Returns a number round to the specified decimal places (where a negative precision indicates a power of ten). Examples: ROUND$(1054, -2) evaluates to 1100 ROUND$(10.54, 1) evaluates to 10.5 SEG$(string, start position, length) Returns a string which is a substring of string that begins at position start position and has a length of length. Positions begin at 1. Example: SEG$("ROBOMON_SERVER", 9, 6) evaluates to server 10 Tivoli Management Solution for Microsoft SQL: Rules Syntax

17 SEGL$(string, length) Returns a string which is a substring of string that begins at the first character and has a length of length. Example: SEGL$("ROBOMON_SERVER", 7) evaluates to RoboMon SEGR$(string, start position) Returns a string which is a substring of string that begins at position start position and ends with the last character of string. Positions begin at 1. Example: SEGR$("ROBOMON_SERVER", 9) evaluates to "server" evaluates to server SEG1$(string, position Returns a string which is the character at position position in string string. Positions begin at 1. Example: SEG1$("ROBOMON_SERVER", 8) evaluates to _ STRING$(string, count) Returns a string consisting of the passed string repeated count times. Example: STRING$("ABC", 3) evaluates to abcabcabc SUM$(statistic [,context]) Computes the sum of the value of the specified statistic across all of the entities which match the specified context (context may be a single value or may include wildcards and lists). Examples: SUM$(FILE_SIZE_BYTES) returns the sum of the sizes of all files collected. SUM$(FILE_SIZE_BYTES, "file1") returns the size of file1. Not at all useful) SUM$(FILE_SIZE_BYTES, "abc*") returns the sum of the sizes of all files collected beginning with the letters abc TRUNC$(number, precision) Returns a number truncated to specified decimal places (where a negative precision indicates a power of ten). Examples: TRUNC$(1034, -2) evaluates to 1000 TRUNC$(1.039, 2) evaluates to 1.03 Expression Operators Table 1 lists the Expression Operators. Table 1. Expression Operators Symbol Expression Operator () Precedence operator v Multiplication / Division Chapter 2. Section I Structure of the Rules 11

18 Table 1. Expression Operators (continued) Symbol Expression Operator % Modulus operator (remainder after division) & Bitwise AND Bitwise OR x Bitwise NOT + Addition for numbers, concatenation for strings (for example: ABC + DEF results in ABCDEF ) - Subtraction for numbers, removal of a substring for strings (for example: ABCDEF - CD results in ABEF ) < Less than <= Less than or equal = Equal >= Greater than or equal > Greater than <> Not equal NOT Logical NOT AND Logical AND OR Logical OR XOR Exclusive OR Actions Tivoli Management Solution for Microsoft SQL is equipped with an extensive array of built-in actions that can be used to automatically correct problems or notify personnel when particular conditions are detected. Specific series of actions can be designated for any condition that may occur on your system. User-defined commands can also be used in actions to allow for virtually unlimited problem correction and notification capabilities. Actions are placed in action blocks. The type of action block chosen defines how the series of actions will respond to the evaluation of the condition statement. Tivoli users can easily create sophisticated series of actions that approach problems in an expert manner, applying increasingly severe measures as a problem persists in time (escalation), evaluating multiple conditions before determining the appropriate action (event correlation), and assuming many responsibilities otherwise performed by system management personnel. For entity-level rules, actions are performed for each entity that meets the criteria of the condition. For additional information, see the follwoing topics: v Action Blocks v Tivoli actions v Symbol Substitution v ACTION keyword 12 Tivoli Management Solution for Microsoft SQL: Rules Syntax

19 Action Blocks The action blocks included in a rule determine which Tivoli actions will be performed based on evaluation of the rule s condition. The many different types of action blocks allow users to provide Tivoli Management Solution for Microsoft SQL with detailed instructions for the execution of specific actions. For example, a true action block executes each time the rule s condition is true, a new action block executes only when the rule s condition is true for the first time, and a false action block executes only when the rule s condition is false. For entity-level rules, Tivoli Management Solution for Microsoft SQL evaluates each eligible entity and performs the appropriate actions for that entity. Action and True Action Blocks Action and true action blocks specify actions to be performed when a rule s condition is true. For example, a condition expression evaluates whether there is a space shortage on a disk and finds that a shortage does exist. The actions included in the action or true action block are then performed. Action and true action blocks are equivalent, and true action blocks are generally used when a rule also contains a false action block, described below. False Action Blocks False action blocks specify that an action is to be performed only if a rule s condition is false. For example, a condition expression evaluates whether there is a space shortage on a disk and finds that no shortage exists. The false action block then sends a mail message indicating that all is well. See note on entity-level rules below. Prologue and Epilogue Action Blocks The prologue action block defines one or more actions to be executed before any other action is performed, and the epilogue action block defines one or more actions to be executed after all other actions are performed. For example, a rule such as the large_inactive_files rule may identify numerous problem files. Rather than sending a mail or log message for each file, you can define a variable to store the names of all files and then send a single message containing all of the names. In this case, the prologue action block would be used to set the variable to zero so that it will be ready to store the current information. The epilogue action block would then send a mail or log message including the variable which lists all problem files. Prologue and epilogue action blocks execute each time the rule executes, regardless of the evaluation of the condition. They execute only once, rather than once per entity. New, Update and Close Action Blocks With new, update, and close action blocks, Tivoli Management Solution for Microsoft SQL makes possible the performance of different actions based on the escalation of a problem over time. New action blocks are executed only when a rule s condition is true for the first time. Perhaps a corrective program or bat file is executed. If the rule s condition is again evaluated as true, the update action block is executed. An update action block may be included to execute a more severe corrective measure or notify a system administrator. When a rule s condition is evaluated as false after having been true, the problem is said to be closed. The close action block may be used to send a mail message or log to a file indicating that all is well. See note on entity-level rules below. Tivoli Management Solution for Microsoft SQL escalation features Tivoli Management Solution for Microsoft SQL escalation features can also be utilized with predefined variables, as described later in this section. Chapter 2. Section I Structure of the Rules 13

20 Special handling of False and Close action blocks for entity-level rules The False and Close action blocks have been designed to ensure that the close actions of a rule execute for an entity after that entity no longer exists. Essentially, in entity-level rules, the false and close actions execute for an entity for one interval after it no longer exists. This ensures that a closed problem can be created in this case. For example, a rule executes for all processes and creates a problem event (in the true actions) if the process is using too much CPU. When the process is no longer using too much CPU, the rule closes the problem (in the close actions). However, if the process is stopped and no longer exists, the close actions will still execute to close the problem. If you do not want this behavior when writing a rule, you should not use false or close actions. Instead, use conditional actions described below within a True action block. Conditional actions The IF expression can be used within any of the action blocks described above to conditionally execute an action or series of actions. Execution is based on the evaluation of an expression that incorporates the full power of condition testing, described under conditions above, including the ability to test if the previous action was successful and how many times the problem has been detected. (Please see Predefined Variables later in this section for more information.) For example: The condition statement of a rule may evaluate whether the CPU is over 70% busy. The first action may simply log the situation to a log file. A conditional action may then be included to evaluate whether the CPU is over 80% busy and, if so, execute a CPU analysis rule. The conditional action could go on to evaluate whether the CPU is over 90% busy and there are three or more processes in the compute queue. If so, a notification could be sent to the system administrator. For more information see the following topics: v Keyword List v ACTION keyword v Condition Keyword v IF Keyword The ACTION Statement Description: ACTION blocks define operations or tasks to be performed by the rule engine based on the result of the condition. If there is no condition the condition is considered to be true. ACTION can only be used within a RULE statement. The ACTION and/or TRUE_ACTION block defines one or more actions to take if the rule s CONDITION is true. The NEW_ACTION block defines one or more actions to take for a newly generated problem (the rule s CONDITION is true for the first time). The UPDATE_ACTION block defines one or more actions to take for a repeating problem (the rule s CONDITION has been true for more than one consecutive interval). The FALSE_ACTION block defined one or more actions to take if the rule s CONDITION is false. The CLOSE_ACTION block defines one or more actions to take for newly fixed problems (the rule s condition is false after having been true on the previous interval). 14 Tivoli Management Solution for Microsoft SQL: Rules Syntax

21 ACTION, TRUE_ACTION, NEW_ACTION, UPDATE_ACTION, FALSE_ACTION and CLOSE_ACTION blocks will execute once per entity based on the condition result. The rule s CONDITION is evaluated once for each entity. Different action blocks may be executed for each entity based on the result of the condition for each. The rule engine will track the condition result per entity so that the appropriate actions may be taken for each. The PROLOGUE_ACTION block defines one or more actions to take before anything else executes for the rule, regardless of the rule s condition. The EPILOGUE_ACTION block defines one or more actions to take after everything else executes for the rule, regardless of the rule s condition. PROLOGUE_ACTION and EPILOGUE_ACTION blocks will execute once per rule rather than once per entity. At least one ACTION, TRUE_ACTION, FALSE_ACTION, NEW_ACTION, UPDATE_ACTION, CLOSE_ACTION, PROLOGUE_ACTION or EPILOGUE_ACTION block is required and must be the last section in a rule definition. Names are optional for action blocks, but are suggested when there is to be more than one block. If an action block does not have a name it is given the NULL name. Action blocks of the same type or condition must have unique names. TRUE_ACTION, NEW_ACTION, UPDATE_ACTION and ACTION are considered to be of the same condition in that they execute when the condition is true. FALSE_ACTION and CLOSE_ACTION are considered to be of the same condition in that they execute when the condition is false. All non-comment lines between the ACTION, NEW_ACTION, UPDATE_ACTION, CLOSE_ACTION, TRUE_ACTION, FALSE_ACTION, PROLOGUE_ACTION, and EPILOGUE_ACTION statements and the next RULE, SCHEDULE, SELECT, TEXT_BLOCK or VARIABLE statements are considered to be action statements. If multiple action blocks will be executed based on the result of the condition, they will be executed in the order in which they appear. For example, a TRUE_ACTION and NEW_ACTION block would both execute for an entity the first time the condition is true. They will be executed in the order they appear in the rule. A TRUE_ACTION and UPDATE_ACTION block would both execute when the condition is true additional times. These would also execute in the order in which they appear in the file. Action blocks which could never be executed in the same rule execution for an entity do not have to be in any particular order. For example, NEW_ACTION, UPDATE_ACTION and CLOSE_ACTION could be specified in any order as only one of these will be executed. Each action statement must appear as one line in the file. The continuation character should be used to extend the definition to multiple physical lines. APPEND Append the string to the string variable Chapter 2. Section I Structure of the Rules 15

22 CALCULATE Calculate the value of a variable. CHECK_BOUNDS Adjust a variable s value to be within defined bounds. CLOSE Close a file. COPY Copy a file CREATE Create a varaible on disk DECREMENT Decrement the value of a variable DELETE Delete a variable on disk. DISABLE Disable an rule or action. ENABLE Enable an rule or action. EVENT Write a message record for Event Monitor or Windows NT use. EXECUTE Execute an operating system command or a rule. EXIT Exit the rule engine. EXPORT Write a binary data file. IF Conditionally execute actions. INCREMENT Increment the value of a variable. LOG Log a message to file or terminal. MAIL Send mail to one or more users. MODIFY Modify a schedule. PRIORITY Alter the scheduling priority of a running process. READ Read a variable from an indexed file or the Windows NT registry. REMOVE Remove a file. SNMP SET Sets the value of an SNMP variable SNMP_TRAP Generates a SNMP trap. TERMINATE Terminate a running process. 16 Tivoli Management Solution for Microsoft SQL: Rules Syntax

23 WAIT Wait until a variable condition is true. WORKING_SET Modifies the working set of a process WRITE Write a variable to an indexed file. ZERO Set a variable s value to zero. The variables $ACTION_STATUS and $ACTION_RESULT will be set to the completion status of each action as it is performed. These are reserved variable names. These will always be set by each action, so that the next action may look at the result of the previous action (i.e. within an IF statement). $ACTION_STATUS is the specific status of the action. $ACTION_RESULT indicates only the success (0) or failure (1) of the action. Restrictions: The ACTION, NEW_ACTION, UPDATE_ACTION, CLOSE_ACTION, TRUE_ACTION, FALSE_ACTION, PROLOGUE_ACTION AND/OR EPILOGUE_ACTION block must contain at least one action statement. Action names must be 1-31 characters in length. Alphanumeric characters and the underscore are legal. Action names (for similar types of action blocks) must be unique within a rule. Built In Actions Tivoli Management Solution for Microsoft SQL provides a variety of built-in actions. These actions can be used to perform an extensive range of activities, including executing corrective measures, notifying personnel, interacting with other rules, and manipulating variables. You can also easily add your own site-specific actions by executing an operating system command, a bat file, or an external program. The built-in actions are described below. Corrective actions attempt to resolve problems automatically by implementing changes on your system. Corrective actions are often the first line of defense when a problem occurs and may achieve a resolution without the need to call on system management personnel, saving time and preventing the interruption of work. The EXECUTE OS_COMMAND action further enhances Tivoli Management Solution for Microsoft SQL capabilities by allowing for interaction with other products, including help desks and various notification packages. EXECUTE Executes an operating system command, a bat file, or external program. EXECUTE_SQL Executes an SQL statement for a database. PRIORITY Alters the scheduling priority of a running process. REMOVE Removes a file. TERMINATE Terminates a running process. WORKING_SET Modfies the working set of a process Chapter 2. Section I Structure of the Rules 17

24 If a corrective action fails to resolve a problem or is not appropriate in a particular instance, notification actions are available to inform system management personnel that the problem exists. EVENT Creates a message event, problem event, or text event which is then available to the Tivoli Event Monitor. LOG Logs a message to a file MAIL Sends electronic mail to one or more people. Rule control actions allow rules to interact with one another, enabling the creation of sophisticated expert systems to respond to a wide range of conditions. Rule control actions also make possible event correlation, in which a variety of potential causes are investigated to determine the best solution to a problem. For example, the failure of a process may be caused by anything from a lack of disk space to an application-specific error to a missing critical file. With rule control actions, the rule that initially detects the process failure can enable other rules that investigate all potential causes and perform appropriate corrective measures. The result is a comprehensive evaluation and a highly-directed, accurate response. DISABLE Disables rules or actions. ENABLE Enables rules or actions EXECUTE RULE Executes an asynchronous rule (not regularly scheduled to) EXIT Exits the rule engine. MODIFY Modifies the schedule of a rule. WAIT Stops execution until the specified conditional expression is satisfied. For advanced monitoring situations, Tivoli Management Solution for Microsoft SQL can be programmed using variables, which are calculated dynamically in rules and evaluated to determine rule behavior in real time. A variety of actions are available to create and utilize variables. These actions are known as file manipulation actions. APPEND Appends a new line and a string. CALCUALTE Calculates the value of a variable. CHECK BOUND Changes the value of a variable to be within a desired range. CLOSE Closes a file. COPY Copies a file. CREATE Creates a variable on disk. DECREMENT Decrements the value of a variable. 18 Tivoli Management Solution for Microsoft SQL: Rules Syntax

25 DELETE Deletes a variable on disk. EXPORT Writes a binary data file. INCREMENT Increments the value of a variable. READ Reads a variable from an indexed file. WRITE Writes a variable to an indexed file. ZERO Sets a variable s value to zero, or null for string variables. Symbol Substitution in Actions Symbol substitution is a powerful capability that provides for specifically directed actions and highly informative notification. In symbol substitution, entity names (such as computer, disk, and process names) and statistical values (such as the percentage of disk space used) can be substituted for symbols in text messages sent to personnel and in information provided to the operating system. For example, a mail message about a disk space shortage could indicate the disk name and the level of the shortage, as well as the date and time at which the shortage occurred. A program used to free storage on the disk could receive the disk name and level of shortage information. Symbols are indicated by curly braces ({ }). A symbol can be a statistic, a user-defined statistic, a variable, a predefined variable, or a predefined symbol. Statistics are values collected from your system by the Tivoli data collector. Tivoli Management Solution for Microsoft SQL provides over 1400 statistics that measure various aspects of your system. You may also create your own user-defined statistics if you wish to calculate a new value within a rule. For example, if you create a user-defined statistic defined as the sum of two provided statistics, you can then reference this value in the condition and actions of the rule. Refer to the description of the STATISTIC statement in RULE definitions for an explanation of how to create a user-defined statistic. In general you will use the same statistics in both the condition and actions of a rule, so that its value is evaluated and then included in a message about the evaluation. Curly braces are used to designate a symbol within an action statement. Curly braces are not used in condition statements. Variables provide programming capabilities, pass information between different rules, and allow you to save information across reboots. Variables can be used to store integers, floating point numbers, or character strings. Variables are global in nature; the value of any variable in one rule is available to all other rules. A variety of predefined variables are available to provide information on the current state of a rule or an action and allow for the escalation of corrective measures as a problem persists in time. $PROBLEM_COUNT and $PROBLEM_STATE enable the rule engine to approach the concept of a problem in much the same way as a human expert, by attempting a remedial action when the problem is first detected and more severe remedial actions if the problem recurs. Chapter 2. Section I Structure of the Rules 19

26 $ACTION_STATUS and $ACTION_RESULT are set whenever an action is executed. These variables may be used in the condition of a rule or in a conditional action, so that a rule or action may evaluate the success of the previous action before executing. The remaining predefined variables, $TRUE_CONDITION_COUNT, $FALSE_CONDITION_COUNT, $NEW_CONDITION_COUNT, $UPDATE_CONDITION_COUNT, and $CLOSE_CONDITION_COUNT, measure the number of times a rule evaluates a particular condition across all entities. These variables do not have final values until the condition has been evaluated in each entity; they represent final counts only when used in epilogue actions. Table 2. Symbol Substitution in Action Variable Value Meaning $PROBLEM_STATE 0 Non-problem 1 New problem (newly generated) 2 Updated (recurring) problem 3 Closed (newly fixed) problem $PROBLEM_COUNT n Number of occurrences since problem was first detected $ACTION_RESULT 0 Success 1 Error $ACTION_STATUS n Specific action result $TRUE_CONDITION_COUNT n Number of times rule s condition was true across all entities $FALSE_CONDITION_COUNT n Number of times rule s condition was false across all entities $NEW_CONDITION_COUNT n Number of times rule s condition defined a new problem across all entities $UPDATE_CONDITION_COUNT n Number of times rule s condition defined an updated problem across all entities. $CLOSE_CONDITION_COUNT n Number of times rule s condition defined a closed problem across all entities. Note: The first four variables in the table above, $PROBLEM_STATE, $PROBLEM_COUNT, $ACTION_RESULT, and $ACTION_STATUS, exist per entity. For example, for a process level rule, these variables will exist for each process evaluated. The remaining variables, $TRUE_CONDITION_COUNT, $FALSE_CONDITION_COUNT, $NEW_CONDITION_COUNT, $UPDATE_CONDITION_COUNT, and $CLOSE_CONDITION_COUNT, are set only after the condition has been evaluated and the actions performed for all entities. They represent final values in epilogue actions only. Predefined Symbols Seven predefined symbols are available if you wish to reference the current 20 Tivoli Management Solution for Microsoft SQL: Rules Syntax

27 rule entity context (CONTEXT ), date (DATE_STR ), computer (COMPUTER ), Tivoli Rule Engine process ID (PID ), rule name (RULE ), time (TIME_STR ), or Tivoli Rule Engine process username (USERNAME ) within an action statement. A special predefined symbol is also available to perform entity existence checking (EXISTS ). Schedules A rule s schedule specifies when the rule will be executed by Tivoli Management Solution for Microsoft SQL. A rule can be executed at a specific time or throughout a range of hours, days, weeks, etc. If a range is specified, an interval is required to determine the frequency of execution within the range. The available scheduling elements include: Table 3. Rule Schedules Schedule Examples Interval Every 15 minutes Times of Day 8 AM and 5 PM Hours of the Day Hours 9-16 (9 AM - 5 PM) Dates December 31, 1995 Days of the Month 1st through the 10th day of the month Days of the Week Every day of the week except the 3rd day (Wed). Weeks of the Month The 2nd week of the month Months of the year The 6th and 12th months of the year (June and Dec) Initially Disabled Rules If you do not wish a rule to immediately begin executing when the Rule Engine is first started, you may disable the rule by including the DISABLE statement. For example, if a rule checks for large inactive files, you may wish to disable the rule at first and enable it only when disk space is low. When you wish the rule to begin execution, you may enable the rule through the graphical user interface or through the action of another rule. Asynchronous Rules A rule that is not regularly scheduled to execute is an asynchronous rule and it is executed only on demand, either by a command issued interactively or from the action statement of another rule. Asynchronous rules cannot have a schedule. If you require a task to be performed both on a scheduled basis and on demand, you can achieve this by creating two different rules. One-Shot Rules If a rule is neither scheduled nor asynchronous, then it is a one-shot rule. A one-shot rule executes only once, when the rule process is started. For example, a one-shot rule might be used to read variables from files so that they will be stored in memory. Defining schedules for Use in Multiple Rules Schedules can be defined outside a rule, named, and then referenced in multiple rules. This eliminates the need to continually redefine an Chapter 2. Section I Structure of the Rules 21