Product | Command type |
---|---|
ClearCase | cleartool subcommand |
ClearCase LT | cleartool subcommand |
Platform |
---|
UNIX |
Windows |
–att·ype attr-type-selector[,...] | –hlt·ype hlink-type-selector[,...] |
–brt·ype branch-type-selector[,...] | –lbt·ype label-type-selector[,...] |
–elt·ype elem-type-selector[,...] | –trt·ype trigger-type-selector[,...] |
–attype attr-type-selector[,...] | or | –att·ype –all |
–brt·ype branch-type-selector[,...] | or | –brt·ype –all |
–elt·ype elem-type-selector[,...] | or | –elt·ype –all |
–hlt·ype hlink-type-selector[,...] | or | –hlt·ype –all |
–lbt·ype label-type-selector[,...] | or | –lbt·ype –all |
–trt·ype trigger-type-selector[,...] | or | –trt·ype –all |
–com·ponent component-selector[,...] (Default: All components) |
–pro·ject project-selector[,...] (Default: All projects) |
–str·eam stream-selector[,...] (Default: All streams) |
Note: –xxxtype aaa,bbb is equivalent to –xxxtype aaa –xxtype bbb.
The mktrtype command creates one or more trigger types for use within a VOB or UCM project VOB. A trigger type defines a sequence of one or more trigger actions to be performed when a specified ClearCase or ClearCase LT operation occurs. The set of operations that initiates each trigger action—that is, causes the trigger to fire—can be very limited (for example, checkout only) or quite general (for example, any operation that modifies an element). You can use a restriction list to further limit the circumstances under which a trigger action is performed.
The trigger types are as follows:
A variant of this type, called an all-element trigger type, is associated with the entire VOB. (Hence, no mktrigger command is required.) In effect, an instance of the type is implicitly attached to each element in the VOB, even those created after this command is executed. This trigger type is useful for disallowing creation of elements that have certain characteristics.
Unlike other types, trigger types cannot be global.
Causing a set of trigger actions to be performed is called firing a trigger. Each trigger action can be either of the following:
Trigger actions execute under the identity of the process that caused the trigger to fire.
A script or batch file executed as (part of) a trigger action can interact with the user. The clearprompt utility is designed for use in such scripts; it can handle several kinds of user interactions through either the command line or GUI.
A single operation can cause any number of triggers to fire. The firing order of such simultaneous triggers is indeterminate. If multiple trigger operations must be executed in a particular order, use a single trigger that defines all operations in order of execution.
It is also possible for triggers to create a chain reaction. For example, a checkin operation fires a trigger that attaches an attribute to the checked-in version; the attach attribute operation, in turn, fires a trigger that sends mail or writes a comment to a file. You can use the CLEARCASE_PPID environment variable to help synchronize multiple firings (for more information, see Trigger Environment Variables).
If a trigger is defined to fire on a hyperlink operation, and the hyperlink connects two elements, the trigger fires twice—once for each end of the hyperlink.
The firing of a trigger can be suppressed when the associated operation is performed by certain identities. Firing of a trigger is suppressed if the trigger type has been made obsolete. (See the lock reference page).
The –execunix and –execwin options allow a single trigger type to have different paths for the same script, or completely different scripts, on UNIX and Windows hosts. When the trigger is fired on UNIX, the command specified with –execunix runs; when the trigger is fired on Windows, the command specified with –execwin runs.
Triggers with only –execunix commands always fail on Windows. Likewise, triggers that only have –execwin commands fail when they fire on UNIX.
The –exec option, whose command will run on both platforms, can be used in combination with the platform-specific options. For example, you can cascade options:
–exec arg1 –execunix arg2 –execwin arg3 –mklabel arg4 ...
A preoperation trigger (–preop option) fires before the corresponding operation begins. The one or more actions you've specified take place in their order on the command line.
This type of trigger is useful for enforcing policies:
For example, a preoperation trigger can prohibit checkin of an element that fails to pass a code-quality test.
A postoperation trigger (–postop option) fires after completion of the corresponding operation. The one or more actions you've specified take place in their order on the command line. This kind of trigger is useful for recording—in the VOB or UCM project VOB, or outside them—the occurrence of the operation. If a postoperation trigger action returns a nonzero exit status, a failed exit status warning message is printed, but other trigger actions, if any, are executed.
For example, a postoperation trigger on checkin attaches an attribute to the checked-in version and sends a mail message to interested users and/or managers.
You can define an element trigger type or UCM trigger type (but not a type trigger type) with a restriction list. The restriction list limits the scope of the operation specified with –preop or –postop. The trigger fires only if the operation involves particular type objects.
A type trigger type is not associated with an element or UCM object, but with one or more type objects. When creating a type trigger type, you must specify an inclusion list, naming the type objects to be associated with the new trigger type. (Hence, it is unnecessary to use mktrigger to create the association.) The special keyword –all allows you to associate a type trigger type with every type object of a particular kind (for example, all branch type objects), even those objects created after you enter this command.
When a trigger fires, the trigger action executes in a special environment whose EVs make information available to –exec, –execunix, and –execwin routines: what operation caused the trigger to fire, what object was involved in the operation, and so on. The complete set of EVs is listed in Trigger Operations and Trigger Environment Variables.
For each object processed, you must be one of the following: type owner (applies to –replace only), VOB owner (element trigger types), project VOB owner (UCM trigger types) or:
An error occurs if one or more of these objects are locked: the VOB (for an element trigger type), the project VOB (for a UCM trigger type), the trigger type (applies to –replace only).
(Replicated VOBs only) No mastership restrictions.
See the permissions reference page.
If you specify a comment when using –replace, the comment appears in the event record for the modification (displayed with lshistory –minor); it does not replace the object's creation comment (displayed with describe). To change an object's creation comment, use chevent.
If an instance of an element or UCM trigger type is currently attached to any object, the replacement definition must correspond in kind: the new definition must be of an element trigger type or a UCM trigger type (but not an all-element or all-UCM object trigger type). You can remove an existing trigger type and all of its attached instances using the rmtype command.
ClearCase and ClearCase LT on Windows—If you do not run mktrtype from the cleartool prompt, enclose command—and any single quotes—in double quotes (" ' command ' "). (See also the cleartool reference page.)
If you invoke a command built in to the Windows shell (for example, cd, del, dir, or copy), you must invoke the shell with cmd /c. For example:
–exec 'cmd /c copy %CLEARCASE_PN% %HOME%'
Note: On UNIX, If you use –execwin when defining a trigger type, you must escape backslashes in command with a backslash. Also, if you invoke a command built in to the Windows shell (for example, cd, del, dir, or copy), you must invoke the shell with cmd /c. For example:
–execwin 'cmd /c copy %CLEARCASE_PN% %HOME%'
type-name | Name of the
label type See the cleartool reference page for rules about composing names. | |
vob-selector | VOB specifier. Specify vob-selector in the form [vob:]pname-in-vob | |
pname-in-vob | Pathname of the VOB tag (whether or not the VOB is mounted) or of any file system object within the VOB (if the VOB is mounted) |
type-name | Name of the
attribute type See the cleartool reference page for rules about composing names. | |
vob-selector | VOB specifier. Specify vob-selector in the form [vob:]pname-in-vob | |
pname-in-vob | Pathname of the VOB tag (whether or not the VOB is mounted) or of any file system object within the VOB (if the VOB is mounted) |
type-name | Name of the
hyperlink type See the cleartool reference page for rules about composing names. | |
vob-selector | VOB specifier Specify vob-selector in the form [vob:]pname-in-vob | |
pname-in-vob | Pathname of the VOB tag (whether or not the VOB is mounted) or of any file system object within the VOB (if the VOB is mounted) |
type-name | Name of the
hyperlink type See the cleartool reference page for rules about composing names. | |
vob-selector | VOB specifier Specify vob-selector in the form [vob:]pname-in-vob | |
pname-in-vob | Pathname of the VOB tag (whether or not the VOB is mounted) or of any file system object within the VOB (if the VOB is mounted) |
Note: With the built-in actions –mklabel, –mkattr, and –mkhlink, you can specify the information either literally or using environment variables:
–mklabel RLS_2.3 | Literal |
–mklabel RLS_$RLSNUM | Depends on value of EV at trigger firing time |
–mklabel %THIS_RLS% | Depends on value of EV at trigger firing time |
–mkattr ECO=437 | Literal |
–mkattr ECO=$ECONUM | Depends on value of EV at trigger firing time |
The built-in actions never cause additional triggers to fire. However, scripts or other programs invoked with –exec may cause such chain reactions. For example, a mklabel command in a shell script can cause another trigger to fire, but the corresponding –mklabel trigger action cannot.
Repeated options, such as –elt text_file –elt c_source, are equivalent to a single option: –elt text_file,c_source. Wildcarding ( –eltype ‘*file' ) is not supported.
At trigger-firing time, the items on the restriction list form a logical condition. If the condition is met, the trigger fires.
Specify the type-selector arguments in the form [type-kind:]type-name[@vob-selector]
type-kind | One of |
|
type-name | Name of the type object | |
vob-selector | VOB specifier Specify vob-selector in the form [vob:]pname-in-vob | |
pname-in-vob | Pathname of the VOB tag (whether or not the VOB is mounted) or of any file system object within the VOB (if the VOB is mounted) |
Note: Suppressing the firing of a preoperation trigger allows the operation to proceed.
Here is a simple condition:
–brtype rel2_bugfix | Fire the trigger only if the operation involves a branch of type rel2_bugfix. |
If the list includes multiple type objects, they are combined into a compound condition: type objects of the same kind are grouped with logical OR; objects (or groups) of different kinds are then logically ANDed.
–brtype rel2_bugfix –eltype text_file,c_source | Fire the trigger only if the operation involves a branch of type rel2_bugfix AND it involves either an element of type text_file OR of an element of type c_source. |
In forming the condition, a type object is ignored if it could not possibly be affected by the operation. (The relevant information is included in the Trigger Operations and Trigger Environment Variables section.) For example, the restriction list –lbtype REL2,REL2.01 applies only to the operations chtype, mklabel, and rmlabel.
component-selector is of the form [component:]component-name[@vob-selector], where vob-selector specifies the component's project VOB.
project-selector is of the form [project:]project-name[@vob-selector], where vob-selector specifies the project's project VOB.
stream-selector is of the form [stream:]stream-name[@vob-selector], where vob-selector specifies the stream's project VOB.
type-name | Name of the
trigger type. See the cleartool reference page for rules about composing names. | |
vob-selector | VOB specifier Specify vob-selector in the form [vob:]pname-in-vob | |
pname-in-vob | Pathname of the VOB tag (whether or not the VOB or project VOB is mounted) or of any file system object within the VOB or project VOB (if the VOB is mounted) |
The following list shows the operation keywords (opkind) for use in definitions of type trigger types (mktrtype –type). In UNIX, the operation fires a trigger only if the affected object is a type object specified on the inclusion list, which is required.
Note: These operations are not ClearCase or ClearCase LT commands, although some have the same names as cleartool subcommands. These are lower-level operations, similar to function calls. See the events_ccase reference page for a list of which commands cause which operations.
MODIFY_TYPE |
chevent |
chmaster |
lock |
mkattr |
mkattr |
mkhlink |
mktype (see Note) |
modtype (see Note) |
rmattr |
rmhlink |
rmtype |
rntype |
unlock |
Note: If you specify mktype, the corresponding inclusion list cannot specify individual type objects; all relevant options must use the –all keyword. For example:
The modtype operation fires on the redefinition of attribute, branch, element, hyperlink, label, and trigger types.
Table 10 lists the operation keywords (opkind) for use in definitions of element and all-element trigger types (–element and –element –all). For any opkind, not all restrictions specified in the restriction-list argument are especially relevant; Table 10also shows which restrictions are checked for each opkind. The opkinds in capitals (such as MODIFY_ELEM) specify all opkinds that appear under them; in other words, they are generalizations of the more specific opkinds.
See also the events_ccase reference page.
Note: These operations are not ClearCase or ClearCase LT commands, although some have the same names as cleartool subcommands. These are lower-level operations, similar to function calls. See the events_ccase reference page for a list of which commands cause which operations.
Table 10. Element Trigger Definition Operation Keywords
Operation keyword | Restrictions checked when trigger fires |
---|---|
MODIFY_ELEM | |
checkout | Element type, branch type |
chevent | See NOTE at end of table |
reserve | Element type, branch type |
uncheckout | Element type, branch type |
unreserve | Element type, branch type |
MODIFY_DATA | |
checkin | Element type, branch type |
chtype | All type objects |
lnname | Element type, branch type |
lock | See NOTE at end of table |
mkbranch | Element type, branch type |
mkelem | Element type |
mkslink | N/A |
protect | See NOTE at end of table |
rmbranch | Element type, branch type |
rmelem | Element type |
rmname | N/A |
rmver | Element type, branch type |
unlock | See NOTE at end of table |
MODIFY_MD | |
chmaster | See NOTE at end of table |
mkattr | Element type, attribute type, branch type |
mkhlink | Element type, hyperlink type, branch type |
mklabel | Element type, label type, branch type |
mktrigger | Element type, trigger type |
rmattr | Element type, attribute type, branch type |
rmhlink | Element type, hyperlink type, branch type |
rmlabel | Element type, label type |
rmtrigger | Element type, trigger type |
Note: The operation fires a trigger only if the affected object is one of the following:
Table 11 lists the operation keywords (opkind) for use in definitions of UCM object and all-UCM-object trigger types (–ucmobject and –ucmobject –all). The table shows the kind of UCM object to which the trigger may be attached—you may also use –all to specify all UCM objects. For any UCM operation, not all restrictions specified in the restriction-list argument are especially relevant; Table 11 also shows which restrictions are checked for each operation. You can use the UCM operation as a synonym for all other UCM operations; it causes a trigger to fire when any UCM operation for which triggers are enabled occurs.
Note: These operations are not ClearCase or ClearCase LT commands, although some have the same names as cleartool subcommands. These are lower-level operations, similar to function calls.
Table 11. UCM Object Trigger Definition Operation Keywords
Operation keyword | Object type | Restrictions checked when trigger fires |
---|---|---|
UCM | ||
deliver_start | Target (integration) stream | Stream, Project |
deliver_cancel | Target (integration) stream | Stream, Project |
deliver_complete | Target (integration) stream | Stream, Project |
rebase_start | Target (development) stream | Stream, Project |
rebase_cancel | Target (development) stream | Stream, Project |
rebase_complete | Target (development) stream | Stream, Project |
mkactivity | Stream that is to contain the activity | Stream, Project |
chactivity | Activity being changed | Stream, Project |
rmactivity | Activity being removed | Stream, Project |
setactivity | Activity being set | Stream, Project |
mkstream | Project that is to contain the stream | Project |
chstream | Stream being changed | Stream, Project |
rmstream | Stream being removed | Stream, Project |
mkbl | Component that is to contain the baseline | Stream, Component, Project. If imported, triggers fire but the environment variables CLEARCASE_STREAM and CLEARCASE_PROJECT are undefined. |
mkbl_complete | Stream where the baselines are to be created | Stream, Component, Project. Fires when all baselines that need to be created in the stream have been created. Does not apply to imported baselines |
chbl | Component that contains the baseline | Component, Project |
rmbl | Component that contains the baseline | Component, Project |
mkproject | The entire project VOB | None |
chproject | Project being changed | Project |
rmproject | Project being removed | Project |
mkcomp | The entire project VOB | None |
rmcomp | The entire project VOB | None |
mkfolder | Folder that is to contain the folder | Project |
chfolder | Folder that contains the folder | Project |
rmfolder | Folder that contains the folder | Project |
setplevel (at 5.0) | The entire project VOB | None |
The following list shows the EVs that are set in the environment in which a trigger action script runs. The words in parentheses at the beginning of the description indicate which operations cause the EV to be set to a significant string; for all other operations, the EV is set to the null string. (See the events_ccase reference page for a list of which commands cause which operations.)
When the command chmaster –default brtype:branch-type-name is run at the site of the replica that masters the branch type, CLEARCASE_FREPLICA is set to the name of the current replica. If the command is run at a site that does not master the branch type, the command fails, but CLEARCASE_FREPLICA is set to the name of the replica that masters the branch type.
When the command chmaster –default branch-name is run, CLEARCASE_FREPLICA is set to the name of the current replica. (If the command is run at a site that does not master the branch, it fails.)
For mkattr, mkhlink, rmattr, rmhlink type triggers, CLEARCASE_MTYPE specifies the metatype of the type being modified, not the metatype of the attribute or hyperlink.
Commands that cause multiple operations | Operations | CLEARCASE_POP_KIND value |
---|---|---|
mkelem | mkelem lnname | mkelem mkelem |
ln –s | mkslink lnname | mkslink mkslink |
move | mv | lnname rmname | rmname lnname |
deliver_start | mkactivity setactivity mkbl | deliver_start |
rebase_start | mkactivity setactivity mkbl | rebase_start |
The move or mv command is a special case because there is no move operation. Therefore, the CLEARCASE_POP_KIND environment variable is set to the values rmname and lnname to show that those operations were part of the command execution.
When the command chmaster –default brtype:branch-type-name is run at the site of the replica that masters the branch type, CLEARCASE_TREPLICA is set to the name of the current replica. If the command is run at a site that does not master the branch type, the command fails, but CLEARCASE_TREPLICA is set to the name of the current replica.
When the command chmaster –default branch-name is run, CLEARCASE_TREPLICA is set to the name of the replica that masters the branch type. (If the command is run at a site that does not master the branch, it fails.)
A combination of the CLEARCASE_VOB_PN and CLEARCASE_PN environment variables can be used to extract the VOB-only pathname. Because the CLEARCASE_VOB_PN variable contains the VOB tag, it can be used to determine where the VOB part of a pathname begins in CLEARCASE_PN.
The UNIX examples in this section are written for use in csh. If you use another shell, you may need to use different quoting and escaping conventions.
The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.
In cleartool single-command mode, cmd-context represents the UNIX shell or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.
Note: Trigger environment variables are typically evaluated when the trigger fires, not when you enter the mktrtype command. If this is the case, escape the $ (UNIX) or % (Windows) environment variable symbol according to the conventions of the shell you are using. Escaping is not necessary if you enter the command manually in cleartool's interactive mode (that is, if it is not interpreted by a shell).
cmd-context mkeltype -supertype text_file -c "shell script" script
Created element type "script".
cmd-context mktrtype -element -all -postop mkelem -eltype script -nc \
-exec '/opt/rational/bin/cleartool protect -chmod a+x $CLEARCASE_PN'\
chmod_a_plus_x
Created trigger type "chmod_a_plus_x".
cmd-context mkelem -eltype script -ci -nc cleanup.sh
Created element "cleanup.sh" (type "script").
Changed protection on "/usr/hw/src/cleanup.sh".
Checked in "cleanup.sh" version "/main/1".
cmd-context mktrtype -element -all -nc -preop mkelem ^
-exec ‘\\photon\triggers\check_ext %CLEARCASE_PN%' check_ext
Created trigger type “check_ext”.
cmd-context mktrtype -element -all -postop checkin -nc \
-exec /opt/rational/bin/notify notify_admin
Created trigger type "notify_admin".
notify script:
mail jones adm <<! "notify_admin" Trigger: checkin of "$CLEARCASE_PN" version: $CLEARCASE_ID_STR by: $CLEARCASE_USER comment: $CLEARCASE_COMMENT !
cmd-context mktrtype –element –postop mkbranch –nc ^
–execunix /net/neon/scripts/branch_log.sh ^
–execwin \\photon\triggers\branch_log.bat branch_log
Created trigger type "branch_log".
cmd-context mktrtype -element -all -nc -preop checkin \
-exec '/net/neon/scripts/metrics_test $CLEARCASE_PN' \
-eltype c_source metrics_trigger
Created trigger type "metrics_trigger".
cmd-context mktrtype -element -all -postop checkin -mklabel REL\$BL_NUM \
-nc -brtype main label_i
Created trigger type "label_it".
Environment variable BL_NUM determines which version label is to be attached. This EV is evaluated at trigger firing time, because the dollar sign ($) is escaped.
cmd-context mktrtype -type -nc -postop mktype -brtype -all \
-exec /net/neon/scripts/mail_admin new_branch_trigger
Created trigger type "new_branch_trigger".
cmd-context mktrtype -type -nc -preop mktype -lbtype -all
-exec '\\photon\triggers\check_label_name' ^
check_label_trigger
Created trigger type "check_label_trigger".
Note: In this example, the single quotes preserve the double quotes on the string literal, and suppress environment variable substitution by the shell. The CLEARCASE_USER environment variable is evaluated at firing time.
cmd-context mktrtype -element -postop checkin \
-c "set attribute to record which user checked in this version" \
-mkattr 'TestedBy="$CLEARCASE_USER"' trig_who_didit
Created trigger type "trig_who_didit".
cmd-context mktrtype -element -all -nc -postop mkelem -eltype c_source \
-exec /net/neon/scripts/hlink_algorithm describe_algorithm
Created trigger type "describe_algorithm".
hlink_algorithm script:
clearprompt text -outfile /usr/tmp/alg.$CLEARCASE_PPID \ -multi_line -def "Internal Design" -prompt "Algorithm Source Document:" TOTEXT=‘cat /usr/tmp/alg.$CLEARCASE_PPID‘ cleartool mkhlink -ttext "$TOTEXT" design_spec $CLEARCASE_PN$CLEARCASE_XN_SFX rm /usr/tmp/alg.$CLEARCASE_PPID
cmd-context mktrtype -element -all -nc -postop checkin -eltype header_file \
-exec '/usr/local/scripts/hdr_comment' change_header_file_comment
Created trigger type "change_header_file_comment".
hdr_comment script:
# analyze change to header file CMNT=‘/usr/local/bin/analyze_hdr_file $CLEARCASE_PN‘ # append analysis to user-supplied checkin comment cleartool chevent -append -c "$CMNT" $CLEARCASE_PN‘
cleartool mktrtype –element –all –preop chmaster –nusers stephen,hugh,emma ^
–execunix "Perl –e \"exit –1;\"" –execwin "ccperl –e \"exit (–1);\"" ^
–c "ACL for chmaster" elem_chmaster_ACL
cleartool mktrtype –type –preop chmaster –nusers stephen,hugh,emma ^
–execunix "Perl –e \"exit –1;\"" –execwin "ccperl –e \"exit (–1);\"" ^
–attype –all –brtype –all –eltype –all –lbtype –all –hltype –all ^
–c "ACL for chmaster" type_chmaster_ACL
cmd-context mktrtype -ucmobject -all -preop deliver_start $PREOPCMDU
$PREOPCMDW -stream $STREAM -nc $PREOPTRTYPE
cmd-context mktrtype -ucmobject -all -postop deliver_complete $WCMD $UCMD
-stream $STREAM -nc $TRTYPE
Copyright© 2003 Rational Software. All Rights Reserved.