Attaching scripts to buttons

Perhaps the single greatest opportunity for customization of Razor lies in the ability to attach shell scripts to run both before and after many of the actions. Scripts which run before Razor performs an action have the ability to veto the pending action by returning a non-zero exit code.

Versions & threads

There are dozens of unique locations where scripts can be attached to the actions of the versions and threads operations. These extensions are enabled by editing the Actions file in the related Tables directory. Each line in the file represents a different button on the related interface to which scripts can be attached.

The following two tables show not only where scripts can be attached, but also what arguments will be passed to the scripts when they are executed.

Buttons for the file operations

Button	When	$1	$2	$3	$4	$5
branch	Before	filename	orig version
	After	filename	new version
checkin.apply	Before	filename	orig version	fullpath	flag
	After	filename	new version	dirname	flag
checkout.apply	Before	filename	version	fullpath
	After	filename	version	dirname
double_click1	Before	filename	version	incl version2	flag3
	After4
file_props.apply	Before	filename	version
	After	filename	version
introduce.apply	Before	filename	version (1.1)	fullpath	flag	bflg5
	After	filename	version (1.1)	dirname	flag
merge_checkin.apply6	Before	filename	orig version	fullpath
	After	filename	new version
new_folder	Before	foldername
	After	foldername
promote.apply	Before	filename	version	new state
	After	filename	version	new state
readonly.apply7	Before	filename	version	fullpath
	After	filename	version	dirname
remove	Before	filename
	After	filename
remove_folder	Before	folder
	After	folder
rename	Before	filename	new name
	After	new name	orig name
terminate	Before	filename	version
	After	filename	version
uncheckout	Before	filename	orig version	button8
	After	filename	version	dir | "N/A"	flag
utilities.revert	Before	filename	orig version
	After	filename	new version

1 The double_click action in a versions Action file is not invoked from the versions tools but only from the threads tool. It is invoked from the threads tool only when the user double_clicks on a file in the Thread Edit dialog box. 2 The possible values for double_click.Before, parameter $3 are either "NONE" or the included version 3 The possible values for double_click.Before, parameter $4 are 0 if file is excluded, 1 if file is included 4 double_click.After is ignored 5 Binary flag, possible values are 0 if file is NOT binary, 1 if it is 6 If a before/after script is attached to checkin.apply, you may wish to call the referenced script from the before/after script attached to merge_checkin.apply as well. 7 This action is honored for file operations within the threads program, specifically file extraction. 8 The possible values for uncheckout.Before, parameter $3 are 0 if user selected "Okay", 1 if user selected "Readonly"

Buttons for threads operations

Button	When	$1	$2	$3
extract_project.apply	Before	threadname	version	dirname
	After	threadname	version	dirname
extract_thread.apply	Before	threadname	version	dirname
	After	threadname	version	dirname
project_create.apply	Before	threadname	version
	After	threadname	version
project_modify. apply	Before	threadname	version
	After	threadname	version
remove	Before	threadname
	After	threadname
thread_create.apply	Before	threadname	version(1.1)
	After	threadname	version(1.1)
thread_modify.apply	Before	threadname	version	fullpath
	After	threadname	new version

In the tables above, the first argument supplied to the script is always the name of the file or thread itself. The second argument is the affected version number of the related file or thread. Note that in some cases, the before and after scripts will be provided different version numbers. Specifically, in the versions program, the checkin.apply before script is told the original version number, and the after script is told the version number of what the check-in effort produced.

The third and fourth arguments to the scripts are optional, and vary in purpose. In the above table, "fullpath" indicates that $3 is the full path name to where the file is coming from or going to. The term "dirname" is simply the directory part of "fullpath".

Both the introduce and check-in operations of the versions program provide the related after script a fourth argument. This flag indicates whether or not an imbedded operation took place, i.e.

0 - files were taken during the operation
1 - readonly copies of the files were left behind
2 - the files were immediately checked back out again

Note that for cases 1 and 2 above, the associated before and after scripts for the check-out readonly or check-out operation are also performed. For example, if someone introduced a file and arranged such that a readonly copy be left behind, the following sequence of scripts will be executed...

introduce.apply before script
readonly.apply before script¹
readonly.apply after script
introduce.apply after script

For the uncheck-out operation, the attached scripts are passed the version number that the file would have gone to, if the edits had been completed by a check-in. Also note that the uncheck-out operation allows the user the option of leaving readonly copies of the files behind. If this is chosen, then the related readonly.apply scripts will be run, and the 3rd argument to the uncheck-out after script will have the directory the readonly copy was placed into (otherwise $3 would be "N/A").

Programming tip: If an introduce.apply script returns the special non-zero exit value of 99, the versions program will skip the file being introduced and not generate an error message/dialog. This could be very useful in cases where directories are being introduced. For example, it may be desirable to skip all compressed files, object files and executables.

In addition to the information available to the scripts via the command line, they are also provided a number of shell environment variables, as outlined below:

