Using rz_toolbox

The file rz_toolbox is a collection of Bourne/Korn shell subroutines, similar to those previous discussed in rz_utils, which provide a higher level of granularity in interacting with the Razor database. These routines are generally less efficient than the corresponding rz_utils functions, but do provide a more detailed level of granularity.

rz_toolbox is a collection of Bourne/Korn shell subroutines which greatly simplifies the task of interacting with the Razor database. It virtually eliminates the need for you to directly parse the various directories and info files, providing a wide variety of functions.

You are in no way restricted or confined to use rz_toolbox; you are always free to parse the database yourself. In fact, if you have a specific set of things you are looking to accomplish and are adept at writing scripts, you may be able to write a very precise and efficient script on your own. Also, since rz_toolbox is a Bourne/Korn shell tool, you will not have the option of taking advantage of it if you are using the C shell (or TCL, or Perl, etc.).

To use rz_toolbox, your Bourne/Korn shell script will need to "dot" in the file. This is analogous to a #include in C programming, or using the source command in the C shell. For example, a typical script may begin as follows...

#!/bin/sh
. $RAZOR_HOME/scripts/rz_toolbox
#...continue on from here...

In order to take advantage of any of the rz_toolbox functions, the environment variables RAZOR_HOME and RAZOR_UNIVERSE_DIR must be set. This may already have been handled by previous reference to the appropriate rz_prep file, or they could directly be set through in-line reference in the script itself.

Once properly set, you'll be able to take advantage of the functions described below, much as you would a normal UNIX program. The descriptions are broken out into three broad categories. The code samples are shown assuming that the lead in shown above has already occurred.

Utility routines

razor_groups

This function sets the environment variable RAZOR_GROUPS to contain a space separated list of all the groups within the indicated RAZOR_UNIVERSE_DIR.

The following code sample will do a simple loop, printing out the names of all the known groups.

#!/bin/sh
. $RAZOR_HOME/scripts/rz_toolbox
razor_groups
for g in $RAZOR_GROUPS ; do
    echo "Group name = $g"
done

razor_files [-o]

This function generates a space separated list of all the files under control within a single Razor group. With the -o option, the list is sent to standard out, otherwise the environment variable RAZOR_FILES is set to the list. The environment variable RAZOR_GROUP must be set to indicate the group of interest prior to calling the function.

Optionally, you can set the environment variable RAZOR_PATTERN to hold a UNIX wildcard expression. If set, it will be used to filter specific files.

The following code sample will print out the names of all files within the "fruit" group which have the characters "xy" in their names.

#!/bin/sh
. $RAZOR_HOME/scripts/rz_toolbox
RAZOR_GROUP=fruit
RAZOR_PATTERN='*xy*'
razor_files
for f in $RAZOR_FILES ; do
    echo "---- $f"
done

TIP: Remember that issues in the problem tracking system are also stored as separate files. The default issues group is named "++ISSUES++". Additional issues groups are named "++ISSUES++.<issue_group>". Knowing this, you can set the RAZOR_GROUP accordingly and use the above function to traverse issues!

razor_folders [-o]

This function generates a space-separated list of all folders within the current group. With the -o option, the list is sent to standard out, otherwise the environment variable $RAZOR_FOLDERS is set to the list. The environment variable RAZOR_GROUP must be set to indicate the current group prior to calling the function. Optionally, you can set the environment variable $RAZOR_PATTERN to hold a UNIX wild card expression. If set, it will be used to filter specific folders.

razor_issue_num

This is a simple courtesy function which will take a single integer argument and reshape it into a Razor style issue number. The output is placed in the environment variable $RAZOR_ISSUE_NUM for subsequent use. For example, the lines...

razor_issue_num 1234
echo $RAZOR_ISSUE_NUM

... will output the string "I..1-234".

NOTE: The prefix defined in the file $RAZOR_UNIVERSE_DIR/DOMAIN_01/<issue group>/Tables/Prefix will be honored.

check_server_down

This function tells you whether the database specified by environment variable $RAZOR_UNIVERSE_DIR is being served. A return of 0 indicates the database is being served, 1 means it isn't.

Parsing for attributes

razor_learn <filename>

If the environment variable $RAZOR_GROUP is set to the name of the group you are interested in, this function will take the filename supplied by the single argument and parse the related Info file. The end result will be a large collection of new and specially named environment variables which tell everything there is to know about the file in question.

The function returns all of its information through a collection of environment variables which can subsequently be queried by the script. The following table describes the variables which will always be generated.

