Watch Expressions

Contents
casp1032
A watch expression defines what is monitored by the watch. The watch expression can be as simple as the name of an attribute or as complex as a formula. A watch expression includes attributes and constant values that are related to each other through mathematical symbols and Boolean operators, which are referred to as primitives.
Expressions are evaluated proceeding from left to right in the following order of precedence for primitives:
Precedence
Primitives
1
.# .
2
( )
3
DELTA ( ) COUNTER_DELTA ( )
4
!
5
| &
6
* /
7
+ -
8
= = != >= <= < >
Primitives
Primitives are typically used in expressions that have a left side and a right side. For example, in A+B, + is the primitive defining the relationship between the left side, A, and the right side, B. Parentheses are used to indicate the order of evaluation for expressions with multiple components.
The available primitives are as follows:
  • +
  • -
  • *
  • /
  • ==
  • !=
  • >
  • <
  • >=
  • <=
  • ! (not)
  • & (and)
  • ,
  • |
  • (
  • )
  • TRUE
  • FALSE
  • TIME
  • DELTA
  • MIN
  • MAX
  • INTEGER
  • REAL
  • UNSIGNED
  • COUNTER_DELTA
  • UNSIGNED64
You can group primitives by function and applicability. You can apply the following primitives only between text strings or in numerical expressions:
  • = = equal to
  • >= greater than or equal to
  • <= less than or equal to
  • != not equal to
  • > greater than
  • < less than
These primitives do not support the attribute types Object ID, IP Addr, and Boolean.
You can apply the following primitives only for numerical expressions:
  • + addition
  • - subtraction
  • * multiplication
  • / division
These primitives do not support the attribute types Text String, Object ID, IP Addr, and Boolean. Supported types are evaluated in the following order:
  • Real
  • Time Ticks, Date, Gauge, Counter
  • Enumeration Integer
If elements are from two different levels, they are evaluated as belonging to the higher level. For example, 5 + 5 is evaluated as an integer, while 5 + 5.1 is evaluated as a real.
DX NetOps Spectrum
model types use the attribute type Counter to store unsigned long integers. If you use the unsigned primitive illegally in an expression, for example, "Text String + UNSIGNED(5)", the resulting error message is of type Counter.
You can apply the following primitives only to Boolean expressions:
  • ! logical not
  • & and
  • | or
The following primitives are composed of words instead of symbols:
  • TIME
    Represents the current time as the number of seconds since January 1, 1970, 00:00 Greenwich Mean Time.
  • DELTA
    Calculates the change of an attribute over the intervals of the sampling frequency. For example, a watch on an integer attribute named int1 at 30-second intervals might produce DELTA values as follows:
Interval
Values
0
100, 0
30
1000 900
60
1000 0
90
-1000 -2000
120
2000 3000
The DELTA primitive supports the following attribute types:
  • Integer
  • Enumeration
  • Real
  • Short
  • Time Ticks
  • Date
  • Gauge
  • Counter