Environment Variable	Definition
RAZOR_UNIVERSE_DIR RAZOR_HOME	These are as you'd expect, and are actually set by the original reference to the rz_prep file for the database.
RAZOR_DOMAIN RAZOR_GROUP RAZOR_FILE	These three combine to provide increasing granularity towards where the file is with respect to the Razor database.
RAZOR_INFO_FILE	(for versions introduce.apply before scripts only) This points to a temporary file containing a review copy of attribute information set on the introduce panel.
RAZOR_ATTR_FILE	(for versions introduce.apply before scripts only) Outputting a tab separated list of Attribute/Value pairs to the this file allows scripts to override selections made by users (except STATES). Creating the file $RAZOR_TMP/RAZOR_BINARY.$RAZOR_PID will cause the file to be introduced as a BINARY file. Razor will remove this temporary file for the user.
RAZOR_ISSUES	If the related activity was associated with one or more issues, this environment variable will contain a space separated collection of the issue numbers.
RAZOR_PID	This is the process id of the Razor program which the user was running.
RAZOR_INCREMENT_ RELEASE	Used for versions check-in and threads save actions this will be set to "1" when the Increment release number checkbox is selected.
RAZOR_TITLE	Where appropriate, this will be set to the text entered by the user for check-in, check-out, branch and revert functions.
RAZOR_ACTION	This variable is set to indicate why the script was called, and is formatted as either <operation>_BEFORE or <operation>_AFTER.

The <operation> part of the setting of RAZOR_ACTION is based on both which program was involved, and the action the user selected, as shown below...

• For the versions program, <operation> could be: BRANCH, BUMP, CHECKIN, CHECKOUT, DUP, INTRODUCE, PROMOTE, PROPS, READONLY, REMOVE, RENAME, SAVE, or UNCHECKOUT.
• For the threads program, <operation> could be DOUBLE_CLICK, EXTRACT_FILE, EXTRACT_THREAD, EXTRACT_PROJECT, THREAD_CREATE, THREAD_MODIFY, PROJECT_CREATE, or PROJECT_MODIFY.
• For the issues program, <operation> could be either ISSUE_CREATE or ISSUE_MODIFY.
• For command line, <operation> is set to BRANCH, BUMP, DUP, INTRODUCE, PROMOTE, SAVE, REMOVE, CHECKOUT, CHECKIN, UNCHECKOUT, READONLY

Whether or not a before or after script takes advantage of all this information is a completely different story.

Let's look at a quick example to illustrate some of the above concepts. Suppose that the user dick was a junior engineer, and was not to be given the same level of trust or latitude as the rest of the engineers. Specifically, when checking out a file for edit, he must associate the activity with one or more issues in the database. The following script, when attached as a checkout.apply before action, will do the necessary screening.

#!/bin/sh
if [ $USER = "dick" -a "$RAZOR_ISSUES" = "" ] ; then
          echo "Sorry Dick... Please associate this action "
          echo "with one or more issues from the Razor database."
          exit 1
else
          exit 0
fi

Execution order for attached scripts

It should be remembered that if multiple files are being acted upon, the attached scripts will be executed for each file selected. In other words, if the user is checking out 3 files for edit in one operation, the related before and after scripts will be invoked 3 times each; once for each file. For example, if a user were checking out the three files "apple", "grape", and "peach", then (if attached) the following sequence would occur...

- run before.apply script for apple
<Razor would process apple, and update database>
run after.apply script for apple
- run before.apply script for grape
<Razor would process grape, and update database>
run after.apply script for grape
- run before.apply script for peach
<Razor would process peach, and update database>
run after.apply script for peach

This pattern of `run before script - do processing - run after script' holds true for all of the multi-file operations with one exception; introducing files. In this case, if we were introducing the files "barney", "fred", and "wilma", then the sequence would be...

- run before.apply script for barney
run before.apply script for fred
run before.apply script for wilma
- <Razor would process barney, fred, and wilma, and update database>
- run after.apply script for barney
run after.apply script for fred
run after.apply script for wilma

Issues

As with the versions and threads programs, scripts can be attached to run both before and after edits are done to the issues database.

The same on-screen form is used for both the creation and modification of issue information. It's occasionally useful though to treat the two events differently. The arguments supplied to the scripts are shown in the following table.²

Buttons for issues operations

Button	When	$1	$2
issue_create.apply	Before	filename	e-mail addrs
	After	filename	e-mail addrs
issue_modify.apply	Before	filename	e-mail addrs
	After	filename	e-mail addrs
remove	Before	filename
	After	filename
preload	Before
	After

The filename points to a readonly copy of an ASCII file containing all of the information on the issue form. The file resides in RAZOR_TMP, and will have a name that is the concatenation of the issue number and the process id of the issues program itself. Please note that this file has been generated and provided to the scripts for information only. Any changes made to the file by the script are ignored.

The second argument provided to the issue_create.apply and issue_modify.apply scripts is a space separated list of e-mail addresses that will be notified. This list comes straight from the related state change in the Permissions file, and is again provided for the sake of completeness.

Also, as outlined in the table on page 239, scripts attached to buttons in the Razor program are provided a number of environment variables which give extra information.

As with scripts attached to buttons in the versions or threads programs, the before script has the ability to veto the pending razor operation by returning a non-zero return code. For example, if we wish to prevent the user `joe' from creating an issue with the Priority field set to High, we could attach the following script as the create.apply before action.

#!/bin/sh
N=`egrep -c "ATTR.*Priority.*High" $1`
if [ $N -gt 0 -a "$USER" = "joe" ] ; then
    echo "Sorry, but you're not allowed to set"
    echo "an issue to be high priority."
    exit 1
else
    exit 0
fi

If Joe were to try and create such an issue, the output from the script will be captured and shown to him.

¹ Note that in this special flow of events, the nested `before' script would no longer have its normal ability to veto the action.
² For a discussion of the preload entry, see the section "Pre-loading an issues form" on page 246.