Common functions

The common functions supported in collection formulas.

Most of the functions that can be used in creating the collection formulas are described here. Along with these functions, you can use all H2 functions and most of the JavaScript functions.

delta
Purpose

It returns the difference between the current value of the binding x and its previous value (n)-(n-1). If the delta() of a MIB object with counter syntax is negative, it is not considered a problem.

Syntax
delta (x)
x The value whose delta value you want to find.
Example
  • 
positive(delta(CISCO_ENHANCED_MEMPOOL_MIB.cempMemPoolFreeHit))
    Which is equal to:
    
positive(currentValue(CISCO_ENHANCED_MEMPOOL_MIB.cempMemPoolFreeHit) – 
previousValue(CISCO_ENHANCED_MEMPOOL_MIB.cempMemPoolFreeHit))
previousDelta
Purpose

It returns the difference between the previous value of the binding x and its previous value (n-1)-(n-2). If previousDelta() of a MIB object with counter syntax is negative, it is not considered a problem.

Syntax
previousDelta (x)
x The value whose previousDelta value you want to find.
Example
  • 
Network.Outbound.Octets.Bytes.Previous.Delta = positive(previousDelta(IF_MIB.ifHCOutOctets)) when resource.type == 'interface' && number(resource.ifSpeed)>4294967295
Network.Outbound.Octets.Bytes.Previous.Delta = positive(previousDelta(RFC1213_MIB.ifOutOctets)) when resource.type == 'interface' && number(resource.ifSpeed)<4294967295
value
Purpose

Returns the value of a binding x. The value function is the same as the currentValue function.

Syntax
value (x)
x The binding whose value you want to find.
Examples
  • 
value(CISCO_ENVMON_MIB.ciscoEnvMonSupplyState)
values
Purpose
It returns an array of values of a binding x that is stored in the current state.
Syntax
values(x)
x The binding whose values from its stored current state that you want to find.
Example

positive(values(CISCO_ENHANCED_MEMPOOL_MIB.cempMemPoolFreeHit)[0])
duration
Purpose
Returns the difference of the current value collection time and the previous value collection time of a binding x.
Syntax
duration (x, ['seconds'])
x The binding whose value you want to find.
seconds Optional argument that indicates the unit of time. By default, it returns the value in milliseconds. If you want the function to return seconds, an argument 'second' must be added to the formula. It can be given as any of the following formats in single quotation marks:
  • 's'
  • 'sec'
  • 'secs'
  • 'second'
  • 'seconds'
Example
  • 
positive(delta(IF_MIB.ifHCOutUcastPkts)/
duration(IF_MIB.ifHCOutUcastPkts))
    Which is equal to:
    
positive(
currentTime(IF_MIB.ifHCOutUcastPkts) – 
previousTime(IF_MIB.ifHCOutUcastPkts))
time
Purpose
Returns the collection time of the current value of a binding x. The time function is the same as the currentTime function.
Syntax
time (x, ['seconds'])
x The binding whose value you want to find.
seconds Optional argument that indicates the unit of time. By default, it returns the value in milliseconds. If you want the function to return seconds, an argument 'second' must be added to the formula. It can be given as any of the following formats in single quotation marks:
  • 's'
  • 'sec'
  • 'secs'
  • 'second'
  • 'seconds'
Example

positive(time(CISCO_ENHANCED_MEMPOOL_MIB.cempMemPoolFreeHit))
times
Purpose
It returns an array of collection times of all the values of a binding x that is stored in the current state.
Syntax
times(x, ['seconds'])
x The binding whose value you want to find.
seconds Optional argument that indicates the unit of time. By default, it returns the value in milliseconds. If you want the function to return seconds, an argument 'second' must be added to the formula. It can be given as any of the following formats in single quotation marks:
  • 's'
  • 'sec'
  • 'secs'
  • 'second'
  • 'seconds'
Example

positive(times(CISCO_ENHANCED_MEMPOOL_MIB.cempMemPoolFreeHit)[0])
currentTime
Purpose
Returns the collection time of the current value of a binding x.
Syntax
currentTime (x, ['seconds'])
x The binding whose value you want to find.
seconds Optional argument that indicates the unit of time. By default, it returns the value in milliseconds. If you want the function to return seconds, an argument 'second' must be added to the formula. It can be given as any of the following formats in single quotation marks:
  • 's'
  • 'sec'
  • 'secs'
  • 'second'
  • 'seconds'
Example

positive(currentTime(CISCO_ENHANCED_MEMPOOL_MIB.cempMemPoolFreeHit))
previousTime
Purpose
Returns the collection time of the previous value of a binding.
Syntax
previousTime (x, ['seconds'])
x The binding whose value you want to find.
seconds Optional argument that indicates the unit of time. By default, it returns the value in milliseconds. If you want the function to return seconds, an argument 'second' must be added to the formula. It can be given as any of the following formats in single quotation marks:
  • 's'
  • 'sec'
  • 'secs'
  • 'second'
  • 'seconds'
