![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
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
- Viewing and Modifying Tasks as Text Files
- Creating New Task Domains
- Creating New Task Kinds
- Creating Task Editor Dialogs
- Actions Common to Java and UNIX
- Apex Guigen
- Customizing Rational Summit/TM Commands
- Enhancements to Summit/CM Customizations
Changing Rational Summit/TM DataThe 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 FilesTasks (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:
visit -as_text C00001.task
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 DomainsTo 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
create_task_domain [options
]view
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:
$APEX_BASE/task/task_domain_prototype.ss
Parameters
- view
Specifies the pathname of the new task domain view. The view must not already exist, however, the subsystem may or may not exist.
- options
Specifies pathnames of task kind directories to be included in the domain's kind path (the task kinds supported by the domain). If the task domain subsystem already exists, the kind directories specified are appended to the existing kind path, unless the –replace option is used. In that case, the specified kinds replace the existing kind path. The pathnames specified must identify existing kind directories, unless the –force option is used. When multiple kind directories are specified, they must be enclosed in quotes.
Default value: (from prototype, see discussion above)
Replace the existing kind path with the path specified in –kind instead of appending.
Allows kind directories which do not exist to be specified in the –kind option. It is presumed that the kinds will be created before the domain is used.
Provides the task id prefix for the task id generation policy of the task domain subsystem. The prefix can be any string suitable for a file name prefix.
Default value: (from prototype, see discussion above)
Specifies the task id suffix for the task id generation policy of the task domain subsystem. The suffix can be any string suitable for a file name root suffix.
Default value: (from prototype, see discussion above)
Provides the minimum task index width for the task id generation policy of the task domain subsystem. The width should be a non-negative integer. The task index portions of generated task ids are padded on the left with zeros, if necessary, to ensure this minimum width.
Example
create_task_domain -kind /proj/task_kinds.ss/all.wrk/bug \ -prefix B /proj/task_domain.ss/all.wrk
Creating New Task KindsTo 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
copy_task_kind [options
]source destination
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
- source
An existing task kind directory to be copied.
- destination
The location for the new task kind directory. The directory specified must include a view within an existing subsystem. If the view does not exist, it will be created. If the directory specified is a view or an existing subdirectory, the new kind directory is created as a subdirectory of that directory with the same name as the source kind directory. Otherwise, the specified directory is created and used as the destination kind directory.
- options
Makes the files created in the new kind directory controlled objects.
Examples
copy_task_kind /proj/task_kinds.ss/all.wrk/bug \ /proj/my_kinds.ss/my.wrk/work cd /proj/task_kinds.ss/all.wrk copy_task_kind bug work
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:
$APEX_BASE/task/task_kinds.ss/share.*.rel/rose
- 1 . Install the special Code Mapper program for Rational Summit/TM into Rose/C++:
- If Rose/C++ version 3.0.2 for Windows is being used, then transfer task_rose_dir/policy.302.cx to rose_dir\policy.cx. Note that this file must be transferred in binary mode.
- If a later version of Rose/C++ for Windows is being used, then transfer task_rose_dir/policy.cx to rose_dir\policy.cx. Note that this file must be transferred in binary mode.
- If Rose/C++ version 3.0.3 (or later) for UNIX is being used, then copy task_rose_dir/policy.cx to rose_dir/codegen/policy.cx.
- 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:
Separator option "Generate Rational Summit Policy" { codemapper policy.cx }
The file task_rose_dir/rose_cpp.mnu contains an example of what the result of this step might look like depending on how Rose/C++ is configured. It is only an example and should not be copied verbatim.
- 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.
Class Diagram Class Category Class Abstract Adornment Association Relationship Cardinality Adornment Has Relationship Cardinality Adornment Inherits Relationship
State Diagram State (Start, Normal or End) State Specification Documentation Actions State Transition State Transition Specification Condition Action
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:
- date
- enum
- fixed
- float
- int
- path
- string
- task_path
- state
- text
- version
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:
The next table illustrates how to define preconditions and post-actions attached to a state transition:
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:
{role_name1,role_name2}
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:
{role_name1,role_name2} action_name1 action_name2
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):
program/Fields Successor: task_path* Predecessor documentation/Fields Predecessor: task_path Successor
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 DialogsTask 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.
tegen -example old_work work
- 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.
tegen work
- 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:
section 1 --------------------------------- section 2 --------------------------------- . . . section n --------------------------------- actions: # Optional one or more APEX_SHELL scripts dlisp: # Optional one or more lines of dlisp code
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:
%script name # one or more lines of APEX_SHELL code %end_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:
//widget_name//
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:
normal section ------------------------------------------ /frame framed section ------------------------------------------ "page set label" /page "page menu label" paged section ------------------------------------------
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:
Pages: /page "Task Description" -style TabBook
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:
box 1 box 2 . . . box n
Boxes
Boxes come in two flavors: normal and columnized. For example:
normal box 1 normal box 2 /columnized columnized box 3 /columnized columnized box 4
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:
row 1 row 2 . . . row n
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:
widget 1 | widget 2 | widget 3 | ... | widget 4
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:
Any tegen widget can be followed (after any and all switches) by zero or more dgen attributes in the form:
-attribute_name attribute_value
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:
-rows number -columns number -visible_items number
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 /nav switch specifies that the standard navigate, history, and completion icon buttons should be included with the field. This switch can only be used with non-list fields and has the form:
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:
/alt action
The specified action is invoked when the alternatives icon is pressed. The action names a user-defined APEX_SHELL script and may include (input only) arguments to that script. The script specifies the items to appear in the alternatives popup menu by setting the wordlist variable called alt_items. For example, if the script contains
set alt_items = (Red Yellow Blue)
the popup menu will contain the alternatives Red, Yellow, and Blue. Action scripts are discussed in more detail below. The /alt switch does not prevent users from entering other values into the field. Actions used for this purpose cannot have any out arguments.
If the /alt switch is omitted for an enum type field, an alternatives icon which displays all possible values for the field (as defined by the task kind's Fields file) is provided by default.
The /default_action switch has the form:
/default_action action
This switch is only supported for list fields. The specified action is invoked when an item in the list field is double-clicked.
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:
/columnized "Who:" | Who | "What:" | What "Where:" | Where | "When:" | When "Why:" | Why | "How:" | How
Such a box might produce a task editor dialog that looks like:
Who: You What: Clean up the backyard Where: Your house When: Saturday afternoon Why: It's a mess How: With a rake
To illustrate rows with different numbers of widgets:
/columnized "Who:" | Who | "Where:" | Where "When:" | When | "What:" | What "How:" | How "Why:" | Why
This columnized box might look like:
Who: You Where: Your house When: Saturday afternoon What: Clean up the backyard How: With a lawn mower, a rake and a broom Why: Because I told you to do it and I mean business
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:
"My_name:" | my_name /const "MY_NAME" | My_Name
then the following dgen widget names are generated:
my_name_label my_name my_name_label_2 my_name_2
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:
/columnized "Domain:" | Domain /const "Id:" | Id /const | "Kind:" | Kind /const --------------------------------------------------- /frame "Edit" /edit_toggle "State:" /transition State "Priority:" | Priority | "Assigned:" | Assigned --------------------------------------------------- "Pages:" /page "Description" -style TabBook "Summary:" Summary "Description:" Description --------------------------------------------------- "Pages:" /page "Related Tasks" "Parent:" Parent "Children:" Children "Visit" /button act_visit_task --------------------------------------------------- dlisp: %prog act_visit_task # Visit selected child else visit parent. <set,target,<valw,//children//,selected>> <cond,<eq,<val,target>,>,<set,target,<valw,//parent//>>> <cond,<ne,<val,target>,>, <perform,visit,<val,target>,,,<alias_key>> , # else <msg_dialog,No child selected and no parent to visit.> >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 HistoryIn the tabbed format for this page set, the top level tabs (displayed horizontally) are:
Description
Related Tasks
Version History
Development
Problem Report
Task HistoryWhen the "Development" tab is selected, the following nested tabs appear:
Similarly, when the "Problem Report" tab is selected, the following nested tabs appear:
Problem Report
Background
Symptoms
Test Sequence
Workaround
PatchNested 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 UNIXAs 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:
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_versionsAction Syntax
Actions are specified as part of the widget that invokes the action. For a button, the syntax is
where button_label is the label to appear on the button. For the alternatives icon button of a task field, the syntax is
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_idscript_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 ::= identifierMultiple 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
action_visit (design_document, "/documents")
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".
action_visit (children.selected, parent)
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_visit_task (description.selected)
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.
action_create_task (domain => domain, parent => name, kind => kind)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 ::= 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
where arg_name is the argument name. The value of a named out argument may be set in a script using the command
set arg_name = value
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:
if ( $doc_file == "" ) then set doc_file = $current_doc_file endif
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
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
and may be set using the command
set arg[n] = value
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
if ( $arg[3] == "" ) then set arg[3] = $current_document endif
The number of positional arguments passed to a script can be obtained from the expression:
In addition, positional arguments that are not out arguments may also be referenced using the simpler notation:
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:
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
setarg_name
= value
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
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:
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:
return $status
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":
actions: %script check_out checkout $file return $status %script_end %script check_in checkin $file return $status %script_end
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:
%script check_out if ( ( ! ?$file ) || $file == "" ) then message_box "No file to check out specified" return 1 endif checkout $file return $status %script_end
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:
set alt_items = (Red Yellow Blue)
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:
task t $1 set value = `t.fieldfield_name
`
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.
%prog act_check_in_task
This action program is used to check-in the task displayed by the task editor. The task must already be a controlled object.
%prog act_check_out_task
This action program is used to check-out the task displayed by the task editor. The task must already be a controlled object.
%prog act_new_child
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.
%prog act_visit_task
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.
%prog act_visit_current
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.
%prog act_show_version_image
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.
%prog update_child
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.
%prog add_version %prog remove_version
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.
%prog user_build
This program can contain any user-defined dlisp code to be executed as part of the standard %prog build.
%prog user_setup
This program can contain any user-defined dlisp code to be executed as part of the standard %prog setup.
%prog user_init
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.
%prog user_exec
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:
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
set value = `tk_task_value summary`
whereas in dlisp, a corresponding call is
<set,value,<tk_task_value,summary>>
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_tasklist_popup,task_list
>Retrieves the task list identified by task_list and returns a string representing the tasks in the list. Each task is represented in the string by a single line containing the simple task id and the contents of the Summary field of the task. The command is used to implement popup task menus.
<tk_tasklist_selection>Returns a string containing the full path names of the tasks in the task list specified in the last call to the tk_tasklist_popup command. Each path name occurs on a separate line. This command is used to handle the selection of a task from a popup task menu produced by the tk_tasklist_popup command.
<tk_domain_popup,simple
>Retrieves the APEX_TASK_DOMAIN_PATH environment variable and returns a string representing the domains. Each domain comprises a single line within the string. If simple is true, simplified domain names are returned. If simple is false, the full path names are returned. The command is used to implement popup domain menus.
<tk_set_domain_path,path
>Sets the APEX_TASK_DOMAIN_PATH environment variable in all Apex and Summit server processes to the value path which must be a space-separated list of domain pathnames.
<tk_kind_popup,domain
,simple
>Retrieves the task kind path for domain and returns a string representing the kinds (one per line). If simple is true, simple kind names are returned. If simple is false, the full path names are returned. The command is used to implement popup task kind menus.
<tk_template_popup,domain
,kind
,simple
>Retrieves the task initialization template path for the given task kind and returns a list representing the templates, one per line. If simple is true, simple template names are returned. If simple is false, the full path names are returned. The command is used to implement popup task kind template menus.
<tk_default_domain,simple
>Retrieves the default domain (the first domain in the APEX_TASK_DOMAIN_PATH environment variable). If simple is true, a simple name for the domain is returned. If simple is false, the full pathname is returned.
<tk_default_kind,domain
,simple
>Retrieves the default task kind (the first kind in the task kind path) for domain. If simple is true, a simple name for the default kind is returned. If simple is false, the full pathname is returned.
<tk_default_template,domain
,kind
,simple
>Retrieves the default task initialization template (the first template from the task kind template path) for the task kind. If simple is true, a simple name for the default template is returned. If simple is false, the full pathname is returned.
<tk_task_init,task_id
>Establishes an association between the calling dialog and the task with the given task_id. The task_id must be the full path name of a task. No task information is retrieved by this call, however, a copy of the task's field map held by the dialog is set to empty. All of the other commands beginning with tk_task_ assume that the dialog has already invoked this command.
<tk_task_read>Copies the associated task's field map (the mapping of task field names to their current values) into the calling dialog. The tk_task_init command must be called first to set the task identity. The value true is returned on the first call. On subsequent calls true is returned if any user-editable field of the task has a value different from that held in the dialog's field map. If not, false is returned.
<tk_name,simple
>Returns the name of the task (if any) associated with the calling dialog. If simple is true, the simple task id is returned. Otherwise, the full path name is returned.
<tk_task_value,field
>Returns the value of field in the dialog's copy of the task field map. The empty string is returned if the field is not in the map.
<tk_task_modify,field
,value
>Sets the value of field to value in the dialog's copy of the task field map.
<tk_task_add,field
,value
>Adds value to the given list-type field in the dialog's copy of the task field map. If value is already in the list, the command has no effect.
<tk_task_remove,field
,value
>Removes value from the given list-type field in the dialog's copy of the task field map. If value is not in the list, the command has no effect.
<tk_task_update[,state_field
,new_state
]>Updates the dialog's associated task using the dialog's copy of the task field map. It is assumed that the values of any state machine fields are unchanged in the dialog's field map. If a state field is to be updated, the field name must be passed as state_field and the new value must be passed as new_state. The new state (if any) is assumed to be legal.
This operation updates the values of editable task fields (excluding state machines), if the applicable modify preconditions are successful. The state field (when specified) is updated if the applicable state transition preconditions are successful. The appropriate post–transition and post–modify actions are also invoked.
<tk_task_lock>Attempts to acquire the task edit lock on the associated task and returns true if successful. If the lock is currently held by another process false is returned. The task edit lock is an exclusive lock that is acquired by task editor dialogs when the user modifies a widget representing an editable task field.
<tk_task_unlock>Releases the lock acquired by tk_task_lock. This command has no effect if the lock is not held.
<tk_get_field,task_id
,field
>Returns the current value of field in the task identified by task_id. The operation fails if the task does not exist. The empty string is returned if field does not exist or has no assigned value.
<tk_resolve_task_ids,task_ids
,domain
[,fail]>Resolves a space-separated list of task_ids in the context of domain and returns the corresponding full task pathnames. Relative task names are resolved by lookup in domain and converted to canonical full pathnames. Absolute path names are converted to the canonical form. If any of the task_ids cannot be resolved, they are reported via a message dialog. If fail is specified as the third argument, the operation fails on such an error, thereby aborting the calling dlisp %prog.
<tk_relative_task_ids,task_ids
,domain
[,fail]>Returns the relative pathnames of the given task_ids with respect to domain. The task_ids is assumed to be space-separated list of full pathnames of tasks. If a task id is not in domain, its full path name is returned. In either case, the .task suffix is dropped as well. If fail is specified as the third argument, the operation fails on an error, thereby aborting the calling dlisp %prog.
<tk_version_handle,version
>Returns an Summit/CM version handle given a quoted string (version)containing a pathname, a version history name, and a version number. The pathname must be the name of an object in a view of a subsystem. The string returned contains the pathname of the subsystem, the object name relative to the containing view, the history name, and the version number. This operation is used to convert a version recorded in a task's CmvcVersions field into a form that can be used to display the version's image via the internal command called show_version.
<tk_is_task,task_id
>Returns true if task_id is the pathname of an existing task.
<tk_is_domain,domain
>Returns true if domain is the pathname of an existing view or a subdirectory of a view within a task domain subsystem.
<tk_domain_error,domain
>Returns an appropriate error message if domain is not the pathname of an existing view or a subdirectory of a view within a task domain subsystem.
<tk_is_domain_subsystem,domain
>Returns true if domain is the pathname of an existing task domain subsystem.
<tk_check_field_value,domain,kind,field,value
>Checks if value is a legal value for the specified field. If so, true is returned, otherwise false is returned. The check is performed according to the field's type definition in the task kind specified. For example, a field of type 'enum' must have one of the allowed values specified in the field's definition.
<tk_get_fields_list,domain,kind
>Returns a list of the fields defined for the given task kind.
<tk_field_popup_domain,domain,kind,field,
[state_value
]>Returns a list (one line per entry) of alternative field values for the specified field. The list returned may be used to form an alternatives popup for a field value in a task editor dialog. The optional state_value applies only to a state machine field and must contain a legal state. In this case, the values returned are the legal successor states; however, those which are not permitted by the user's adopted roles are prefixed with an "*" (asterisk). Also see tk_state_popup_domain below.
<tk_state_popup,domain,kind,field,state_value
>Returns a list of possible state transitions (one per line) for the given state machine field. The list returned may be used to set a transition_menu widget for the state field in a task editor dialog. The state_value must contain a legal state. The list returned contains all legal transitions from state_value to other states. Each legal transition is represented by a line of the form:
state_value
->new_state_value
However, the first line in the returned list contains only state_value. Those transitions which are not permitted by the user's adopted roles are prefixed with an "*" (asterisk). This form of list may be passed to the set_option_menu dlisp command; in this case, a leading "*" will cause the option to be insensitive and appear gray (the asterisk does not appear).
<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:
tegen [options
]tegen_file
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:
- tegen_file
If the –example option is used, then this parameter names the task editor generation file to be created from the example. Otherwise, this parameter names the task editor generation file to be used directly to generate the .dlg or .dgen file. The file must have an extension of .tegen, but it need not be explicitly specified.
- options
Specifies that a .dgen file should be generated instead of a .dlg file. The apex_guigen tool must be subsequently applied to create the required .dlg file.
This option implies the -gen_dgen option and also specifies the name of the task editor dialog generation file to be created. The file is created with the extension .dgen, if no extension is specified.
Default value: The file name with the same root name as the tegen_file parameter, but with .dgen as the extension.
Identifies the task editor generation file to use as the example from which the given tegen_file is created. If not specified, then the tegen_file parameter itself, is used as the task editor generation file. The file must have an extension of .tegen, but it need not be explicitly specified.
Names the task kind Fields definition file from which tegen acquires task field name and type information. This information is required.
Indicates how many additional pixels are used to separate tegen label widgets from constant field widgets which precede them on the same row.
Examples:
tegen -example Example bug tegen bug
Apex GuigenCustomized 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 CommandsCustomization 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
TASK_CUSTOMIZATION_KEY:file
...
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 actionpre_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 CustomizationsThis 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
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 actionpre_add_task
Syntax
pre_add_taskrev tasks file history version
Description
Called prior to associating tasks with a version of a controlled object using add_task.
Parameters
- rev
Version control revision number. For more information, see Version Control Customization.
- tasks
Specifies the tasks to be associated. Quotes are used if there is more that one task.
- file
Specifies the object to be associated.
- history
Specifies the history that contains the version.
- version
post_add_task
Syntax
post_add_taskrev tasks file history version
Description
Called after associating tasks with a version of a controlled object using add_task.
Parameters
- rev
Version control revision number. For more information, see Version Control Customization.
- tasks
Specifies the tasks to be associated. Quotes are used if there is more that one task.
- file
Specifies the object to be associated.
- history
Specifies the history that contains the version.
- version
pre_remove_task
Syntax
pre_remove_taskrev tasks file history version
Description
Called before disassociating tasks from a version of a controlled object using remove_task.
Parameters
- rev
Version control revision number. For more information, see Version Control Customization.
- tasks
Specifies the tasks to be disassociated. Quotes are used if there is more that one task.
- file
Specifies the object to be disassociated.
- history
Specifies the history that contains the version.
- version
post_remove_task
Syntax
post_remove_taskrev tasks file history version
Description
Called after disassociating tasks from a version of a controlled object using remove_task.
Parameters
- rev
Version control revision number. For more information, see Version Control Customization.
- tasks
Specifies the tasks to be disassociated. Quotes are used if there is more that one task.
- file
Specifies the object to be disassociated.
- history
Specifies the history that contains the version.
- version
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |