TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Customizing Rational Summit/TM

This chapter describes the tools and procedures for customizing Rational Summit/TM task domains, task kinds, task editor dialogs, and commands.

The following topics will be covered in this chapter:


Changing Rational Summit/TM Data

The Apex and Summit customization procedures described in this chapter modify the Rational Summit/TM database accessed by Apex and Summit. In order to optimize performance, much of the Summit/TM database is cached in memory. To ensure that the cached information is properly updated, the command Tasks > Reset Task Info... should be invoked after performing customizations and before running any command which may require access to changed Summit/TM information. As a side effect of this command, all open dialogs are cancelled. This ensures that no Summit/TM dialogs are using outdated information.

For example, after modifying an existing task kind all Summit/TM dialogs should be closed and the cache refreshed through the Reset Task Info command. The current implementation of this command causes the Apex or Summit Dialog Server to be killed and restarted. As a result, all dialogs will be closed and the initial Apex or Summit dialog will be redisplayed by this command.

Note that the Reset Task Info command is not required when tasks themselves are modified or when a task editor dialog is modified (unless the Java interface) is used. However, the command should be used when a task domain's policy or switches are changed, when a task kind is changed, and when Summit/TM role information in the user's ~/.Rational directory is changed.


Viewing and Modifying Tasks as Text Files

Tasks (and other objects such as task lists) are examined and subsequently edited using the visit command (or the Navigate > Visit menu item). Under normal circumstances, the visit command invokes an editor that is designed specifically for the given type of object. For example, visiting a task initiates a task editor dialog. Under special circumstances, it may be desirable to examine or modify the file in which a task's field values are stored as a plain, ordinary text file. This can be accomplished using the visit command by specifying the -as_text option as follows:

Alternatively, the same result can be achieved with the Control-Meta-Navigate > Visit menu item. That is, hold down the Control and Meta keys while you click on the Navigate > Visit menu item.


Creating New Task Domains

To create a new task domain view just run the create_task_domain command described below (or use the File > New > New Task Domain menu item). To make it more convenient to access this new domain, either add its path to the APEX_TASK_DOMAIN_PATH environment variable, or add it to the list of task domains in the configuration file rational_dir/config/task_domain_path (where rational_dir is the parent directory of $APEX_HOME). The configuration file is used by apexinit or summitinit to set the environment variable if it is not already set. The new domain will be the default domain if it is the first domain named.

After creating the task domain, you may wish to set up the task domain's role policy by editing the Policy/Task_Roles file within the task domain subsystem.

create_task_domain

Syntax

Description

Creates a new task domain view. If the subsystem specified in view does not exist, then it is also created, in which case the task domain subsystem properties can also be set using various options. This command must be run under an Apex or Summit shell. If the subsystem is also created, then the default values for its policy switches are taken from that of the prototype task domain located at:

Parameters

Example


Creating New Task Kinds

To create a new task kind it is best to start with a copy of an existing task kind. Use the copy_task_kind command described below to create a kind. Then you will want to customize the following information that is normally present in every task kind:

Information

Files Within Task Kind

Task Kind Policy Switches
Taskmgmt_Kind.sw
Task Fields and Types
Fields
State Machines
*.sm
Actions
*.actions
Task Templates
*.task
Task Editors
*.tegen, *.dlg

The above is a reasonable order in which to customize the information, although you will not be able to set the Template_Path and Default_Gui fields of the Taskmgmt_Kind.sw policy switch file until you have defined the task kind templates and task editors.

It is not necessary to have all of this information in every task kind, especially for testing purposes. For example, you don't need a task editor if you only use the command line interface to test the new kind. Also, every task kind does not have to have a state machine with an associated actions file.

All of these files are text files which can be manually edited. However, if you have Rose/C++ 3.0, you can use it to create the Fields file, state machine files (*.sm), and skeleton action files (*.actions).

A convenient way to create a task template is to just create a task of the task kind, set its fields to the appropriate values, and then copy the resulting task file into the task kind directory as a template.

To create customized task editors, you will need to use the tegen and/or apex_guigen tools.

copy_task_kind

Syntax

Description

Creates a new task kind directory by making a copy of an existing task kind directory. This command should be used instead of the usual copy command because it automatically updates the task editor files and templates files to use the new kind name. (Template relationships are not modified.)

The source and destination cannot refer to the same subdirectory within different views of the same subsystem. The accept_changes command should be used for that type of operation.

Parameters

Examples

Using Rose/C++ to Generate Task Kind Policy Information

This section describes how to use Rational Rose/C++ 3.0 to build, maintain and analyze task kind field descriptions and state machines. It assumes a medium degree of familiarity with Rose/C++.

Rose can be used to define the task fields of a task kind using a class diagram. A task kind state machine can be designed using a Rose state diagram which graphically describes the state transitions a task can go through. Once designed, both the task kind fields definition file and the state machine file (along with a skeleton actions file) can be generated automatically using a special Rose Code Mapper program.

Setting up Rose/C++

Before using Rose/C++ to generate task kind policy information, certain files must be installed in the same directory in which Rose/C++ is installed. Check to see if this has already been done by the normal installation process before doing it manually.

In the following discussion, rose_dir is used to refer to the directory in which Rose/C++ is installed and task_rose_dir is used to refer to the directory containing Rational Summit/TM specific files to use with Rose. If you are using Rose/C++ for Windows, then rose_dir will be located on a PC machine and you will have to transfer files between the machine on which Rational Summit/TM is installed and the PC, by whatever means you have available. The task_rose_dir is located in the appropriate shared Rational Summit/TM directory:

1 . Install the special Code Mapper program for Rational Summit/TM into Rose/C++:

2 . Make a backup copy of the Rose/C++ menu file. In the Windows version of Rose/C++, this file is named rose_dir\rose_cpp.mnu. In the UNIX version, it is rose_dir/menus/rose_cpp.mnu. Within the new copy of this file, insert the following menu item at the bottom of the list:

3 . Copy the sample Rose model file for Rational Summit/TM, task_rose_dir/change.mdl to some convenient place so that it can be modified.

Rational Summit Task Kind Rose Model

This information describes how a Rose model is used to represent a Summit task kind with its associated task fields and state machines. In general, it does this by defining the mappings from the necessary Summit concepts to the Rose model constructs which can best represent those concepts. Some representations are more accurate (or more complete or more natural) than others due to either minor limitations in the Rose model or the fact that Rose is a general purpose modeling tool that Summit is trying to use for a specific application.

Much of the terminology introduced below reflects the nature of this mapping from Summit concepts to Rose constructs. At times, the terminology may seem at bit lengthy and redundant. For example, consider the term task field type base class. After all, a type is a class, so why include both in the term? The reason is to emphasize that the Summit concept, task field type, is being mapped onto the Rose construct, base class.

Summit only needs to use a small subset of the modeling constructs supported by Rose. In fact, only the following Rose constructs are required. Note that this discussion just uses Rose's Booch Notation. The other Rose notations are equally valid.

As described here, a Rose model can be used to represent most, but not all, of the information that goes into making a Summit task kind. Such a model can generate a task kind's Fields file, state machine file (state_field_name.sm) and a skeleton actions file (state_field_name.actions on UNIX, state_field_name.act on Windows). It can not generate a task kind's switch file (Taskmgmt_Kind.sw), any task editor dialog files, any task template files, nor customized state machine action scripts. These must be created by other means in order to have a complete and useful task kind.

And now, on to the detailed mappings! This discussion attempts to present all of the information necessary to build a task kind Rose model from the ground up. However, it is certainly wiser (and a lot easier) to start with a copy of one of the existing sample models, provided with the product, when creating a new task kind or modifying an existing one.

Naming Conventions

Unless explicitly stated otherwise, all names used to identify parts of the Rose model that are used by the generated task kind must be identifiers (starts with a letter, followed by zero or more letters, digits or underscore characters).

