When entering a file in a field of type file, Tracker responds as follows:

The menu for file fields includes two items useful for obtaining information about ClearCase files, available if the field has a valid value and the file referred to is a VOB file. They are “Describe” and “History,” both accessible from the “Actions” sub-menu. They use ToolTalk™ to communicate with ClearCase. “Describe” executes the cleartool describe -long and “History” executes the cleartool lshistory command on the file referred to by the field. Both commands display their results in a tty window, created as needed, which is separate from the Tracker application. Subsequent command results appear there as well.

The default one-of list is a closed set from which a user must select one of the pre-defined values shown in the “Values” menu or dialog box. You can specify an open one-of set by entering an ellipsis (...) immediately (no comma) after the last value. Use open sets to specify the values used most often and to allow entry of non-predetermined values.

A one-of field may contain any single-line text value. In PDL, one-of field values may appear either as identifiers or as single-line quoted strings. A legal identifier must begin with an alpha character (upper or lower case). It may include letters, the underscore (_), and digits, in any order. You may not begin a legal identifier with $, since the $ prefix marks predefined fields or environment variables.

A single-line quoted string value may use the full character set. You can mix legal identifiers with quoted literal strings in a one-of field definition. For example;

x: one-of 
    a, b, c, '123', 'sarah', '4.0.1' ...

The short-text values let you pull in values from external programs by using the exec commands (see “Using the exec Functions” in Chapter 6, “Advanced Design Techniques”). It also lets you cross-assign values between fields. You can use the setValue method to set the one-of field value to short-text. For example, suppose that the Submitter field is a one-of field with the values being a list of engineers in a particular group. You can set the value to default to the current user of the application ($USER), which is a short-text field.

If a one-of field has 25 values or less (default), Tracker creates a cascading submenu off its “Values” menu item in the GUI. If there are more than 25 values, Tracker builds a selection dialog box that presents the user with a scrolled list from which to choose a value.

To change the default setting for the number of fields required for a scrolled list, you must set the maxAssistValues resource in the app_defaults file (see “Personal Tracker Resources” in Chapter 6, “Advanced Design Techniques.”

There are two limitations on using one-of fields:

Figure 2-2 shows the history of the actions taken on a request in a Tracker application. The actions SUBMIT_BUG, ASSIGN, and RESOLVE are recorded, along with the date and the submitter's name. Note that you cannot customize the format of the entryheader when you design your application; Tracker creates the headings automatically.

Figure 2-2. Entries in the Journal Field

You can write anything you like to the body of the journal entry using setValue(). The RTS example PDL file stores only the transition name in the journal entry body, using:

history.setValue($TRANSITION.text);

This is an example of a more complex journal entry:

tmpShortText.setValue(
execFilter('echo “Transition from state $STATE_old 
            to $STATE”'));
history.setValue(tmpShortText.value);

Figure 2-3 shows the field declaration for a journal field.

Tracker automatically assigns an entity identification number ($ENTITY_ID) to each new request as it is submitted to the database. Because the ID number is assigned prior to the execution of any actions, its value can be used in an action to set the value of other variables. For example, where report_number is of type int:

actions {
        report_number.setValue($ENTITY_ID.value);
        ...
        }

Rules are declared after the state declaration; they are preceded by the key word rules and are enclosed by braces ({}). In the transition example, the RESOLVE transition has these rules:

rules {
    resolution_description.isSet;
    resolved_in.isSet;
}

They require that there be entries in both the Resolution field and the Resolved in field.

An individual rule is terminated by a semicolon (;) and consists of one or more conditions. You define conditions using the boolean Tracker methods. An individual condition can be ored with other conditions, using the operator ||. This means that the entire rule (terminated by the semicolon) is satisfied if any one (or more) of the individual conditions is satisfied. Rules separated by semicolons (;) are effectively anded together, that is, all of the rules must be satisfied in order to permit the transition.

If all conditions are not met, the transition will not be permitted (its Apply button will not be enabled) and incorrect fields will be highlighted accordingly. It is useful to think of a rule as having top-level and secondary-level conditions. A top-level condition is the main part of a rule; the secondary level refers to conditions inside nested expressions. When a rule is not met, only the fields in top-level rules are highlighted. The fields at the secondary level are not highlighted. For example, consider the rule:

owner.is(submitter.value);

The rule means that the owner value must be the same as the submitter. If this condition is not met, then the owner field (which is a top-level rule) will be highlighted. The submitter field is in a nested expression and will not be highlighted. It is a good idea to explain such relationships between fields in an on-line help card, either in the transition help card or the associated rule help card if it exists.

Actions immediately follow rules. They are preceded by the key word actions. Actions can change the values of fields. Like rules, they are defined in terms of methods. Where rules mainly use boolean methods, actions use boolean methods only to set values subject to conditions.

Three methods provide access to shell commands (and environment variables) external to the PDL: execCommand, execFilter, and execSelect. They take a single string parameter and are not associated with fields. These methods are described in Table 2-3. For more information, see “Using the exec Functions” in Chapter 6, “Advanced Design Techniques.”

Here are some useful Tracker environment variables, accessible through the external methods:

The methods for testing field data are called against a field, for example:

description.isSet

They do not take parameters and do not accept the empty parentheses that C uses: for example, description.isset() is incorrect. They are predicates; they return a boolean result, so they can be used in rules. The methods are listed in Table 2-4.

In addition, you can test any field of type boolean with the value method (described in Table 2-11), as in this example:

boolfield.value;

If boolfield is true, then this rule will be satisfied; if boolfield is false, or if it is unset, this rule will be unsatisfied (boolfield will be highlighted in the GUI).

The methods in Table 2-5 return other types of data in addition to booleans. They are used only inside expressions within parameter lists, typically in conjunction with a boolean method. Since there are no side effects from these methods, they are not appropriate for use as top-level methods in actions, although this is legal.

The methods for making field comparisons are called against a field and take an expression as a parameter.

For example,

priority.isGreater(3)

tests whether the priority field is greater than the value 3. These methods are shown in Table 2-6

.

The methods for field value computations let you perform computations using field values. They take an expression, which can contain nested methods as well. For example, the action

due_date.is(due_date.setDefault('now + 30:00:00:00'));

computes the value of the expression ('now + 30:00:00:00'), which is equal to the current date plus 30 days, sets that value as a default in the date field, and uses that value if another has not been entered.

These methods have two categories: methods that actually change the field values and methods that perform calculations with field values.

Table 2-7 shows the methods for changing field values.

Table 2-8

Currently, there is only one such method:
<fieldname>.setReadOnly

This method takes a boolean argument; it defaults to ReadOnly (true). It can be invoked in any type of field and its action is to render the field read-only in the GUI. This means the user cannot modify the data in the field, although the PDL code itself may still do so.

The action of this method lasts only for the current transition. Once the transition has been applied or cancelled, the field reverts to its original state.

The main view name declared in the PDL file:

The auxiliary view names appear as items in the Views menu in the main view and also in their respective title bars.

Each view can have a title declaration, within the parentheses following the view name. If the title declaration is empty, no title will be drawn above the view. In declaring a title, you can use strings inside single quotes and field names defined in the fields declaration section. The strings and field values are assembled into a one-line title at the top of the entire view.

Fields that display in a title are not editable inside the title area. You can use white space to separate items, in which case they are positioned next to each other, or you can use one or more commas to separate them. To stretch a title so that it reaches across the window, use commas; these add padding so that all the comma-separated sections are of equal width.

The body of the view is enclosed in braces and declares the features of the window, that is, labels, fields, controls, and associated on-line help. A window is defined feature by feature from top to bottom. Tracker provides a number of key words to make the process easier.

The key word display lets you define an area within the window. You can specify a title, defined in the same way as the title of the entire view. You can also select resources to control both the appearance of the display as a whole and items within the display area. See “Feature Names” in the next section.

Within the view body, you can also declare the control bar, which contains the Modes menu, button controls, and the query results area for displaying request summaries matching the query criteria.

The key word row helps you organize fields and their labels, entered as literal strings called tuples, into a row. Similar to title declarations, the items in a row are specified with or without comma separators. Padding is added at the commas, so that the groups separated by commas are evenly spaced. If the row is inside a display, the first literal string in each group is treated as a label. The width of a given column is expanded according to the longest label in the display. Rows can be given names, which are used in resource selection, but do not display any title text. Tuples are discussed in “Defining a Request Form Area” later in this chapter.

Tracker supplies a number of key words to let you declare the standard features of Tracker applications. These are the reserved words and their meanings in PDL files.

control-bar () 
  {transitions ...} 

qresults () 
  {index ...}

qresults() {
    index   type:3:'Type'
    $ENTITY_ID:5:'ID#'
    $STATE:20:'State'
    owner:20:'Owner'
    summary::'Summary';
};

A feature name identifies an element in the user interface and is attached to the X11 widget that implements the display, which in turn retrieves resources. Feature names precede the PDL key words (described in the previous section) and are followed by colons. A number of useful appearance variations are provided in the standard Tracker application defaults file.

The feature names applied to views, displays, and rows are used to select resources that fine tune the appearance and behavior of the interface. Due to the hierarchical way in which X11 manages resources, a name attached to a view or display can also be used to select resources for contained display items that are nested several layers deep.

For example, if a view named viewOne contains an unnamed display, which in turn contains an unnamed row, which finally contains a certain field, you can specify resources for that field in the resource file or the application defaults file by the name viewOne, and they will be correctly applied to the field.

Resources specified by the application name itself generally take precedence over those specified by the application class name. Resources specified in individual users' resource files generally take precedence over those specified in the application defaults file.

Complete details on resource selection are located in the Xlib Programming Manual for Version 11under “Managing User Preferences.”

A number of resources are defined in the Tracker application default file (and included in the application defaults file generated for Tracker applications). To use them, you must give the indicated name to the feature you want controlled (or to a display or row that contains it). Predefined feature names are illustrated in Table 2-9.

For more information on feature names, refer to “Using Dates” in Chapter 6, “Advanced Design Techniques.”

Tracker provides two icons in the query results area. A small rectangle next to a request in the list indicates that the request has been displayed in the form area. A check mark indicates that the request has been edited (see Bug #1 in Figure 2-8).

Figure 2-8. Portion of PDL Defining Query Results Area

Two entries in the app-defaults file affect the query results area. The entry

*query_results.visibleItemCount:5 

sets the number of lines to display at startup (request summaries) in the query results to five. If your end users prefer a different initial size, you can change this entry.

When you perform a query on the request database, Tracker retrieves the first 50 entities that it finds so that it doesn't need to perform another retrieval until the user scrolls past the fiftieth line. The entry

*QueryFetchCount: 50

controls the number of summaries retrieved. Retrieving more entities slows the initial query results area display but the trade-off is that you have more entities to scroll through. If performance on queries becomes a problem, you can adjust the fetch quantity.

You can arrange the request form area in any way you like by using tuples in the row statement. If a row consists of a single tuple, that tuple will be expanded to fill the row. For example, this format

row{'Description' 'hello there'} 

fills the row. If you divide the row up into several tuples, the row width is evenly divided among the tuples. For example, this format

row{'Description' 'hello there', , }

would cause the first tuple, consisting of 'Description' and 'hello there', to use one third of the full row width. The other two tuples are empty, so the rest of the row will be empty.

You can use empty strings within a tuple to get a similar effect. For example,

row{'Found in:' ' ', ' '};

creates two tuples of equal width in the row. The first tuple contains the text “Found in:” plus a specified amount of space. The second tuple contains only white space. If you use this format:

row{'Found in:'};

the text fills up the row completely.

To calculate the amount of space required for each item in a tuple, consider these guidelines.

The tuple is laid out from left to right, with a single space between items. The last item is then “attached” to the rightmost edge of the tuple and the tuple is stretched to fill its allotted space in the row.

When the width of the tuple is adjusted, you may have a larger space opening up between the rightmost item and its neighboring item to the left. The amount of space created will depend on how wide the tuple is, which in turn depends on the row width and number of tuples in the row. This example shows how to use tuples to left-justify a label:

display() {
    row{'Resolution:' ' '};
    fourRowLongText:
    row{resolution_description};
}

The first row contains one tuple with two items, the label 'Resolution:' and the space ' '. The label will occupy a 10-character space starting from the left, and is separated from the space item by a 1-character space. The space item then expands to fill the rest of the row.

In addition to your custom settings, Tracker adjusts the width of tuples so that they form justified columns in a display. A tuple in a given column in a row is always allotted the width of the widest item in that column.

For example, in this three-column display with three rows, the width of the second column will be equivalent to the width of the 'Recommendation:' tuple in the third row:

threeColumn: display() {
    row{'Report #:' $ENTITY_ID,
        'Status:' $STATE,
        'Priority:' priority};
    row{'Type:' type,
        'Submitter:' submitter,
        'Owner:' owner};
    row{'Date:' submit_date,
        'Closed:' close_date,
        'Recommendation:' recommendation};
}

Figure 2-10 shows how display appears on the screen.

Figure 2-10. An example of a three-column display

It is important to remember that on-line help has a hierarchical structure. Figure 2-14 shows a typical Tracker hierarchy; it represents the hierarchy from a user's point of view. The stacked help cards in the diagram indicate that there can be multiple help cards and subtrees at that location. The order in which the help cards appear (top to bottom and left to right) correspond to the sequence in which they are declared in the PDL files, except for the help cards that are shown in the illustration in white. These cards are actually declared elsewhere in the hierarchy, where they appear in gray; they are in the hierarchy redundantly as a convenience for users.

In a Tracker application, you must declare the top-level system help card (at the beginning of the PDL file) and the top-level view help card (at the beginning of the view declaration section). If these are missing, you will get warning messages when tvgen (and rtsgen) is run; more importantly, your end users may get error messages if they try to use on-line help.

At the top level, it is important to make the resulting hierarchy easy for users to find what they are looking for. The top-level system help card file forms the root of the on-line help hierarchy. Below it are the top-level cards for the fields and transitions and the application help cards, which group the views.

Figure 2-14. Typical Tracker On-line Help Hierarchy

Note that the help cards for individual fields and transitions (rules and actions included) can appear redundantly in the hierarchy, under the top-level field and transition cards and in the view subtrees that contain them. These help cards are actually declared in the fields section and transitions section of the PDL file respectively. These cards are shown in Figure 2-14 in white.

It is a good idea to include a help card for the control-bar in each application. The control-bar help card groups all relevant transition help cards as subtopics under the control-bar help card. If the user selects any item in the control-bar using context-sensitive help, help on the set of transitions provided by the application will be readily available in the subtopics window of the help viewer.

At the bottom level, you should provide detailed information for the individual transition cards on how the particular transition relates to the overall tracking process. You can describe the rules and actions in the card in the transition help card or separately in the associated rules and actions help cards.

Use help declarations for individual fields to clarify the intended use of the field and to give suggestions for using specific values for the field. The field help declarations appear at the bottom of the view help hierarchy. They are grouped under the containing row if you declare it; otherwise, they appear under the containing display area. If you declare neither the containing row nor display area, then the field help declarations are grouped directly under the view help card.

After adding or changing help declarations in the PDL, you can review the changes by running the application (after running tvgen and tvinstall) and by selecting items in the “Help” menu. Select “Browser” in the help viewer window to examine your help hierarchy.

---

Caution: tvgen does not remove help cards from the <databasedir>/tools/help directory before generating new on-line help. If you rename (or remove) an application in your system, you should remove the corresponding subtree in <databasedir>/tools/help.

---