Compare Events task-pane reference

Database

The PI AF database from which the function returns events. Specify in the format \\ServerName\DatabaseName. Click the field to see a list of databases that contain event templates on connected PI AF servers. You must specify the database before the function can find any matching events.

Tip: To limit returned events to those under a specific parent event, you can specify the event path of that parent event in the Database field. See Search for events of a specific parent event.

Search start

A PI time expression that specifies the time that the function starts searching the database for events. For example, specify *-12h to search for events from database records starting 12 hours ago.

Search end

A PI time expression that specifies the time that the function stops searching the database for events. For example, specify * to search for events up to the current time.

Limit to database level

Select this check box to only search the database root level for matching events. If you clear this check box, the function searches for matching events at any level of the hierarchy.

Event name

The name of matched events. You can specify partial names with wildcard characters.

Event template

An event template of the matched events. Note that if you select a base event template, the function includes events from derived templates.

When you select an event template, the Columns to display list updates to reflect attributes of the selected template. The update removes any attributes you previously inserted.

Element name

A PI AF element referenced by the matched events. You can specify partial names with wildcard characters. If using PI AF server version 2.8 or later, you can specify the path to a specific element.

Element template

An element template of an element referenced by matched events. Note that if you select a base element template, the function includes events that reference elements from derived templates.

PI AF server version 2.6 or later is required to filter on element templates.

Event category

The category of matched events.

Minimum duration

The minimum duration of matched events. Specify a value and time-unit abbreviation.

Maximum duration

The maximum duration of matched events. Specify a value and time-unit abbreviation.

Search mode

The method that the function uses to find matching events relative to the time period specified by the search start and search end:

• active in range

  Find events that are active any time during the specified time period.

• entirely in range

  Find events that start and finish during the specified time period.

• starting in range

  Find events that start during the specified time period and finish either during or after the specified time period.

• ending in range

  Find events that finish during the specified time period and start either before or during the specified time period.

• in progress

  Find events that start during the specified time period but have not yet finished. Only available with PI AF server version 2.6 or later.

Sort order

The method the function uses to sort returned events:

• name ascending

  Order events by the event name, from A to Z.

• name descending

  Order events by the event name, from Z to A.

• start time ascending

  Order events by start time, from earliest to latest.

• start time descending

  Order events by start time, from latest to earliest.

• end time ascending

  Order events by end time, from earliest to latest.

• end time descending

  Order events by end time, from latest to earliest.

Severity

The severity of matched events. Specify an operator and severity type. The function filters matched events based on the specified condition. Severity types correspond to a value, listed from highest to lowest. For example, if you enter < Warning, the function matches events less severe than Warning: either Information or None.

Attribute value filters

Up to four attribute conditions that the function uses to filter matched events. Events must meet all conditions to be returned.

Note: You must specify an event template before you can specify an attribute-value filter.

For each filter, specify:

• Attribute

  An event attribute for which the function filters matched events. Available attributes depend on the selected event template.

• Operator

  The relational operator that the function applies to the specified attribute value. Available operators depend on the attribute data type.

• Value

  The value that the function uses to search for matching attributes. For example, if you set the Operator field to =, then the function limits events to those with the specified attribute equal to this value.

Acknowledgment filters

Limit matched events to those that can be acknowledged:

• Select the Acknowledged check box to match events that have been acknowledged.

• Select the Unacknowledged check box to match events that have not been acknowledged.

• Select both check boxes to match any event that can be acknowledged, regardless of its current acknowledgment state.

Limit to annotated

Select this check box to match only annotated events. Clear this check box to match all events, with or without annotations.

Columns to display

The columns in the returned function array. The list contains the names of attributes. By default, the list includes the virtual attributes generated for all events and the event attributes from the selected event template.

The function includes the path of attributes; the function identifies unique attributes by name and position in the hierarchy. You can:

• Select the Select all check box to include all the listed attributes as columns in the returned function array.

• Select a check box to include the attribute, or clear a check box to exclude an attribute as a column in the returned function array.

• Click to open the Add Attributes window where you can select additional attributes to include as columns in the function array. See Add child-event attributes as columns in the Compare Events task pane.

• Right-click an attribute and then click Clone for parent event to insert the attribute for the parent event as a column in the function array. See Add parent-event attributes as columns in the Compare Events task pane.

• Type the name of an event attribute next to the blank check box at the bottom of the list.

• Right-click an attribute, click Insert attribute to insert a blank attribute above the selected attribute, and then type the name of an event attribute.

• Select an attribute and click to move the attribute up in the list.

• Select an attribute and click to move the attribute down in the list.

• Select an attribute and click to remove the attribute from the list.

• Right-click an attribute and then click Delete attribute to remove the attribute from the list.

  If the length of the selected column names exceeds 759 characters, the function cannot process columns individually. In this case, the task pane prompts you to specify all columns as a group. With columns specified as a group, the list says All event attributes and template attributes, and the returned function array includes all the default attributes and their children attributes, but no additional attributes that you specified.

Output cell

The worksheet cell where the function writes the resulting function array. If you select a cell before you open the function task pane, PI DataLink inserts the selected cell into the Output cell field.

Specify the top-left corner of the function array. PI DataLink expands the range downward and to the right of the output cell, as necessary to return specified data. PI DataLink might overwrite adjacent cells.

If you specify a multi-cell array in the Output cell field and the specified array is larger than the resulting function array, PI DataLink pastes the function formula in the unneeded cells of the specified array.