Task Class Category

First of all, in order to define various Rose classes that have a special meaning and purpose for Summit (but not really to Rose), every Rose model that is used to build task kinds must have a class category called Task. Its use is detailed below.

Note that, in general, only predefined classes required by Summit should be defined in this class category. User defined classes should be defined in other categories. These other categories will have to reference the classes defined in the Task category and can do so using Rose's Query > Add Classes command.

Task Kind Classes

A Summit task kind is represented in Rose as a class with some special attributes. It is referred to as a task kind class. There are two types of task kind classes, abstract and concrete. A given Summit Rose model can have multiple task kind classes of each type.

Abstract Task Kind Classes

An abstract task kind class is just a normal Rose class with its abstract adornment enabled. As explained in greater detail later, an abstract task kind class is used as a convenient building block for constructing concrete task kind classes. An abstract task kind class can inherit the structure of (via a Rose inherits relationship) other abstract task kind classes.

There is a very special abstract task kind class, called TaskKind, that must be defined in the Task class category. As described below, it is the ancestor of all concrete task kind classes. As such, it should never inherit from any other task kind class (that is, it should never be a subclass or derived class).

Concrete Task Kind Classes

A concrete task kind class is just a normal Rose class. It represents an actual task kind that can be generated and used by Summit. The name of the concrete task kind class is the simple name of the actual task kind to be generated.

A concrete task kind class can inherit the structure of (via a Rose inherits relationship) one or more distinct abstract task kind classes. Furthermore, a concrete task kind class must inherit (either directly or indirectly) from the special TaskKind abstract task kind class described in the previous section.

For example, the concrete task kind class work can inherit from the abstract task kind class standard which in turn can inherit from the special TaskKind class. This inheritance relationship between a concrete task kind class and the TaskKind class is what actually identifies the former as a concrete task kind class. Otherwise, it is just another class.

Task Field Type Base Classes

As defined so far, task kind classes, whether abstract or concrete, are not very useful because they have no fundamental (tangible) data members. For that, some data classes are needed. A task field type base class is a normal Rose class which represents one of the supported Summit task field types. The name of the class is the same as the name of the type. Furthermore, all such field type classes must be defined in the special Task class category. Thus, the following task field type base classes are supported:

Note: These task field type base classes need only be defined once, but can be used multiple times by task kind classes.

Task Field Definitions

For a task kind to have a task field of a particular type, its associated concrete task kind class must contain a copy of the task field type base class associated with that type. For the simple field types, this is accomplished in the model by just defining a Rose uses relationship between the concrete task kind class (or one of its inherited abstract task kind classes) and the task field type base class (which is the supplier class). The name of the uses relationship is the name of the task field and must be defined.

For the more complex field types, state, enum and task_path, a more complex model must be built, as described later, but a relationship comparable to the uses relationship is still defined.

For all field types, the cardinality of the supplier end (field type base class for simple field types) of the uses relationship determines whether the task field can contain a single value or a list of values. If the cardinality is Unspecified, then the field is a single element. If the cardinality is Zero or More (0..n), then the field is a list. Other cardinality settings should be avoided.

All such uses relationships for a given concrete task kind class (whether direct or inherited) must have unique names.

State Field Definitions

A task field of type state is considered complex because it defines a state machine as well as a field. In Rose, a given class can implement at most one state diagram which is used to represent a task state machine. So far, in this discussion, there are only two candidate classes where such a state diagram can be defined: a task kind class or the state task field type base class. Putting a state diagram in a task kind class is a poor solution because it greatly distorts the general model for task field definitions. Putting a state diagram in the state task field type base class is equally undesirable because, then, all task kinds generated from a given Rose model would have to have the same state machine. The chosen solution is to implement a state diagram in an intermediate class called a state task field type derived class (or state type derived class for short).

A state type derived class must inherit from the state field type base class. The state type derived class must, in turn, be used by a task kind class in the same manner as is a simple field type base class. The name of the uses relationship between the task kind class and the state type derived class defines the name of the generated task field. It also defines the names of the generated state machine and actions files. For example, if the uses relationship is called Work, then the task field will be called Work and the generated files will be called Work.sm and Work.actions (Work.act on Windows).

State Machines

As mentioned above, a task state machine is represented in the Rose model by a state diagram which must be associated with a state type derived class. A state diagram must have exactly one start state and zero or more normal or end states.

Each state in a state diagram must have a name. This name also identifies the state in the resultant task state machine. The state names of a task state machine are ordered. This ordering is useful when sorting tasks by their current state field values. The state name order is represented in a state diagram as follows.