Example

previousTime(CISCO_ENHANCED_MEMPOOL_MIB.cempMemPoolFreeHit)
rate
Purpose
It returns the rate of change between the current value and previous value of a binding.
Syntax
rate (x, ['seconds'])
x The binding whose value you want to find.
seconds Optional argument that indicates the unit of time. By default, it returns the value in milliseconds. If you want the function to return seconds, an argument 'second' must be added to the formula. It can be given as any of the following formats in single quotation marks:
  • 's'
  • 'sec'
  • 'secs'
  • 'second'
  • 'seconds'
Example
positive(rate(IF_MIB.ifHCOutUcastPkts, 'second'))
Which is equal to:
positive(delta(IF_MIB.ifHCOutUcastPkts)/duration(IF_MIB.ifHCOutUcastPkts, 'second'))
currentValue
Purpose
It returns the value of a binding x.
Syntax
currentValue (x)
x The value whose currentValue value you want to find.
Example

currentValue(CISCO_ENHANCED_MEMPOOL_MIB.cempMemPoolFreeHit)
previousValue
Purpose
Returns the previous value of a binding.
Syntax
previousValue (x)
x The value whose previousValue value you want to find.
Example

previousValue(CISCO_ENHANCED_MEMPOOL_MIB.cempMemPoolFreeHit)
positive
Purpose
It returns the value of the expression as follows,
  • If the value of the binding is positive, it returns the value.
  • If the value of the binding is negative, it returns null. You can provide a default value to be returned. For example positive(-1, 10), it returns 10.
  • When you write a custom formula that uses positive function, enclose the function within the expression so it returns a null value instead of zero. For example,
    positive(value(RFC1213_MIB.ifOutOctets)  * 8000)
    returns null as intended. Whereas 
    positive(value(RFC1213_MIB.ifOutOctets))  * 8000
    returns zero, which are incorrect.
Syntax
posistive (x, [default_value])
x The binding whose value is returned. If the binding is positive, then the value is returned. If it is negative, then null is returned. If the binding is a negative value, provide a default value. Then, the default value is returned.
[default_value] An optional argument. Value that must be returned for a negative result from the expression.
Example

positive(rate(IF_MIB.ifHCOutOctets, 'second')*8 / 
value(IF_MIB.ifHighSpeed)/10000)
oidVariableField
Purpose
The oidVariableField function is a utility function to parse and extract data from Object Identifiers (OIDs) in a specific format. Recursively processes an array of OID components to construct a list of variable-length fields.
Syntax
oidVariableField(oid: String, offset: Int, field: Int) list[String]
where,
  • oid is the Object Identifier that is defined in a MIB file.
  • offset is an integer. It is the starting position for extraction (0-based index).
  • field is an integer. It is the number of variable fields to extract (1-based index).
Returns a variable-length field as a string, or an empty string if not found.
Example
H2Functions.oidVariableField("5.104.101.108.108.111.5.119.111.114.108.100", 0, 1)
// res1: List[String] = List("5.104.101.108.108.111")

H2Functions.oidVariableField("5.104.101.108.108.111.5.119.111.114.108.100", 1, 2)
// res2: List[String] = List("5.119.111.114.108.100")
oidOctetString
Purpose
The oidOctetString function extracts an octet string from the specified OID based on the provided field index and version.
Syntax
oidOctetString(oid: String, offset: Int, field: Int)
where,
  • oid is the Object Identifier that is defined in a MIB file.
  • offset is an integer. It is the starting position for extraction (0-based index).
  • field is an integer. It is the number of variable fields to extract (1-based index).
Example
H2Functions.oidOctetString("5.104.101.108.108.111.5.119.111.114.108.100", 1, 1) res7: String = hello

The integers 104, 101, 108, 108, 111 are taken from the OID.

The oidOctetString function effectively converts parts of the OID into ASCII text by interpreting the numerical values as characters. In your example, the first segment yields hello because it converts the ASCII values of the extracted integers into their corresponding string representation.

Bindings
Purpose
It is to create aliases for the H2 functions. In H2, SQL aliases can be created to bind SQL function calls directly to functions in Java or Scala classes. This allows developers to use the functions of existing code from within SQL queries, making the database more powerful and flexible. Bindings increase code reusability, enhance functions, and ease of integration.
Syntax
h2.createStatement().execute(s"""CREATE ALIAS IF NOT EXISTS OID_VARIABLEFIELD FOR "persistent.itoa.discovery.h2.H2Functions.oidVariableField" """)
This command creates an alias that is named OID_VARIABLEFIELD that maps to the oidVariableField method in the H2Functions class located in the persistent.itoa.discovery.h2 package.
Example
h2.createStatement().execute(s"""CREATE ALIAS IF NOT EXISTS OID_OCTETSTRING FOR "persistent.itoa.discovery.h2.H2Functions.oidOctetString" """)
Similarly, this command creates an alias that is named OID_OCTETSTRING that maps to the oidOctetString method in the same class.