Environment variable	Definition & usage
RAZOR_INFO_FILE RAZOR_HISTORY_FILE RAZOR_VCS_FILE	These three variables provide the full path names to where the corresponding Info, History and SCCS/RCS files can be found.
RAZOR_VERSION	The latest version number for the file.
RAZOR_TIME_CHECKED_IN	A timestamp indicating when the file was last modified.
RAZOR_MOD_TIME	A timestamp indicating when attributes about the file were last modified.1 For issues, this will always equal the RAZOR_TIME_CHECKED_IN, but it could be a more recent time for files under version control.
RAZOR_IS_A_BRANCH	Set to 1 if the named file is a branch. This will always be 0 for issues and threads.
RAZOR_BINARY	Set to 1 if the file has been declared to be binary. This will always be 0 for issues and threads.
RAZOR_IS_TERMINATED	Relevant only if the file is a branch, this will be set to 1 if the branch has been terminated. Always 0 for issues and threads.
RAZOR_CHECKED_OUT	Set to 1 if the file is presently checked out. This should always be 0 for issues and threads.
RAZOR_OWNER	If the file is checked out, this contains the userid of who has the file.
RAZOR_NUM_BRANCHES	This indicates how many non-terminated branches exist for this file.
RAZOR_NUM_STATES	For files under control, it indicates the number of states that have actually been assigned to this file so far. For issues, it indicates the index of the state the issue is presently at.
RAZOR_STATES	For files, this is a space separated list of "state:version" pairs, indicating when the file last achieved each of the assigned states. For issues, the version number is replaced with a timestamp indicating when the issues last transitioned to that state.
RAZOR_ATTR	This is a space separated list of all the possible attribute labels.

1 Modified via BRANCH, FILE_PROP, REMOVE, RENAME, or REVERT.

The razor_learn function will yield all of the environment variables described below regardless of the nature of the corresponding Attributes file in use. Additionally, a collection of group-specific variables will be created with names that correspond with the various attribute labels.

For example, if there were attributes with the labels "Filetype" and "Library", then the razor_learn function would generate the environment variables "RAZOR_Filetype" and "RAZOR_Library" to hold their values. Other than the "RAZOR_" prefix, the spelling and capitalization of the labels will remain the same. Space and punctuation within the label name itself will of course be translated to underscores.

TIP: An example showing the usage of razor_learn, as well as some of the other functions defined in the rz_toolbox, may be found in the script $RAZOR_HOME/examples/sample_toolbox_usage.

The exit status of the razor_learn function returns a 0 if there were no problems. Otherwise, error messages will be sent to the standard output, and you will be returned a non-zero exit status, which can be sensed by the "$?" environment variable.

The razor_learn function is perhaps the most powerful in the collection supplied by rz_toolbox. In many cases you can write a few lines of shell script which can be used to extract the specific information you are looking for in a much more efficient manner.

For example, if the only information you need is the setting of the `Author' ONE_OF_MANY, then the following lines of shell script will run much more quickly than the razor_learn function...

INFO_FILE=$RAZOR_UNIVERSE_DIR/DOMAIN_01/<group>/Info/
filename
AUTHOR=`awk '/ATTR.*Author/ {print $3}' $INFO_FILE`

The decision as to whether or not you should use razor_learn, or code something yourself will be based on balancing your need for shell code efficiency against your available time and comfort level for writing scripts.

razor_learn_file <filename>

This is a special purpose subset of the razor_learn function described above. Rather than parsing just the file found in the Info directory of the indicated $RAZOR_GROUP, it will parse any similarly shaped file, as identified by the argument to the function.

It is expected that this function will be used most often to interpret information that has not yet been fully recorded in the database.

TIP: The issues program creates a copy of the issue form as a simple disk file, (in the format of an Info file), and offers it to apply.before scripts as the first argument on the command line. This allows the script to examine the information on the form prior to it being passed to the database server.

razor_attr_val <attribute_label>

This function will set environment variable $RAZOR_ATTR_VAL to the value of the specified attribute label. This function should be called after invoking razor_learn so $RAZOR_ATTR and $RAZOR_<attr name> are properly defined.

razor_versions

This function fills the environment variable $RAZOR_VERSIONS with a space separated list of all the version numbers for the file most recently examined with the razor_learn function. This functionality was separated from razor_learn in the interest of efficiency.

Filtering by script

Just as the filter panel of the GUI's allow you to prune the main display list to a specific set of files, it is possible to achieve the same effect through functions in the rz_toolbox.

razor_load_filter <filter_file>

This function is meant to read in the filename specified as the single argument. Each line of the file should contain a single attribute name, a tab, and a list of acceptable values. The resulting collection represents a filter which may be applied against files in the database.

razor_filter_match

Given that a proper filter has been loaded (above), this function compares the most recently razor_learn'd file and returns a 1 if it matches all of the selection criteria.

For example, if we wanted to print all of the files in the apple group which were written by Ken and were for the HP platform, then we could use the following script.

#!/bin/sh
#
# Source in the toolbox, set the group, and get a list of
# all the files in it
#
. $RAZOR_HOME/scripts/rz_toolbox
RAZOR_GROUP=apple
razor_files
# 
# Create a temporary filter file definition, load it in,
# then delete the file
#
FF=/tmp/ff.$$
cat >$FF <<-EOF1-
Author    Ken
Platform  HP
-EOF1-
razor_load_filter $FF
rm -f $FF
#
# Now spin in a loop for all the files and print the ones
# that match what we're looking for
#
for x in $RAZOR_FILES ; do
    razor_learn $x
    razor_filter_match
    if [ $? -eq 1 ] ; then
        lpr $x
    fi
done

The above example is perhaps overkill for such a simple task, but it does serve to illustrate how several of the themes discussed in the rz_toolbox may be used together to achieve a reasonably sophisticated solution.