The state names are ordered by putting the start state first and then partitioning the remaining states based on whether the state has any documentation (see the state's specification for this). States with documentation come first, ordered by the value of the documentation. States without documentation come last, ordered by the name of the state. If the documentation area is used to control the ordering, then it typically contains a value in the form enum=nn where nn gives the state's ordinal position. Note, however, that the documentation is sorted by lexicographic order on the entire value not by numeric order on the ordinal.

Summit state machine transitions are represented in a natural way within a Rose state diagram.

In Summit, the ability to transition from one state to another can be controlled by role and action preconditions. In addition, post-actions can be executed once a state transition has been approved. In a Rose state diagram, preconditions are just referred to as conditions and post-actions are just called actions. Furthermore, via their respective specification dialogs, Rose conditions can be attached to states and Rose actions can be attached to both states and transitions. Since Rose does not directly support conditions attached to a transition nor the notion of role preconditions, some special notation is introduced to represent them.

When used in a Summit state machine, preconditions and post-actions attached to a state are performed by every transition into that state. Preconditions and post-actions attached to a transition are only performed if that particular transition is traversed.

The following table illustrates how to define preconditions and post-actions that are attached to a state:

Summit Concept

State Specification Field

Syntax

Role precondition
Condition
{role_name}
Role precondition
Condition
role:role_name
Action precondition
Condition
action_name
Post-action
Action
action_name

The next table illustrates how to define preconditions and post-actions attached to a state transition:

Summit Concept

Trans. Spec. Field

Syntax

Role precondition
Actions
condition: {role_name}
Role precondition
Actions
condition: role:role_name
Action precondition
Actions
condition: action_name
Post-action
Actions
action_name

As shown, there are two ways of representing a role precondition. They are functionally equivalent. Multiple role_names can be given by separating them with commas as in:

In all cases, a role precondition specification cannot contain any embedded space characters. However, multiple role and action preconditions can be combined by separating them with spaces as in:

Also note that, when attached to a state transition, preconditions must be prefixed with the special string, condition: (with the colon).

Finally, when defining a precondition or post-action attached to a state using Rose's State Action Specification dialog, the Type radio button must be set to Action and the When radio button must be set to On Entry. Only simple entry actions are supported.

Enum Field Definitions

A task field of type enum is considered complex because it defines a set of enumeration values as well as a field. This is represented in the Rose model using a special form of a state diagram. Thus, just like for state task fields, an enum type derived class must be defined to implement the state diagram. In this case, however, the enum type derived class must inherit from the enum field type base class. The enum type derived class, in turn, is used by a task kind class. The name of the uses relationship between the task kind class and the enum type derived class defines the name of the generated task field.

The enum state diagram should contain only normal states. No start state, end states, or state transitions are needed. In fact, the only thing the states are used for is to provide a place to define the enumeration values for the enum field type. The names of the states represent these values which can be any legal enumeration value.

The ordering rules for the enumeration values are identical to those previously described for normal state machines.

Task_Path Field Definitions

A task field of type task_path is considered complex because it defines a bidirectional task relationship. Thus, it really defines two task fields at once. This pair of fields is represented in the model with a Rose association relationship, not a uses relationship. Furthermore, the association relationship must be connected between two task kind classes (concrete or abstract). The two task kind classes may be one and the same. The association relationship is, itself, unnamed. However, the two roles of the relationship must be specified. (As used here, role is a Rose concept, and is not the same as a Summit role.) The roles are set via the association relationship's specification dialog. These role names are used as the generated task_path field names. Note also, in this dialog, that the Name Direction must be <non-directional>, which, for this purpose, really means bidirectional. The cardinality of both ends of the association relationship can be set in order to define one-to-one, many-to-one, or many-to-many task relationships. As before, the cardinality should be set to Unspecified for one or Zero or More (0..n) for many.

To illustrate the mapping of an association relationship to a task kind field definition, consider this example. Suppose a task_path association relationship is defined between the two concrete task kind classes program and document. The role for the program end of the relationship is set to Predecessor with an unspecified cardinality (that is, one). The role for the document end is set to Successor with the cardinality Zero or More. The meaning of this relationship is that a program task is the predecessor to zero or more successor document tasks. When the program and document task kinds are generated, their Fields files will contain the following definitions (among others):

These definitions may seem backward, but note that, although the program task is the predecessor, it must point to its successors and vice versa.

There is one exception to the above representation for task_path field definitions. The implicitly defined task field Name is of type task_path, but it does not define a bidirectional task relationship. Therefore, it is represented in the model the same way as the other simple field types, using the task_path task field type base class. This class should not be used for any other task_path field definitions.

Generating a Task Kind

Once the task kind model has been designed, it is ready to be converted into an actual task kind. This is accomplished by first setting the Directory property (if necessary) and then running the Tools > Generate Task Management Policy command.

The Directory property is a Rose model property that can be accessed and changed from any diagram (as long as no diagram object is selected) by running the Tools > Properties > Edit Properties command. Search the ItemProperty list to find the Directory property. This property defines the parent directory of the generated task kind directories. Its default value, denoted by AUTO GENERATE depends on which version of Rose is being used. On UNIX, it is the directory from which Rose was started. On Windows, it is the Rose application's start-up directory context (which is often the directory in which Rose is installed).

To create a task kind, select one or more concrete task kind classes and run the Tools > Generate Task Management Policy command. If no concrete task kind classes are selected, then task kinds will be generated for all concrete task kind classes in the model. For a given concrete task kind class, a task kind directory (of the same name as the class and within the directory specified by the Directory model property) will be created if it does not already exist. Then the task kind fields definition file (Fields), state machine file (state_field_name.sm) and skeleton actions file (state_field_name.actions on UNIX, state_field_name.act on Windows) will be constructed and stored in the task kind directory. Note, however, that if a state machine file already exists, then the newly generated one will have a name in the form state_field_name.actions.new (state_field_name.new on Windows). The generated action file only contains the names of the action preconditions and post-actions. The actual commands which these actions are to perform must be added manually.


Creating Task Editor Dialogs

Task editor dialogs are the most complex and powerful features of Rational Summit/TM. As such, they can also be the most difficult to customize. To simplify this process, Rational Summit/TM includes a tool, called tegen, which is specifically tailored to the job of creating task editor dialogs. The tegen tools creates a task editor dialog based on a user-defined source file containing a description of the dialog. The tool can be used to create task editor dialogs for both the UNIX and Java interfaces to Summit/TM.

Unix Tegen

For the UNIX interface to Summit/TM, tegen is used in conjunction with apex_guigen which is a more general tool for building UNIX dialogs.

The basic content and format of a task editor is described to tegen with a task editor generation file which always has a .tegen extension. On UNIX, tegen takes such a file, along with the task kind fields definition file (Fields), and produces a temporary dialog generation file (a .dgen file). This .dgen file is then further processed by apex_guigen to produce the final dialog file (a .dlg file). This resultant .dlg file is used by the UNIX interface to Summit/TM to display and execute the dialog whenever an applicable task is visited.

By default, tegen creates a temporary .dgen file and then automatically invokes apex_guigen to generate the .dlg file. The temporary .dgen file is then deleted. The –gen_dgen or –dgen option may be used to save the .dgen file (instead of calling apex_guigen) so that the .dgen file can be customized. Customized .dgen files are not applicable to the Java Interface. Please see Customizing Task Editors with Apex_guigen for detailed information about apex_guigen and .dgen files.

Java Tegen

The Java version of tegen processes the same tegen source files as the UNIX tegen tool. However, the Java version of tegen is automatically invoked to translate the appropriate tegen file when a task is visited. It can only be called by visiting a task.

If there are errors in interpreting the tegen source file, a popup window containing error messages appears. Generally, the tegen source line number and the source line itself are included with each error message.

Locating Task Editors

The UNIX and Java interfaces to Summit use the same rules for locating editor files. Usually, the .tegen source file and .dlg file for a task kind are in the task kind directory. However, another editor location may be specified through customizations (see the Rational Summit/TM Data Structures for details). For example, the user's customization file called ~/.Rational/Task_Gui may indicate specific editor locations for specific task kinds. A customized editor location is a pathname ending with an editor name without a file extension.

For the Java interface to Summit, the .tegen extension is appended automatically to this editor pathname. The resulting pathname is then used to access the tegen source file. In order to locate a task editor via the Java interface, a .dlg file must exist in the same directory as the .tegen file (even though that file is not actually used).

For the UNIX interface to Summit, the .dlg extension is added to the editor name used to access a task editor dialog. The Java interface does not use the .dlg file.

Actions

Both the UNIX and Java versions of tegen support the definition of actions which are essentially subprograms that are called when a button is pressed or a list item is double-clicked.

In earlier versions of Summit/TM, all actions were written in the dlisp language. However, the Java version of tegen does not support actions specified in the dlisp language. The dlisp: section of the .tegen file is ignored by the Java interface.

To address this limitation, new types of action definitions have been added that are supported by both the Java and the UNIX versions of tegen. These action types can perform many common functions. The script action type executes a user-defined script written in the APEX_SHELL language, which is a super-set of the standard UNIX csh language. See Actions Common to Java and UNIX for a complete description of these action definitions.

Using Tegen

New task editor dialogs are typically produced with the following simple procedure. This procedure assumes you are creating a new version of a task editor dialog (called work) from an existing one (called old_work). This old version could just be a copy of the original work task editor dialog.

1 . Change the current working directory to be the task kind directory for the new task editor dialog.

2 . Create an initial task editor generation file, work.tegen, from the previous version, old_work.tegen.

3 . Edit the work.tegen file to remove any unwanted task field widgets or move them to different positions.

4 . Create the dialog file, work.dlg, from the customized task editor generation file, work.tegen.

5 . Test the new task editor dialog by visiting a task whose task editor policy selects the new task editor.

Step 4 above is required to generate the UNIX version of the dialog (the .dlg file). The Java version requires only the .tegen file.

Overall Tegen File Format

A task editor generation file is a text file with a line-oriented format that permits the fields of a task editor to be laid out in roughly the positions that they will occupy in the resultant dialog. In general, this file breaks up a task editor into one or more sections, which in turn consist of multiple boxes, which themselves are divided into one or more rows, which are, at last, composed of many tegen widgets. A .tegen file can also contain user-defined action scripts in the actions part and user-defined dlisp code in the dlisp part.

More specifically, the overall structure of a .tegen file looks like this:

As shown, each section is separated from the next by a line containing only hyphen characters ("–").

User-defined Actions

User-defined action scripts written in the APEX_SHELL language may be included in the actions part following the actions: token. Each script included must have the following form, where name is the user-defined name of the script:

Widgets should not be directly referenced by these scripts but they may be passed as parameters to the script. The actions: token may be omitted if no actions are defined.

User-defined Dlisp Code

Any user-defined dlisp code must be introduced with the dlisp: token. If no dlisp code is needed, then the dlisp: token is not necessary. In general, tegen just copies the dlisp code into the generated .dlg or .dgen file. It does, however, keep track of all the %progs encountered so it can verify that all button widget actions are properly defined. It also supports a special notation for referring to tegen-generated widgets by name within the dlisp code. This special notation looks like this:

Anywhere tegen finds such a pattern within the dlisp code, it removes the // delimiters and verifies that the widget_name has actually been defined. An error is displayed if widget_name is not defined.

Sections

The sections within a .tegen file come in three varieties: normal, framed and paged. A normal section has nothing special about it other than being separated from its adjoining sections. A framed section is just like a normal section except that it will have a lined border drawn around it. A paged section is a normal section which is contained within its own dialog page. These three types of sections are specified as follows:

The /frame switch identifies a framed (bordered) section and must appear alone on the first line of its section.

The /page switch and its associated labels identify a paged section and must also appear alone on the first line of its section. As is true for all tegen labels, they must be enclosed in double quotes.

The "page set label" identifies an entire set of pages to be defined. Each paged section within that set must refer to the same "page set label". The "page menu label" must be different for each paged section in the set and is used to identify the particular page.

The pages in a given set are stacked on top of one another in the dialog layout. The dialog user must select the page to be displayed (brought to the top). For UNIX there are two forms of paged section. In the default form, the page to be displayed is selected from an option menu. In the tabbed form, tabs are displayed at the tops of the pages and a tab is selected to display a particular page. To use the tabbed format on UNIX, the attribute -style TabBook must be specified after the page menu label of the first page in the page set. For example:

The tabbed format is always used in the Java Interface.

Immediately following the special section switches, if any, all sections can contain one or more boxes. Boxes are separated from one another by one or more blank lines as follows:

Boxes

Boxes come in two flavors: normal and columnized. For example:

As indicated, these boxes are separated by blank lines. A columnized box is identified with the /columnized switch, alone, on the first line of the box. Normal boxes are not columnized. What it means to be columnized will be fully explained later, after rows and tegen widgets have been introduced. For now, it should be noted that boxes only indicate which areas should be columnized and which should not. Also, the columns within one columnized box will not necessarily line up with the columns of another. Finally, for a slight performance benefit, adjacent normal boxes are combined into one. This regrouping has no effect on the visible appearance of the task editor dialog.

All boxes are divided into one or more rows. For example:

Rows

Each row corresponds to one horizontal collection of contiguous widgets in the resultant dialog. However, individual widgets can vary considerably in height. So, a given row may occupy a thin area of the dialog or a very thick area depending on the height of its highest widget. In a .tegen file, the widgets within a given row are separated from each other by the vertical bar character ("|") as follows:

Tegen Widgets

Tegen widgets identify the labels, buttons, task fields and other special purpose items which are presented in a task editor dialog. There is a one-to-one correspondence between tegen widgets and dgen widgets although tegen also generates additional dgen widgets to define the rows, boxes and sections into which the tegen widgets are placed. These types of tegen widgets are supported:

Widget Name

Widget Format

Label
"label"
Constant Field
task_field /const
Field
task_field switches
Button
"button_label" /button action
Edit Toggle
"edit_label" /edit_toggle
Transition
"state_label" /transition state_field

Any tegen widget can be followed (after any and all switches) by zero or more dgen attributes in the form:

If any dgen attributes are provided, they are just copied directly into the generated .dgen file to be interpreted by apex_guigen. Such attributes are not normally needed, but can be provided to achieve greater control over how the associated dgen widget is displayed.

The Java version of tegen recognizes only the following specific attributes:

Label Widget

The label widget just displays a constant piece of text in the task editor dialog and is commonly used to identify the value of an associated field widget. Special "dummy" labels can also be defined which contain only one or more space characters (such as " "). These labels can be used to adjust the spacing between widgets or as placeholders in a columnized box. Dummy labels should be used sparingly, if at all.

Constant Field Widget

A constant field widget presents the value of the named task_field in a format similar to that of label widgets. It is commonly used to display simple fields which cannot be changed within its task editor dialog. A task field can be editable, in general, but still be presented as a constant by the dialog. The task_field cannot be a multi-valued field (that is, the associated type for the field cannot contain the "*" notation indicating that it is a list of values).

Field Widget

The field widget is used to display the value of the indicated task_field. Any task field can be used except those of type state. A tegen field widget may be followed by one or more of the following optional switches:

  • The /alt switch specifies that an alternatives icon should be included with the field. This switch can only be used with non-list fields and has the form:
  • The /default_action switch has the form:

    Tegen supports a number of predefined actions which are discussed in detail below. A new action may also be defined in the action: or dlisp: part of the tegen input.

    Tegen selects an appropriate dgen widget for displaying the field value based on the field's type and its (static) editability. Editable multi-valued fields use the scrolled_text dgen widget with default values for the dgen –rows and –columns attributes of 20 and 30. Non-editable, multi-valued fields use the scrolled_list dgen widget with a default value for the dgen –visible_items attribute of 15. These defaults can be overridden by placing like-named attributes and their values at the end of the field widget. Single-valued fields use the text_combo, text_nav_combo, text_alt, or text_simple dgen widgets depending on which icon buttons are required. In all cases, if the task field is not editable, then the dgen widget will be defined as not editable.

    Button Widget

    A button widget must define an action to be performed by the task editor dialog when the button is pressed. The button_label merely specifies the label that is placed on the button so that the user can tell what it should do. The action is called when the button is pressed.

    Tegen supports a number of predefined actions which are discussed in detail below. If a new action is desired, (or a predefined action must be changed), then the implementation of the action must be specified in one of the following ways:

    1 . as an APEX_SHELL script in a separate file,

    2 . as a %script definition, written in the APEX_SHELL language and included in the actions: part of the .tegen file, or

    3 . as a %prog definition, written in dlisp, included in the dlisp: part of the .tegen file.

    Tegen issues an error if a button widget is defined without an associated action. Note that for formatting reasons it is often best to place multiple buttons on a row of their own.

    Edit Toggle Widget

    The edit toggle widget is just a toggle button which indicates if any fields in a task editor dialog have been modified, but not saved. Its edit_label is just used to identify it to the user and it normally has the value "Edit". Currently, every .tegen file must have an edit toggle widget.

    Transition Widget

    The transition widget is only used for task fields of type state. It is used to present a drop-down menu of all the legal state transitions that a user can attempt on a task. The contents of state_label is usually the name of the associated state_field.

    Columnized Boxes

    We are now prepared to discuss columnized boxes in greater detail. The rows in a columnized box can contain one or more tegen widgets. The rows do not have to have the same number of widgets, but the result usually looks better if they do. The widgets in each row are assigned a column number, starting with 1 for the left-most widget and proceeding, in consecutive order, to the right-most widget. Tegen tries to align all the widgets belonging to a particular column, in a left justified manner. If a column is not continuous (that is, if a widget is missing from the middle of a column), then tegen cannot guarantee that the entire column will be lined up, although each continuous sub-column will be properly aligned.

    Here is an example of a columnized box specification where each row has the same number of widgets:

    Such a box might produce a task editor dialog that looks like:

    To illustrate rows with different numbers of widgets:

    This columnized box might look like:

    Note that the last widget in a row with fewer widgets can extend beyond the normal end of its column to the end of the last column in the box. This extension can be suppressed by adding a dummy label (that is, a label whose value only contains spaces, such as " ") to the end of the shorter row.

    Generated Dgen Widget Names

    As indicated previously, at times it is useful in dlisp code to refer to the dgen widgets that tegen generates for the various tegen widgets. In particular, label, constant field and field tegen widgets must often be referred to by the dlisp code using the //widget_name// notation.

    The name of the dgen widget generated for a tegen label widget is a function of the label string. This function converts the string to lower case, substitutes an underscore character ("_") for all illegal widget name characters (including blanks), removes leading, trailing and multiple underscore characters and then appends the string "_label". For example, the tegen label "My Name:" will be converted into a dgen widget with the name my_name_label.

    For a constant field or field tegen widget, the associated dgen widget name is just the name of the field converted to lower case. Thus, the field widget for the task field My_Name is just my_name.

    In all cases, if there are multiple uses of the same label widget label string or field widget task field name, an additional sequence number (in the form "_n") is appended to the previously described dgen widget name. For example, if the following widgets appear in the same .tegen file:

    then the following dgen widget names are generated:

    Example of a Tegen File

    Now we are ready to put all these syntactic elements of a .tegen file together into the following simple example:

    This fully self-contained task editor generation file contains four sections: the first normal, the second framed and the last two paged. The first section contains one columnized box with two rows and the second section has a single normal box with three rows. The "Description" paged section has one box with four rows and the "Related Tasks" paged section has two boxes with four rows and one row respectively.

    The "Visit" button widget has an associated action %prog called act_visit_task which is defined in the dlisp: code area. This %prog references the dgen widgets associated with the Children and Parent task field widgets as //children// and //parent//.

    Tabbed Paged Sections

    The "paged" sections of task editor dialogs may be formatted as a horizontal row of tabs containing the "page menu labels" specified for each page in the tegen source file. A tab is clicked to select a particular page. In the UNIX implementation, this format is used only if the attribute -style TabBook is specified for the first page in the set. The tabbed format is always used by the Java implementation.

    If the page menu labels are long or there are many pages, the tabs generated may not fit within the dialog's width. This forces the user to widen the dialog to see the rest of the tabs.

    One way to address this problem is to make the page menu labels shorter. If the tabs are still too wide for the dialog, the problem can generally be solved by using "nested tabbed pages". Nesting of tabbed pages is used in the standard task editor dialogs. For example, the standard "change" task editor dialog has the following collection of page menu labels:

    Description
    Related Tasks
    Version History
    Development
    – Design
    – Test
    Problem Report
    – Background
    – Symptoms
    – Test Sequence
    – Workaround
    – Patch
    Task History

    In the tabbed format for this page set, the top level tabs (displayed horizontally) are:

    Description
    Related Tasks
    Version History
    Development
    Problem Report
    Task History

    When the "Development" tab is selected, the following nested tabs appear:

    Development
    Design
    Test

    Similarly, when the "Problem Report" tab is selected, the following nested tabs appear:

    Problem Report
    Background
    Symptoms
    Test Sequence
    Workaround
    Patch

    Nested tabs are created by using special page menu labels. Each page whose page menu label starts with a hyphen (–) is assumed to be a nested page. The page that precedes a group of such pages is also considered a nested page belonging to the same group. A new parent page with same page menu label as this page is created and all of the nested pages are represented as another row of tabs within this parent page.

    In the example above, the page menu labels "Development", "– Design", and "– Test" form a nested group and the parent page for this group is given the label "Development".

    This nesting technique is recommended when a large number of pages is required. If necessary, deeper levels of nesting can be obtained by included additional hyphens, so that a page menu label such as "–– Test Results" will indicate a second level of nesting.


    Actions Common to Java and UNIX

    As mentioned above, the use of dlisp code to implement task editor dialog actions is not supported by the Java interface to Apex and Summit. However, there is a special set of actions which are supported both by Java and UNIX task editor dialogs created using the tegen tool. These actions can be activated by buttons or by the double-clicking an item in a list field.

    The new types of actions supported are:

    action_visit
    Visits any directory or file identified in one or more task editor dialog fields.
    action_visit_task
    Like action_visit, except that the .task extension is added, if there is no file extension, and the domain of the current task is assumed, if the name is not qualified.
    action_create_task
    Invokes the File > New > New Task dialog with specified options to create a new task.
    run script
    Executes a user-defined apex shell script accepting input arguments and output arguments which may be used to update fields in the task editor dialog. The script may be included within the tegen source file, or a script stored in a separate file may be referenced.

    These actions accept arguments and are therefore somewhat more flexible than user-defined dlisp actions which do not support arguments.

    The run script type of action is the most versatile since Apex and Summit commands can be invoked and shell programming constructs such as if-commands and loops can be used. However, since the script runs on the Apex/Summit server, these actions cannot invoke other Java dialogs or visit files via the Java interface. That is why the action_visit, action_visit_task, and action_create_task are also provided.

    In addition to these action types, both the Java and UNIX versions of tegen also support the following, predefined actions which have no parameters, (see Predefined Action Programs):

    act_check_in_task
    act_check_out_task
    act_new_child
    act_visit_task
    act_visit_parent
    act_visit_current
    act_show_version_image
    act_show_versions

    Action Syntax

    Actions are specified as part of the widget that invokes the action. For a button, the syntax is

    "button_label" /button action

    where button_label is the label to appear on the button. For the alternatives icon button of a task field, the syntax is

    task_field /alt action

    where task_field is the field name.

    For the default action of a list field, the syntax is

    task_field /default_action action

    where task_field is the field name.

    An action identifies the action and specifies the arguments to the action (if any). The syntax for an action is:

    action ::= action_id [([arguments])]

    action_id ::= action_visit |
    action_visit_task |
    action_create_task |
    act_check_in_task |
    act_check_out_task |
    act_new_child |
    act_visit_task |
    act_visit_parent |
    act_visit_current |
    act_show_version_image |
    act_show_versions |
    script_id

    script_id       ::= script_name | "script_pathname"
    script_name     ::= identifier
    script_pathname    ::= character...

    The action_id identifies the action to be invoked. If the action_id is an identifier that does not match any of the specific action names above, it is assumed to be a script_name. In this case, an apex shell script with that name must appear in the actions: part of the tegen file (described later). The action defined executes that script.

    Alternatively, the script_id may identify a %prog in the dlisp part of the .tegen file. However, in this case the action is not supported by the Java interface and no arguments are allowed.

    If the action_id is enclosed in double quotes, it is assumed to be a script_pathname. The pathname must identify a file containing an APEX_SHELL script. The action defined executes the script in that file.

    The arguments (if any) must be enclosed in parentheses. An empty argument list can be indicated by "()" or by specifying only the action_id. All of the action names above that begin with "act_" are the older, predefined actions that do not accept arguments.

    Action Arguments Syntax

    The list of arguments to an action has the syntax:

    arguments ::= arg [, arg]...
    arg ::= [arg_name =] [in] [out] arg_value
    arg_name ::= identifier

    Multiple arguments must separated by commas (,). Arguments may be either named or positional. A named argument begins with an identifier followed by the arrow symbol (=>). The arguments to an action must be either all named or all unnamed. The names of arguments must be distinct. The order of arguments in a named argument list has no affect. The order of arguments in an unnamed (positional) list is significant because the arguments are referenced by position.

    An argument may be specified to be an in argument or an out argument or both (in out). If neither in nor out is specified, in is assumed. The value of an in argument is passed as an input to the action. The value of an out argument is returned by the action and is used to update a field in the dialog.

    The arg_value specifies the actual argument passed as described in the next section.

    Argument Value Syntax

    arg_value ::= field_ref | "string_literal"
    field_ref ::= field_name [. selected]
    field_name ::= identifier
    string_literal ::= character...

    An arg_value (argument value) is either a field_ref (field reference) or a string_literal (a sequence of characters enclosed in double quotes). A field reference may be used as an in, out, or in out argument. The value of a string_literal argument is simply the string enclosed by the double quotes. A string literal cannot be used as an out argument.

    A field_ref refers to the value of a field. For an in argument, the value of a field_ref is the current value in the field identified by the field_name within the dialog. If the dialog does not have such a field, the current value of the field in the task itself is used.

    If the .selected suffix is included, the value passed to the action is the current selection within the dialog field. For a simple field, the selection consists of the selected characters in the field. For a list field, the selection is the selected list item. If no character or list item is selected in the field, the value is the empty string.

    The .selected suffix can only be used when the field_name identifies a field in the dialog. The .selected suffix may not be used for an out argument.

    For an out argument, the field_ref must identify an editable task field within the dialog. The value of this field is updated with a result from the action. Note that out arguments do not update the task itself, but only fields in the dialog. After a field is updated as the result of an action, the user may update the task accordingly by clicking the OK or Apply button.

    action_visit and action_visit_task

    The syntax for these actions is:

    action_visit ( arguments )
    action_visit_task (
    arguments )

    At least one argument is required. The arguments must be unnamed in arguments. When the action is invoked, each argument is evaluated in order until a non-empty value results. This value is assumed to be the pathname of a directory or file to be visited. For example, the action

    visits the file whose pathname appears in the dialog field called "design_document" or, if that field is empty, the directory having the literal pathname "/documents".

    The action

    visits the current selected task in the "children" list field or, if no such task is selected, the task in the "parent" field.

    The visit actions issue an error message if no pathname is found or if no object with that pathname exists.

    action_visit_task is similar to action_visit except that a task to be visited may be specified using the simple task id, without the .task suffix. The domain of the current task is assumed if the id is not qualified.

    This action can be used, for example, to implement a button that will visit a task mentioned in the "description" field of a task when the task name is selected in that field. The action for such a button is simply:

    action_create_task

    The syntax for the action_create_task is:

    action_create_task [([arguments])]

    This action displays the File > New > New Task dialog, allowing the user to create a new task. It has no direct affect on the task editor dialog which invokes it. The arguments are optional and provide initial values for the fields of the New Task dialog. The arguments must be named and the allowed names refer to fields of the New Task dialog as follows:

    domain  "Domain:"
    parent  "Parent:"
    kind  "Kind:"
    template  "Template:"
    name  "Name:"

    Any combination of these arguments is permitted. When an argument is omitted, the usual defaults apply to the initial value of the field in the New Task dialog.

    For example, the action

    brings up the New Task dialog with the Domain and Kind fields set to the same values as the domain and kind of the current task and with the Parent field set to designate the current task. Here, the identifiers "domain", "name" and "kind" which follow the arrows (=>) are references to fields of the current task. The Template field (which is omitted) will be set to the default for the task kind.

    Run Script Actions

    These actions cause user-defined APEX_SHELL scripts to be executed. Fields of the dialog may be updated as a result of running the script using out arguments. The general syntax is

    script_id [(arguments])]

    where

    script_id ::= script_name | "script_pathname"
    script_name ::= identifier
    script_pathname ::= character...

    There are two forms of script_id. The script_name form is an identifier that references a script included directly in the actions: section of the tegen source file (the syntax for this is described later). The script_pathname is a string literal in double quotes. The value of the string literal is must be the pathname of a separate file containing the APEX_SHELL script.

    Script Arguments

    The arguments required (if any) are determined by the author of the script. It is important that the arguments passed to a script meet the expectations of the script, however, there is no mechanism (as yet) to verify this automatically before the action is invoked.

    Arguments may be named or positional (unnamed). Arguments are referenced within the script using certain shell variables. When named arguments are used, the value of an argument may be referenced in a script using the expression

    $arg_name

    where arg_name is the argument name. The value of a named out argument may be set in a script using the command

    where arg_name is the argument name and value is the value to be assigned to the argument. For example, a named in out argument called "doc_file" might be referenced in a script as follows:

    Positional arguments work in a similar way except that the effective name of an argument is formed using the position of the argument. This name is

    arg[n]

    where n is the argument position (1, 2, 3 etc.). (Note that here the brackets ([]) are required characters rather than an indication that n is optional.) Positional arguments values are referenced using the expression

    $arg[n]

    and may be set using the command

    where n is the argument position. If the "doc_file" argument in example above, was instead the third positional argument (number 3), the script would contain

    The number of positional arguments passed to a script can be obtained from the expression:

    $#arg

    In addition, positional arguments that are not out arguments may also be referenced using the simpler notation:

    $n

    where n is the argument position.

    Optional Script Arguments

    A script may be written in such a way that some or all of its arguments are optional. When a script uses positional arguments, only trailing arguments can be omitted. When named arguments are used, any argument can be omitted. A script can check whether a named argument has been passed using the expression:

    $?arg_name

    The value of this expression is 1 (true) if the argument was passed, and 0 (false) if it was not. Note that execution of a set command like

    will always cause the subsequent value of the expression $?arg_name to be 1.

    Some caution must be exercised is selecting names for optional arguments since environment variables may be inadvertently referenced as though they were script arguments. One workable strategy is to always use uppercase names for environment variables (as Apex and Summit do) and lowercase names for script arguments.

    For optional positional arguments, the number of arguments passed must be tested using the expression $#arg before accessing an argument. If an argument is accessed using

    $arg[n]

    and n is greater than the number of arguments passed, a shell error will occur and the script will be aborted.

    It is good practice to test that the required arguments are provided at the beginning of a script.

    When an in or out argument is omitted, the corresponding shell variable is not set. When an out argument is omitted, no field in the dialog is updated even though the script may set the value of the missing argument.

    Execution of Script Actions

    When a script action is executed, all of the in arguments are evaluated. The values of the shell variables that represent these arguments are initialized accordingly. The initial value given to shell variables representing arguments that are not in (that is, only out) is the empty string (""). Any arguments that are not supplied are not given a value.

    A script must return a result indicating whether execution was successful. This result is returned using the apex shell return command which has the syntax:

    return value

    where value is the value to be returned. If the value returned is "0", the script is considered successful. If any other value is returned, the script is assumed to have failed. For example, the following return command returns the status of the last command executed:

    In this case, the script is successful if the last command executed was successful.

    If the script returns "0" (indicating success), the values of the out arguments are stored in the fields indicated by the argument list. In the case of a failure, the values for out arguments are discarded and fields of the task editor dialog are not changed by the action. When an out argument is omitted, no field is updated for the missing argument.

    Scripts can invoke various predefined functions to access Summit task information. See Accessing Rational Summit/TM Data from Actions.

    Script Output

    All messages that are written to standard output by the script are displayed in the Apex or Summit message window. In the case of the Java interface, these messages will appear at the bottom of the Directory Browser window when the script completes execution.

    When a script fails, an error message box may be popped up to alert the user that something has gone wrong. A script can produce a popup message box by invoking the following special command:

    message_box [-title title] message

    The title is the title to appear at the top of the message box. If omitted, the title "Error" is used. The message is displayed as the contents of the message box. The title and message should be enclosed in quotes when they contain spaces or special shell characters. In the Java interface, the message box is displayed when the script completes execution.

    When a script does not return "0" (success) and no message_box command has been executed by the script, an error window containing the return value is popped up automatically.

    If a script contains errors such as shell syntax errors or references to undefined commands, the script is aborted and an error box is displayed specifying the error encountered and the line number within the body of script. The echo command is useful in debugging a script.

    Scripts in the actions: Section

    The script invoked by an action may be included within the same tegen source file in the actions: section. The actions section must immediately follow all of the widget definitions in the tegen source file. The syntax of the actions section is

    actions ::= action_line
    script...
    action_line
    ::= actions:
    script ::= script_start_line
    script_body
    script_end_line
    script_start_line :
    := %script script_name
    script_body
    ::= line...
    script_end_line
    ::= %script_end
    line ::= character...

    where each item described as a "line" must appear on a separate line. The action_line indicates the start of the actions: section. Each script_start_line indicates the beginning of a script and specifies the script_name of the script. The script_end_line marks the end of a script.

    The script_body consists of any number of lines of text written in the APEX_SHELL language. The APEX_SHELL language has the same syntax and capabilities as the standard UNIX cshell and provides many extensions useful in the context of Summit/TM. See the Scripting Language Guide" for a detailed description of the APEX_SHELL language.

    The following is an example of two simple scripts that check-out or check-in a file, assuming that the target file is passed in the named argument "file":

    The indentation and blank lines shown are not required. These scripts could be improved by verifying that a non-empty "file" argument was passed. For example:

    Note that several actions in the same tegen file can invoke the same script in the actions section (usually with different argument values).

    Scripts in Separate Files

    Alternatively, a script may be stored in a separate file. In this case, actions must refer to the file by its full pathname enclosed in double quotes. The file should contain only the script_body. The %script and %script_end lines must be omitted.

    When a script is stored in a separate file, it may be referenced by multiple task editor dialogs. An additional benefit of using a separate file is that the script does not have to be transmitted to the Apex or Summit server when the Java interface is used. This makes action execution somewhat faster if the script is long.

    Scripts Used as "/alt" Actions

    When the /alt switch is used on a task field, the contents of the menu displayed by the alternatives icon is determined by invoking the specified action script. Such scripts may have only in arguments and must set the APEX_SHELL wordlist variable called alt_items. The items placed in that variable are the items displayed in the alternatives popup menu.

    For example, to cause the popup menu to display the values Red, Yellow and Blue, the action script should do this:

    Accessing Fields in APEX_SHELL Scripts

    In an APEX_SHELL script, the value of a field as currently displayed in the dialog may be accessed by passing the field name as an in argument. Similarly, the value of a field as displayed in the dialog may be changed by passing the field name as an out argument. In the case of a state field widget (defined with the /transition switch), the value is either the current state, or the target state of an allowed transition.

    It is also possible to access the current value of a field, as defined in the task itself, by passing the field name to the script. The name field contains the full pathname of the task. Assuming name is passed as the first positional argument, the value of a field named field_name can be accessed as follows:

    See the Scripting Language Guide for a detailed description of the APEX_SHELL task type.

    Predefined Action Programs

    Tegen also supports the following predefined action programs which do not accept arguments. These programs do not have to be explicitly defined in the .tegen file unless it is desired to replace the built-in definitions with customized versions.

    This action program is used to check-in the task displayed by the task editor. The task must already be a controlled object.

    This action program is used to check-out the task displayed by the task editor. The task must already be a controlled object.

    This action program is used to create a new child task of the task displayed by the task editor. That is, the displayed task becomes the parent of the new child task. This program actually activates the Task Editor - New Child Task dialog with its fields filled in appropriately. This program references the domain task field widget.

    This action program is used to visit either the parent task or a child task of the task displayed by the task editor. The task to visit must first be selected. This program references the children and parent task field widgets.

    This action program is used to visit the current version of the object selected in the CmvcVersions field widget, ignoring the actual version number of the selected object. That is, the version of the object which is in the view selected, is visited. This program references the cmvcversions task field widget.

    This action program is used to show the image of the version of the object selected in the CmvcVersions field widget. A temporary copy of this version is created. This program references the cvcmversions task field widget.

    Externally Called Dlisp Programs

    There are a number of dlisp %progs that every task editor dialog must define because they are called by other parts of the Rational Summit/TM system which are outside the customizable boundaries of a task editor dialog. For the most part, users do not have to worry about these %progs when using tegen. Tegen automatically defines the %progs as needed. However, since they appear in the generated .dgen file, it can be helpful to know what they are there for. If these %progs are not defined, then undesirable warnings and error messages may be displayed when they are called.

    This program is called whenever the Children field of a task being accessed by a task editor is modified by some other Rational Summit/TM command. It is used to keep the displayed value of the Children field up to date. If the task editor dialog does not have a Children field widget, then this %prog will do nothing, but it must still be defined.

    Similarly, these programs are called whenever a version is added to or removed from the displayed task's CmvcVersions field. If the task editor dialog does not have a CmvcVersions field widget, then these programs will do nothing, but they must still be defined.

    This program can contain any user-defined dlisp code to be executed as part of the standard %prog build.

    This program can contain any user-defined dlisp code to be executed as part of the standard %prog setup.

    This program can contain any user-defined dlisp code to be executed as part of the standard %prog init. Tegen automatically places some code here for initializing the page widgets and for initializing the values of task field widgets that are referred to more than once in the task editor dialog.

    This program can contain any user-defined dlisp code to be executed as part of the standard %prog exec. It is called when widgets representing task fields have been modified and the OK or Apply button is pressed.

    Accessing Rational Summit/TM Data from Actions

    A number of specialized commands are provided to support the implementation of Task Editor dialogs and Summit/TM dialogs in general. These commands may be invoked from either an APEX_SHELL action %script or from a dlisp action %prog in the same manner as any other command. However, the commands below which begin with tk_task_ may not be used in Java task editor dialogs. The APEX_SHELL provides other functions for accessing task data that do work with Java task editors dialogs. See the "Scripting Language Guide" for a detailed description of the APEX_SHELL task type which provides access to task data.

    In cases where no return value is specified for a command below, the empty string is returned. If a command 'fails', the %prog or %script which invokes it is abandoned as though the fail command was executed. In general, the following parameters are used in these commands:

    domain
    the full path name of a task domain.
    kind
    the simple name of a task kind in domain.
    field
    the name of a field defined by the task kind.
    value
    the (string) value of a task field.
    task_id
    the full pathname of a task.
    task_list
    the full pathname of a task list
    simple
    a boolean value (true or false) used in commands that support popup menus. When true, the popup menu entries are returned. When false, the corresponding resultant values of popup selections are returned.

    The syntax used to call these commands depends on whether the call is written in the APEX_SHELL or the dlisp language. For example the variable value may be set to the current value of the task field called summary as follows for the APEX_SHELL

    whereas in dlisp, a corresponding call is

    In the command descriptions below, the dlisp syntax is used but it should be understood that the APEX_SHELL syntax may be used as well.

    The commands prefixed with tk_task_ implicitly refer to a task which has been associated with the dialog by invoking the tk_task_init command. These commands cannot be called by Java task editor dialogs.

    The following Summit/TM-support commands are provided:

    <tk_field_default,domain,kind,field>
    

    Returns the default value for the specified field. The default value depends on the type of the field. For enum type fields, it is the first enum literal.

    <tk_valid_field_name,domain,kind,field>
    

    Returns true if field is a the name of a field defined by the specified task kind; otherwise false is returned.

    <tk_role_popup,domain>
    

    Returns the list of roles (one per line) granted to the current user by domain. These are the roles specified in the domain itself.

    <tk_get_role,domain>
    

    Returns the list of effective roles (one per line) granted to the current user for domain. This list takes into account the roles granted by the domain as well as any restrictions on the user's roles for that domain specified in the user's ~/.Rational directory.

    <tk_field_edit>
    

    Returns the list of non-editable field names as determined by executing the associated task kind's Field_Edit.ash APEX_SHELL script. If no such script is defined, an empty list is returned.

    tegen

    Syntax:

    Description:

    Creates a new dialog file (a .dlg file) or dialog generation file (a .dgen file) from a simpler task editor generation file (a .tegen file). The .dgen file can be modified if necessary and then be processed by apex_guigen to create the UNIX task editor dialog file (the .dlg file).

    For Java task editor dialogs, the .tegen file is interpreted directly and automatically when a task is visited.

    The –example option can be used to create the initial .tegen file, for a newly customized task kind, from an existing .tegen file (once the new task kind's Fields file has been updated). Any task fields that are in the Fields file (but not in the example .tegen file explicitly) are automatically incorporated, just before the dlisp section. The new tegen_file can be edited to place the new field widgets in the desired positions within the task editor dialog.

    Once the initial tegen_file is created, tegen can be used without the –example option to regenerate the .dlg or .dgen file directly from tegen_file.

    Parameters:

    Examples:


    Apex Guigen

    Customized task editors can be built using the apex_guigen tool. This tool takes a .dgen file as input and produces a dialog file (.dlg file) that Apex and Summit can then use to display the associated task editor dialog. Apex_guigen must be run under an Apex or Summit shell. Customizations of task editors using apex_guigen apply only to the UNIX interface to Summit.

    The details on how to run apex_guigen and on the interpretation of .dgen files can be found in the chapter Customizing Task Editors with Apex_guigen and the chapter Customizing Task Editor Actions using Dlisp.


    Customizing Rational Summit/TM Commands

    Customization of Rational Summit/TM operations is accomplished on a per task domain basis through a customization key in the domain which associates actions (scripts) with the domain. Each action has a name, and actions with specific names are invoked before and after the execution of various Rational Summit/TM operations.

    Customization Key

    The customizations to be used for a task domain must be specified in the file

    task_domain_subsystem/Policy/Taskmgmt.sw

    where task_domain_subsystem is the subsystem name of the domain. The Rational Summit/TM customization key is given by a line in this file of the form

    where file... is list of qualified pathnames of action files. Wild cards may be used in the file names. The contents of each action file must be zero or more actions. An action is a named Apex or Summit script similar to a csh shell script. Actions are also used in Apex and Summit to define custom menu commands. A given action name should occur only once in the action files named in the customization key.

    When a customizable Rational Summit/TM command is executed, the actions associated with the task domain of the target task are checked for customization actions (with specific names) associated with that command. Just before a command is executed, the pre-action (if any) for that command is invoked. If the pre-action returns a non-zero value, the command fails and is not executed. If zero is returned, the command is executed and then the post-action (if any) for the command is executed.

    When an action is invoked, a number of parameters are passed (depending upon the specific command) to provide detailed information about the operation. These parameters are accessed positionally in the action using prompts of the form PARM_N where N is the number of the parameter (1, 2, etc.). For example, PARM_2 accesses the second parameter. The prompt PARM_0 accesses the name of the action. Any parameter whose value is a list is provided as a single token by enclosing the space-separated list of items in quotes.

    Some customization actions are executed for each task domain or task involved in an operation. This can involve considerable overhead for commands that process many tasks (for example. Tasks > Query).

    The specific actions invoked, their parameters, and the commands they are associated with are specified in the following subsections.

    Note: In the roles parameter of an action, the value "ALL_ROLES" is substituted for "*".

    Note: In addition to the actions described below for the add_task and remove_task commands, there may be Summit/CM customization operations defined as well. In this case, the Rational Summit/TM and Summit/CM customizations are executed in the following order:

    Rational Summit/CM pre-operation script
    Rational Summit/TM pre-operation action
    Rational Summit/CM post-operation script
    Rational Summit/TM post-operation action

    pre_create_task

    This action is called before a new task is created.

    Parameters

    1 . roles - the effective roles of the current user for the domain.

    2 . domain - the full path name of the task domain.

    3 . kind - the full pathname of the task kind.

    4 . fields - the pathname of a temporary file containing the values of fields to be initialized in field-value format.

    post_create_task

    This action is called after a new task is created.

    Parameters

    1 . roles - the effective roles of the current user for the domain.

    2 . domain - the full path name of the task domain.

    3 . kind - the full pathname of the task kind.

    4 . fields - the pathname of a temporary file containing the values of fields initialized in field-value format.

    5 . task_name - the full pathnames of the tasks created.

    pre_modify_task

    This action is called before the modify_task command is applied to a task.

    Parameters

    1 . roles - the effective roles of the current user for the domain.

    2 . task_name - the canonical pathname of the task.

    3 . fields - the pathname of a temporary file containing the new field values in field-value format.

    post_modify_task

    This action is called after the modify_task command is applied to a task.

    Parameters

    1 . roles - the effective roles of the current user for the domain.

    2 . task_name - the canonical pathname of the task.

    3 . fields - the pathname of a temporary file containing the new field values in field-value format.

    pre_add_task

    This action is called before the add_task command is applied (directly or via the Add Task dialog) to associate tasks with a version.

    Parameters

    1 . roles - the effective roles of the current user for the domain.

    2 . task_names - the canonical pathnames of the tasks to be associated with the version.

    3 . file - the pathname of the object to be associated.

    4 . history - the name of the version history.

    5 . version - the version number of the object version to be associated.

    post_add_task

    This action is called after the add_task command is applied (directly or via the Add Task dialog) to associate tasks with a version.

    Parameters

    1 . roles - the effective roles of the current user for the domain.

    2 . task_names - the canonical pathnames of the tasks that were associated with the version.

    3 . file - the pathname of the object associated.

    4 . history - the name of the version history.

    5 . version - the version number of the object version associated.

    pre_remove_task

    This action is called before the remove_task command is applied (directly or via the Remove Tasks dialog) to disassociate tasks from a version.

    Parameters

    1 . roles - the effective roles of the current user for the domain.

    2 . task_names - the canonical pathnames of the tasks to be disassociated from the version.

    3 . file - the pathname of the object to be disassociated.

    4 . history - the name of the version history.

    5 . version - the version number of the object version to be disassociated.

    post_remove_task

    This action is called after the remove_task command is applied (directly or via the Remove Tasks dialog) to disassociate tasks from a version.

    Parameters

    1 . roles - the effective roles of the current user for the domain.

    2 . task_names - the canonical pathnames of the tasks that were disassociated from the version.

    3 . file - the pathname of the object disassociated.

    4 . history - the name of the version history.

    5 . version - the version number of the object version disassociated.

    pre_show_fields

    This action is called before fields of a task are shown via the list_task command, the show_summary command, or the menu commands Tasks > Show and Tasks > Query.

    Parameters

    1 . roles - the effective roles of the current user for the domain.

    2 . task_name - the canonical pathname of the task.

    3 . kind - the full pathname of the task kind.

    4 . fields - a string containing the field names separated by spaces.

    post_show_fields

    This action is called after fields of a task are shown via the list_task command, the show_summary command, and the menu commands Tasks > Show and Tasks > Query.

    Parameters

    1 . roles - the effective roles of the current user for the domain.

    2 . task_name - the canonical pathname of the task.

    3 . kind - the full pathname of the task kind.

    4 . fields - a string containing the field names separated by spaces.


    Enhancements to Summit/CM Customizations

    This section describes additional customization features of Rational's Summit/CM (Configuration Management) system provided for Rational Summit/TM commands. Only the additional customization operations are described here.

    Accessing Task Ids in Customization Actions

    CMVC customization operations for commands which include a task parameter may access the tasks specified using the environment variable APEX_INPUT_TASKS. The variable contains the full pathnames of the task specified.

    Version Control Customization

    The following sections describe the customization operations (for Rational Summit/TM commands) called by Summit/CM using the version control key. The first parameter of each customization is called rev and takes the form

    major_number.minor_number

    The major_number is incremented for incompatible changes to the customization interface. The minor_number is incremented for upward compatible changes to the interface.

    The Rational Summit/TM commands associated with Summit/CM customization operations are add_task and remove_task. These commands are also invoked by the dialogs Add Tasks and Remove Tasks.

    These commands can also have associated Rational Summit/TM customization actions. The order of execution is that case is the following:

    Rational Summit/CM pre-operation script
    Rational Summit/TM pre-operation action
    Rational Summit/CM post-operation script
    Rational Summit/TM post-operation action

    pre_add_task

    Syntax

    Description

    Called prior to associating tasks with a version of a controlled object using add_task.

    Parameters

    post_add_task

    Syntax

    Description

    Called after associating tasks with a version of a controlled object using add_task.

    Parameters

    pre_remove_task

    Syntax

    Description

    Called before disassociating tasks from a version of a controlled object using remove_task.

    Parameters

    post_remove_task

    Syntax

    Description

    Called after disassociating tasks from a version of a controlled object using remove_task.

    Parameters


  • Rational Software Corporation 
    http://www.rational.com
    support@rational.com
    techpubs@rational.com
    Copyright © 1993-2001, Rational Software Corporation. All rights reserved.
    TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS