User Guide › Service Level Management › Business Logic Scope › How to Use Business Logic › Business Logic Objects › Tools Object

Tools Object

A global object that contains some useful methods.

AddEventAnnotation(<Info>, <EventId>)

Saves an event annotation to specified event. This information can later be useful while viewing raw data (events). The saved annotation may explain some specific situation during execution of the Business Logic formula at specific moment.

The Information parameter specifies the annotation text should be written.

It also accepts an EventId parameter specifying annotated event.

AddRootCauseComment(<Info>, <Timestamp>, <ResourceId>)

Saves a root cause comment. This information can later be useful in generated reports. The saved root cause comment explains a specific situation during execution of the Business Logic formula at a specific moment.

The Information parameter specifies the comment should be written.

The method receives a timestamp to be saved together with the comment. It also accepts a ResourceId parameter specifying resource related to the method context. (This parameter is optional, and may be omitted.)

GetCustomAttributeForResource(resourceName, timestamp, customAttributeName)

Returns the value of the specified custom attribute, from the specified resource, at the specified time.

If the attribute doesn't exist at the time of the event, an error occurs.

Example:

Dim AttribVal
AttribVal = Tools. GetCustomAttributeForResource. "MyResource", #12/12/2006 12:34:56#, "MyAttribute"

GetExternalData (connectionString, query)

This method returns a recordset taken from the database specified by the connection string, based on the specified query.

Both strings must end with a semicolon (;).

The user may then use this recordset as follows:

• Recordset.MoveNext - move to the next record in the record set.
• Recordset.MovePrev - move to the previous record in the record set.
• Val = RecordSet("Field1") - get the value of Field1 from the current record in the recordset.
• Do Until ruleNames.EOF - stops the loop when the current record is the end of the file.
• Do Until ruleNames.BOF - stops the loop when the current record is the beginning of the file.
• RecordSet.Close - close the database connection.

Example:

Dim rs
Set rs = Tools.GetExternalData(
"dsn=oblicore;uid=oblicore;pwd=oblicore;", "select * from t_rules")
Do Until rs.EOF
  Out.Log "Name=" & rs("RULE_NAME"), "I"
  rs.MoveNext
Loop
rs.Close 

GetLocaleTime(<utcTime>)

The method converts a time given in UTC into the time zone of the current metric.

GetUtcTime(<localeTime>)

The method converts a time given in the time zone of the current metric into UTC.

HasCustomAttributeForResource(resourceName, timestamp, customAttributeName)

Return specifies whether or not the specified attribute exists in the specified resource at the specified time.

Example:

Dim AttribExistsNow
AttribExistsNow = Tools. HasCustomAttributeForResource "MyResource", #12/12/2006 12:34:56#, "MyAttribute"

NetTime(<Begin time>, <End time>)

Accepts two parameters that signify a period of time.

The method calculates and returns the amount of time (in seconds) from the beginning of the period to its end, which is within TimeSlots.

Should Begin time be later than End time, the result is a negative number.

SaveFields(<tableName>, <Key>, fieldName1, fieldValue1, fieldName2, fieldValue2,…)

Similar to SaveRecord, except that instead of enumerating all values, it provides pairs of field names and related field values. Field numbers can be substituted for field names. (The number of the first value field is 1).

Note: This method is executed only by the Tracking period agent.

SaveRecord <tableName>, <key>, <val1>, <val2>,…

Saves a record in a user table. User tables are used to output information during the service-level calculation. This information can later be used to generate reports. There may be many user tables.

The tableName parameter specifies the table to which the information should be written. Each record in the user table has a unique key, which specifies the record to which the information should be written. Each record also has many string-type value fields. The exact number of value fields in each user table and the field names are defined during implementation.

The SaveRecord method receives a user table name and a key. It also accepts all the value fields in the user table. (These value parameters are optional, and may be omitted.) If a record with the same key already exists, it is updated. (Only the value fields transferred as parameters are updated.) If a record with this key does not exist, it is created.

Note: This method is executed only by the Tracking period agent.

SendEvent(<eventName>, <resourceName>, <Timestamp>, <TimeUnit>, <args>)

This method creates a new metric event. The parameter definitions are as follows:

• EventTypeName – The name of the event type of this event.
• ResourceName – The name of the resource for which this event is sent. This parameter is optional. If it is not supplied, the event is sent on all resources. The name can also contain Resource Group name. If this is the case, the event is sent on this resource group. The system recognizes by itself whether the specified name if Resource name or Resource Group name. This can be replaced with a ResourceGroup name. No other values change when using the group name instead of a resource name.
• Timestamp – this is the timestamp of this event. This parameter is optional. If this parameter is not supplied, the timestamp is the timestamp of the last event received by the metric.
• TimeUnit – This is the time unit to be sent. The types of time unit the user can send are:
  • All
  • Tracking
  • Hour
  • Day
  • Week
  • Month
  • Quarter
  • Year

  The time unit parameter is a mandatory parameter, No events are sent if the parameter is not defined or defined incorrectly.

  The parameter is not case sensitive.

  An error is written to the log if the time unit is defined incorrectly in the business logic.

• Val_1, Val_2… – The value fields of the event. The number of the value fields depends on the event type. If the number of supplied parameters is more than the number of data fields in the event type, a run-time error is reported when this line is executed. If the number of supplied parameters is less than the number of data fields, a default value is placed in the last parameters. The default value depends on the type of the field. If the values passed are not consistent with the type of the values in the event, and if there is no appropriate casting, an error is generated.

Example:

Tools.SendEvent "OnEvent", "MyResource", #1/2/2006 13:46:00#, "All", 1, 2