In cases where the value is never expected to go down (such as with Time Ticks and Counter), use COUNTER_DELTA.
You can instance attributes in DELTA expressions as follows:
  • DELTA (If_In_Octets.2)
  • DELTA (If_Out_Octets.#)
  • DELTA (TIME) is also supported
DELTA (TIME) is the difference between now and the last evaluation of the watch; it is useful only for calculations involving internal attributes. To generate a rate calculation involving external attributes, use the device's time, for example, DELTA (XflDELTA (Sys_Up_Time), where Sys_Up_Time is the time counter on the device.
  • COUNTER_DELTA
    Calculates the change of an attribute whose value is assumed to be an increasing unsigned integer. The value may be reset to zero, but the result of this primitive is always a positive unsigned integer. Negative attribute values are treated as large unsigned values.
    The COUNTER_DELTA primitive supports the same attribute types as DELTA, and you can also instance attributes within COUNTER_DELTA expressions as described for DELTA. COUNTER_DELTA (TIME) is also supported.
  • ATTR
    Indicates that the hexadecimal number in parentheses following the primitive is an attribute identifier. This primitive lets an attribute to be uniquely identified when duplicate names exist as shown in the following examples:
    ATTR (<
    attr_id
    >)
    ATTR (<
    attr_id
    >).<
    instance id
    >
    ATTR (<
    attr_id
    >).#
    The <
    attr_id
    > value is “0x” or “0X” followed by between one and eight hexadecimal numerals.
  • TRUE
    Defines the Boolean constant True.
  • FALSE
    Defines the Boolean constant False.
  • MAX
    Identifies the larger of two expressions separated by a comma and enclosed by parentheses, for example, (attribute x+1, attribute y-5). The expressions may consist of any combination of operands, attributes, or primitives that results in a numeric value (non-text, string, octet, bool).
  • MIN
    Identifies the smaller of two expressions separated by a comma within parentheses, for example, (attribute x+1, attribute y-5). The expressions may consist of a combination of operands, attributes, or primitives that results in a numeric value (non-text, string, octet, bool).
You can use the following primitives (not shown on the pop-up selector menu) to indicate the instances of a list attribute that are monitored by a watch.
  • .
    Indicates that the following entry identifies a specific instance of a list attribute.
    For example, If_In_Octets.2 specifies the second instance of the attribute If_In_Octets. In the case of an IP address table, the identifier might be an entire address instead of a single digit.
    A watch fails if the specified instance of an attribute does not exist even for one of the models for which the watch is activated. In cases where the instance exists for some models but not for others, the watch succeeds for those models where it is present and fails for others.
  • .#
    Indicates that the current Instance Specifier value shown in the Watch Detail View determines which instances are monitored.
    For example, if the Instance Specifier value is ALL, the expression If_In_Octets.# applies the watch to all instances of the If_In_Octets attribute. However, if the Instance Specifier value is RANGE (1-3), only instances 1, 2, and 3 are monitored.
    In cases where a range of instances is specified, the watch fails even if one of the instances in the range is not present for one of the models. Conversely, the watch is successful for any model where all of the instances in the range are present.
Data Types
The following table shows the data type values that you can assign to the various attribute types.
Note:
Although
DX NetOps Spectrum
does not support watches of attributes with the data type OCTET STRING, you can watch such attributes using the TEXT STRING data type.
Expression Result Type
Acceptable Destination Attribute Types
BOOLEAN
Any Numeric Type
TEXT STRING
Text String
INTEGER
Integer, Enumeration, Real
ENUMERATION
Integer, Enumeration, Real
REAL
Integer, Enumeration, Real
DATE
Real, Date, Time Ticks, Counter, Gauge, Counter64
TIME TICKS
Real, Date, Time Ticks, Counter, Gauge, Counter64
COUNTER
Real, Date, Time Ticks, Counter, Gauge, Counter64
GAUGE
Real, Date, Time Ticks, Counter, Gauge, Counter64
OBJECT Id
OBJECT Id
IP ADDRESS
IP ADDR
COUNTER64
COUNTER64, Real
For example, given an integer attribute named Int1, the expression Int1 = 50.5 (requires a cast) is allowed, while Int1 = “a string” is not allowed.
The rules are most flexible for assigning values to Boolean and Text String attributes. Any expression can be evaluated to a 0 and 1 and can be written to a Boolean attribute. For example, given Bool1 as a Boolean attribute, the expression Bool1 = 500 * 50 + 450 assigns TRUE to Bool1. The expression Bool1 = (500 * 50 + 450) * 0 assigns FALSE to Bool1. Similarly, any expression can be evaluated to a text string. Given a Text String attribute named str1, the expression str1 = 500 + 50 assigns the string “550” to str1.
The Text String attribute type accepts text strings in quotation marks, and arithmetic expressions that are not contained in quotation marks, such as 500 + 50, which results in a string of “550.”
Constants
Like attribute values and operators, you can enter constants directly into the expression field. You can enter the following types of constants in expression formulas:
  • UnsignedInteger, represented by a sequence of one or more digits with a positive value.
  • Real, represented by a sequence of zero or more digits followed by a dot, followed by a sequence of one or more digits. For example, .7 or 1.7 or 23.24 (but not 7).
  • Signed Integer, represented by a sequence of one or more digits with either a positive or negative value.
  • Text String, represented by any sequence of characters that are enclosed by double quotation marks. For example, "a string" or "5.25" or " ".
Casting Operators
Casting forces one data type into another. When you perform casting, you risk losing some portion of the value being cast. Casting is unnecessary when the range of the source data type fits into the range of the destination data type.
For example, you can assign an integer to a real number without casting because -1.79769 e+308
<=
-2,147,483,648 and 2,147,483,647
<=
1.79769 e+308. However, you must use casting when assigning an integer to a counter because the ranges do not overlap.
Casting works correctly for the overlapping ranges of the involved data types. For example, casting the integer 5 to a counter behaves as expected. But negative numbers do not fit inside of the range of Counter. As a result, casting -5 to a Counter produces the unsigned (positive) result of 4,294,967,291 because of the way computers represent numbers. Conversely, casting a counter value larger than 2,147,483,647 into an integer produces a negative number.
You can use the following operators to cast the result of an expression in parentheses to a selected data type.
Operator
Result of Casting
UNSIGNED
Normally, 27 is treated as a signed integer; however, “UNSIGNED (27)” is interpreted as the unsigned integer 27. If a negative number appears in the expression following this operator, it is interpreted as unsigned. Example: UNSIGNED (-5) is interpreted as 5. The number, -5 is UNSIGNED with a value of: 4294967291.
INTEGER
Any real number in the expression following this operator is rounded up or down to the nearest integer. Examples: INTEGER (2.4) is interpreted as 2 and INTEGER (2.6) is interpreted as 3.
REAL
Example: REAL (3) is interpreted as 3.0.
Data Type of a Literal Number
A numeric literal in a watch expression is compared against a series of ranges to determine its data type. The Type column in the table below is the actual data type of the numeric literal, which is directly interchangeable with the other types that are listed in that column cell.
The following table shows how the data type of a literal number is determined:
Minimum
Maximum
Type
-2,147,483,648
2,147,483,647
Integer, Boolean*, Enumeration
0
4,294,967,295
Counter, Date**, Gauge, TimeTicks
0
18,446,744,073,709,551,615
Counter64
-1.79769 e+308
1.79769 e+308
Real
* You can also use the constants TRUE and FALSE for Boolean data types. Any non-zero value is equivalent to TRUE.
**The number of seconds from Jan 1, 1970 00:00:00 UTC(0).