Customizing Data Filters

This section describes the primary interface provided by the Trace Analyzer for creating, deleting, and editing data filters.

Filter Configuration Interface

Data filters are managed through the Filters page in the Configuration Dialog Window, accessed via the  Configure - Filters action in the Global Toolbar or the Main Menu.  This interface is depicted in Figure 1.


Figure 1.  Filter Configuration user interface

This interface enables the creation, renaming, deletion, editing, and verification of data filters.  A single filter may be loaded into this interface at a time.  The currently loaded filter is determined by the selection in the Filter Name combo-box in the upper left portion of the interface depicted in Figure 1.

Every filter must have a valid filter expression associated with it before it can be applied to trace data.  Filter expressions follow a well defined syntax.  In order to create or edit filter expressions, it is important first to understand this syntax.  See the Filter Syntax section for more information on this topic.

Creating a New Filter

A new filter is created via the Create New Filter action in the Filter Configuration Toolbar.  This action prompts the user for a filter name and creates a new filter containing no filter expression initially.  The filter name provided must be unique.  The new filter is displayed and is ready for editing.

Renaming a Filter

An existing filter can be renamed via the Rename Current Filter action in the Filter Configuration Toolbar.  The filter to be renamed is the filter currently loaded in this interface.  The new filter name provided by the user must be unique among all filters in the system.  The new name is applied immediately.

Deleting a Filter

An existing filter can be deleted via the Delete Current Filter action in the Filter Configuration Toolbar.  The filter to be deleted is the filter currently loaded in this interface.  The user is prompted for a confirmation.  If the action is confirmed, the current filter is permanently deleted.  This function should be used with caution.

Editing a Filter Expression

An existing or new filter can be modified to behave differently by editing its underlying filter expression.  The current expression associated with a filter is presented in the Expression text field near the top of the page.  All changes to the expression are reflected in this field, whether made directly or interactively.

This interface enables an expression to be edited interactively, by providing various, visual, helper components, such as the operator icons in the toolbar, the protocol browser components, the symbolic name mappings table, and the logical function helper interface.  Any of the items presented in these views can be inserted into the filter expression interactively.

Alternatively, advanced users who are familiar with the expression syntax used by filters can edit an expression directly, by simply typing in the Expression text field.

Verifying a Filter Expression

A filter expression must be verified before the filter can be used, to ensure that the expression is valid.  This is done either explicitly via the Verify Current Filter action in the Filter Configuration Toolbar, or implicitly, when another notebook page in the Configuration Dialog Window is selected or when the window itself is closed.

If a filter expression cannot be verified, an error message will appear in the Status Message Area of either the Configuration Dialog Window or of the Global Toolbar, depending on which window is displayed at the time the verification takes place.

When a filters has been verified successfully, a green checkmark () appears to the left of the filter's name in the list of filters in the Filter Name combo box.  If a filter has not yet been verified, or has failed verification, a red 'x' () appears instead.  Only filters which have been verified successfully will appear in the Select Filter combo box in the Global Toolbar.

Filter Configuration Toolbar

A toolbar is located at the top of the Filters page, just below the notebook tabs.  This toolbar provides controls to perform the actions described in Table 1.
Control
 Action Description
Create New Filter See Creating a New Filter.
Rename Current Filter See Renaming a Filter.
Delete Current Filter See Deleting a Filter.
Verify Current Filter Causes an explicit attempt to verify the filter expression currently displayed.  See also Editing a Filter Expression.
Clear Filter Expression Clears the Expression text field of all text.
Equals Inserts the specified operator symbol into the Expression text field at the cursor's current location.
Not Equal Inserts the specified operator symbol into the Expression text field at the cursor's current location.
Greater Than Inserts the specified operator symbol into the Expression text field at the cursor's current location.
Greater Than or Equal To Inserts the specified operator symbol into the Expression text field at the cursor's current location.
Less Than Inserts the specified operator symbol into the Expression text field at the cursor's current location.
Less Than or Equal To Inserts the specified operator symbol into the Expression text field at the cursor's current location.
Logical AND Inserts the specified operator symbol into the Expression text field at the cursor's current location.
Logical OR Inserts the specified operator symbol into the Expression text field at the cursor's current location.
Negate Surrounds the selected text in the Expression text field with parentheses and precedes the opening parenthesis with the negation keyword not.
Addition Inserts the specified operator symbol into the Expression text field at the cursor's current location.
Subtraction Inserts the specified operator symbol into the Expression text field at the cursor's current location.
Multiplication Inserts the specified operator symbol into the Expression text field at the cursor's current location.
Division Inserts the specified operator symbol into the Expression text field at the cursor's current location.
Remainder Inserts the specified operator symbol into the Expression text field at the cursor's current location.
Bitwise AND Inserts the specified operator symbol into the Expression text field at the cursor's current location.
Bitwise OR Inserts the specified operator symbol into the Expression text field at the cursor's current location.
Bitwise XOR Inserts the specified operator symbol into the Expression text field at the cursor's current location.
Parentheses Surrounds the selected text in the Expression text field with parentheses.
Table 1.  Filter Configuration Toolbar actions

Protocol Browser Components

The Protocol Browser components in the Available Protocols area (see Figure 1) are used by the Filter Configuration interface to enable the user to browse through all protocol definitions and interactively insert an individual protocol field ID into the current filter expression.  See the Browsing Protocol Definitions section for a detailed description of the three related Protocol Browser components.

Interactively Updating an Expression

Double-clicking any protocol field in the Protocol Layout Tree view inserts that protocol field's ID into the Expression text field at the current cursor position.

Symbolic Name Mapping Table

As different protocol fields are selected in the Protocol Layout Tree view of the protocol browser components, a table to the right of these components is updated with the list of symbolic name aliases, if any, which can be applied to the selected protocol field in a filter expression.  This interface component is depicted in Figure 2.


Figure 2.  Symbolic Name Mapping table component

Not all protocol fields have symbolic name aliases associated with them, so this table may be empty, depending upon which protocol field is selected in the currently displayed protocol layout view.

If a particular protocol field does have symbolic name aliases associated with it, regardless of whether they are user-defined (see Symbolic Name Aliases) or pre-defined by the author of the protocol definition, they will appear in this table.

For example, Figure 2 depicts a scrollable list of aliases for the various function callout codes defined by the Kernel Trace for OS/2 Function Header protocol (protocol ID:  KTO_FN_HDR).  This list was generated when the KTO_FN_HDR:CODE protocol field was selected in the protocol layout view.

Interactively Updating an Expression

Any item in this table which is double-clicked will be inserted into the Expression text field at the current cursor position.  Note that the column in which the double-click occurs is relevant:  if the Descriptive Text column is the target, the descriptive text for the clicked row will be inserted;  if the Data Value column is the target, the numeric data value will be inserted instead.

For instance, to use the example of Figure 2 again, one might be defining a filter expression to detect whether a trace record contains a KTO_FN_HDR:CODE protocol field whose value represents Change File Pointer (the symbolic name alias for code 07).  If the following partial expression were already included in the Expression text field

KTO_FN_HDR:CODE =
double clicking on the Change File Pointer cell in the table would complete the expression as follows (assuming the text field cursor were already positioned at the end of the partial expression text):
KTO_FN_HDR:CODE = 'Change File Pointer'
Note that surrounding single quotes are added automatically if there is any whitespace within the text.

Alternatively, the partial expression might be completed by double clicking on the 07 data value in the same table row to create:

KTO_FN_HDR:CODE = 07
Either choice represents a valid filter expression.

Logical Function Helper Interface

An interface is provided in the lower right quadrant of the Filter Configuration interface to provide an overview of the various, logical user functions available for use within filter expressions.  This interface is depicted in Figure 3.


Figure 3.  Logical Function Helper interface

On the left side of this interface is an alphabetical list of all the logical user functions available.  Selecting any function name in the list causes information about the selected function to appear in the area to the right of the list.  This information includes:


Interactively Updating an Expression

Double-clicking any function name in the list inserts the selected function name, followed by open and close parentheses (e.g., @protocol()) into the Expression text field at the current cursor position.

Copyright © 2000-2001 Golden Code Development Corporation.  ALL RIGHTS RESERVED.