Basics: defining the terminology

The Attributes file

One of the most important configuration files for the Razor tool suite is Attributes. There is a copy of this file within the Tables sub-directory for issues, each of the defined file groups, each of their associated thread groups, as well as the project group.¹

The full syntax for the Attributes file is provided later in this manual. This nicely commented file is generated during the creation of a new database or group. You are encouraged to refer to these comments for specific details on how to edit the file itself. Below is an example of the out-of-the-box issues Attributes file.

NOTE: While Razor comes pretty-well equipped out-of-the-box, the configuration files are intended only to be a starting point. You are encouraged to customize these files to meet your specific requirement.

# 
# Standard RAZOR data file rules apply.  Empty lines and those beginning
# with a hash (`#') are ignored.  These may be sprinkled liberally
# throughout the file.
# 
# All other lines must contain at least three (3) TAB SEPARATED fields.
# If there are fewer than 3 fields, the program errors out.  Some attribute
# types allow/require a 4th TAB SEPARATED field.  The first field denotes
# the type of attribute item, and it must be one of the following...
# 
#    CHECK_BOX
#    TEXT_FIELD
#    ONE_OF_MANY
#    ONE_OF_MANY_STACK
#    X_OF_MANY
#    TIME_STAMP  (issues only)
#    LABEL
#    STATE
#    ONE_OF_MANY_LIST
#    X_OF_MANY_LIST
#    TEXT_PANE
# 
# The second field is the label you want associated with the item.  Since
# this is a tab delimited file, it is possible for the label to contain
# embedded spaces, however, we STRONGLY discourage this.  The RAZOR programs
# will append a colon (`:') to the text when displaying it on screen.
# 
# The third field is required, but the syntax differs for each of the
# possible attribute types.  Please refer to the documentation for
# details.
# 
# For ONE_OF_MANY, ONE_OF_MANY_STACK, X_OF_MANY, ONE_OF_MANY_LIST and
# X_OF_MANY_LIST an optional 4th field defines the number of rows to
# display the Attributes.
# 
# The TEXT_PANE attribute is used to label the two scrolling text areas
# at the bottom of the issue form.  The attribute name MUST be of the
# format `TEXTn' where `n' is 1 for the first text area, 2 for the second.
# The third field in the TEXT_PANE definition will be the string used to
# label the text area.
#
# For the TIME_STAMP, the third field is the time format and may be in a
# form as specified in the man pages for gmtime or ctime.  An example of
# a time format would be the string %D.  This would display the date in
# the format MM/DD/YY.
# 
# The fourth field of the TIME_STAMP attribute is a comma separated list
# of flags of the following format:
# 
#	I=<nn>		-Defines an increment in days to be added to the
#			 current date.
#	P=[Y|N]		-Defines if this field should automatically be
#			 loaded when a new Issue is created.  The default
#			 is N.
#	R=[Y|N]		-Defines if entry of the field is required.  The
#			 default is N.
#	U=[Y|N]		-Defines if the field should automatically be
#			 updated when an Issue is transitioned to the
#			 modify state.  The default is N.
#	W=[Y|N]		-Defines if the field is writable.  The default
#			 is Y.
# 
# NOTE:  For the issues program, the first field MUST be a TEXT_FIELD.
# This text field is shown on the main display as the title for the
# issue.
# 
# CHANGING ATTRIBUTES:  After you have created some issues, you may
# find that you would like to change or add attributes.  To ADD an
# attribute or add a value (including a state) to an existing attribute, 
# take the database server down ("razor down") and edit this file.  
# To RENAME or REMOVE an existing attribute and/or an attribute value
# (including a state), take the database server down and use one of
# the following scripts that may be found in $RAZOR_HOME/scripts:
#
#	rz_rename_attr, rz_rename_attr_val 
#	rz_remove_attr, rz_remove_attr_val
#
# These scripts will update the Attributes file and the existing
# database.  Refer to the manual for details.
#
#
TEXT_FIELD	Title	50
ONE_OF_MANY	Priority	---, Low, Medium, High, Urgent
ONE_OF_MANY	Impact	---, Minimal, Medium, Severe

STATE	State	Submitted, No-Action, Active, Completed, Closed

TIME_STAMP	Projection	%m/%d/%Y	I=7,P=Y

X_OF_MANY	Scope	Code, Systems, Documentation, Library, 
Marketing, Testing

CHECK_BOX	Approved	No

X_OF_MANY	Responsibility	Engineering, Testing, Management

TEXT_PANE	TEXT1	Description of Problem

TEXT_PANE	TEXT2	Actions Taken

Since an understanding of attributes serves as a cornerstone to all three programs in the Razor tool set and since the syntax and nature of the controlling file is the same, it is discussed first.

Attribute types defined

Below is a summary of the primary attribute types, how they may be used, and how they end up appearing on your display. In the hope of clarity, the typographic convention "" is used to denote the tab character. You are actually allowed to use as many tabs as you wish to separate the fields in order to make the file look more columnar.

NOTE: Although the syntax and mechanisms of Razor allow it, we strongly discourage the use of punctuation characters in either the attribute labels or possible values; these tend to confuse or complicate efforts to parse the resulting ASCII database files with UNIX utilities such as awk or perl. The syntax also allows for spaces to be used in attribute labels (but not the values), however, we, again, discourage their use. Instead of spaces, we would recommend using either the underscore character (as in "Due_by"), or Hungarian Notation (as in "DueBy"). Choose attribute labels and values much as you would choose variable names in a program.

IMPORTANT: Before modifying an Attributes file, be sure to bring down the database server. Restart the server for the changes to take effect.

CHECK_BOX

A CHECK_BOX is conceptually an X_OF_MANY which offers only one option. That single option can then either be selected or not selected. The syntax for specifying this attribute type is as follows:

CHECK_BOX<label_name>2<default_value>

The <default_value> should be set to `0' (zero) if you'd like the CHECK_BOX to be initially un-set, and `1' (one) if you'd like its default to be selected. An example is shown below:

CHECK_BOXObsolete0

The decision of when to use a CHECK_BOX instead of one of the other attribute types (such as a ONE_OF_MANY offering `Yes' and `No') is up to whomever configures your Razor installation.

LABEL (issues only)

A LABEL is purely read-only information presented on the issues form. Users cannot interact with it or modify it in any way. The syntax is as follows...

LABEL<label_name><text>

In this case, the <label_name> does not actually get displayed to the user³. Instead, it is the <text> field which is put on the display, as in the following example:

LABELQA** Values below here are for QA only **

This attribute type is often employed simply to provide a visual break between different sections of a large attribute collection.

ONE_OF_MANY
ONE_OF_MANY_LIST
ONE_OF_MANY_STACK

These three attributes serve the same function but differ in the way the values are presented to the user. The intent is to force the selection of a single value from a limited list⁴ of options. These attributes are often used to select a priority for an associated issue or to denote the type of file being entered into the versions program. Since the definition is the same for either, we'll just show the syntax for ONE_OF_MANY...

ONE_OF_MANY<label_name><value_list>[<num>]

Here, the <value_list> is a comma-separated list of values that you want offered to the user. Values in the value list can either be a text string (with no embedded spaces) or a file specification of the form "file:<filename>". <filename>, located in the groups Tables directory, can be any combination of comma, space, or newline-delimited entries. Let's say that the file fruit_trees, in the Tables directory, contained the following:

Apple
Pear
Cherry

... and a ONE_OF_MANY definition of a tree was found in the Attributes file as:

ONE_OF_MANYTreeOak, Elm, file:fruit_trees, Fur, Pine

...then the full list of values would be:

Oak, Elm, Apple, Pear, Cherry, Fur, Pine

Although there are practical limits on the number of values presented (you normally don't want the user to choose from a huge list), there are none directly imposed by the program.

If present, the optional <num> field gives you some control over how the options on the list are displayed. If present for a ONE_OF_MANY, it dictates how many rows the options will be spread over. If present for a ONE_OF_MANY_STACK, it determines how many entries per column will be used. If present for a ONE_OF_MANY_LIST, it determines how many lines will be visible.

Below are three examples of how ONE_OF_MANYs may be used.

ONE_OF_MANYFiletypeC,C++,Ada,Header,Script,Doc

If the above sample were instead entered as a ONE_OF_MANY_STACK, it would appear as follows:




Furthermore, if the sample were entered as a ONE_OF_MANY_LIST, it would appear as follows




The default setting on initial use is that the first option in the list is selected. For the sake of sorting, the items in the front of the list are considered lesser in value than those at the end. This is independent of what the words may mean to you.

TIP: You may want to take advantage of knowing that the first element of a ONE_OF_MANY style attribute is the default setting when you are designing an issues form. If all new issues are to be assigned a `Low' priority, then have your options work from low to high. Many sites opt to have the first choice on the list be something offbeat and visually distinct, such as `---', to distinguish whether the value was consciously set to one of the values, or left at the default.

STATE

A STATE attribute is a special purpose ONE_OF_MANY. If employed, there can be only one STATE attribute defined within the same Attributes file. The syntax is basically the same as that of a ONE_OF_MANY, as shown below:

STATE<label_name><value_list>

The <value_list> is a comma separated list of possible state names. Unlike a ONE_OF_MANY, however, you do not have the option of controlling the number of rows used during the display of this type of attribute.

Although the syntax for defining the STATE attribute is the same, the "state" of an issues form is completely different in meaning and intent from the "state" of files or threads under control of Razor. For a more detailed examination of how and why you would use the STATE attribute refer to either "Issue STATEs (permissions)" on page 205, or "File and thread STATEs" on page 213.

TEXT_FIELD

A TEXT_FIELD is a single line of unrestricted text. Common usage is most likely as the initial entry on an issues form. As entered in the Attributes file, it consists of 3 tab separated fields...

TEXT_FIELD<label_name><length>5

Where <label> is what will appear on the display and <length> is the maximum number of characters that can be entered into the field. Below is a sample TEXT_FIELD and the display that would result from it...

TEXT_FIELDTitle50






These attributes are naturally empty at creation time. The above example sets a limit of 
50 characters. Your setting may be set larger or smaller depending on the specific need 
for the information to be held in the field.

NOTE: For issues, the first TEXT_FIELD.entry MUST be non-blank when submitted, either as entered by the user or by pre-load or e-mail submission. Issues requires at least one TEXT_FIELD attribute. The first TEXT_FIELD is shown as the title on the issues main display.

TEXT_PANE (issues only)

The TEXT_PANE attribute is used to label the two scrolling text areas at the bottom of the issue form. The attribute name MUST be of the format `TEXTn' where `n' is 1 for the first text area, 2 for the second. The definition consists of three fields...

TEXT_PANE<TEXTn><label_name>

The third field in the TEXT_PANE definition will be the string used to label the text area. Two text panes, TEXT1 labeled `Problem' and TEXT2 labelled `Solution' are shown below.




The contents of these two text panes can be prefilled from the contents of the files Problem_template and Solution_template. Details of the use of these files is discussed in "Pre-loading information into the text panes" on page 210.

TIME_STAMP (issues program only)

A TIME_STAMP is a special purpose text field which offers a very controlled but versatile input mechanism. As such, its syntax is a bit more complex than most of the other attribute types, as shown below:

TIME_STAMP<label_name><format><flags>

As with all the other attribute types, the <label> field is simply used as an identifier on the display and in the database.

The <format> field controls not only what information is displayed and entered on the attribute but also exactly how it appears. An example of a format field would be the string "%D" which yields a date entry of the form "04/01/95".⁶ For a full listing of the types of format strings allowed, you'll need to refer to the man pages for strftime on a UNIX system. Below are some examples illustrating the variety of options.




For example, to generate the second example in the above listing, make the following entry in the Attributes file:

TIME_STAMPBrief%e-%b-%Y

A TIME_STAMP attribute is reminiscent of a TEXT_FIELD, and the user can directly type into it. You'll notice that the <label_name> field becomes a button on the issue form. Selecting it brings up a separate panel which is used for the actual entry of the date/time value. Input to the field is nicely controlled, yet remains flexible for the user.




The Time menu option offers a variety of courtesy mechanisms for setting the field to specific dates (Today, One week from now, Four weeks ago, etc.). The special options of Min and Max time set the field to the most distant and future times possible.⁷

The Clear button at the bottom of the popup clears the data on the field and dismisses the popup.

The optional <flags> field for timestamps is a comma separated list of additional controls over how the TIME_STAMP itself behaves. Possible entries are detailed in the following table:

Flag	Description	Default
I=<n>	The <n> entry defines the number of days (increment) to be added to the current date when the field is pre-loaded or updated.	0
P=[Y|N]	Defines whether this field should be pre-loaded when a new issue is created.	N
R=[Y|N]	Defines whether an entry is required for this field.	N
U=[Y|N]	Denotes whether the issues program should automatically update this value to today's date plus the increment whenever the issue is toggled to the modify state.	N
W=[Y|N]	Defines if the field is writable by the user.	Y

Note that there can be no spaces on either side of the `=' sign for any of the flags, but that more than one flag can be specified for a TIME_STAMP. For example, the following flag combination indicates that the attribute should be pre-loaded with a date one week from today, whenever the issue is created or modified, and the user is not allowed to change it.

P=Y,I=7,U=Y,W=N

Razor allows you to "spell out" the flag names if you wish, which may make the meaning of the flags clearer, as in the following...

Preload=Yes,Increment=7,Update=Yes,Writable=No

NOTE: It is possible to create conflicting flag combinations. For example, you could require entry in the field, but not have it be pre-loaded or writable by the user. Please don't do this; you won't like yourself in the morning.

All of this functionality and control combine to make the TIME_STAMP attribute one of the more powerful fields on the issues form. Through it, you can set up fields for noting the discovery date of a problem (which may be different from the date the issue was submitted), reminder dates for notifying the originator of the status of the issue... whatever.

X_OF_MANY
X_OF_MANY_LIST

X_OF_MANY and X_OF_MANY_LIST offer the ability to choose zero or more options from a fixed list⁸. The syntax for this type of attribute is nearly identical to that of a ONE_OF_MANY and is as follows:

X_OF_MANY<label_name><value_list> [<num>]

Here, the <value_list> is a comma-separated list of values that you want offered to the user. Values in the value list can be either a text string (with no embedded spaces) or a file specification of the form "file:<filename>". <filename>, located in the groups Tables directory, can be any combination of comma, space, or newline-delimited entries. Let's say that the file unix_platforms, in the Tables directory, contained the following:

Sun
HP
SGI
RS6000

... and a X_OF_MANY definition of platform was found in the Attributes file as:

X_OF_MANYPlatformfile:unix_platforms,Macintosh,Intel

...then the full list of values would be:

Sun, HP, SGI, RS6000, Macintosh, Intel

Although there are practical limits on the number of values presented (you normally don't want the user to choose from a huge list), there are none directly imposed by the program. If present, the optional <num> field serves to control how many rows will be used to display the list to the user. Below is an example:

X_OF_MANYPlatformSun,HP,SGI,RS6000,Other

If the above sample were instead entered as an X_OF_MANY_LIST, it would appear as follows:




The default setting for an X_OF_MANYs is that none of the options are set. You are allowed to filter on X_OF_MANYs settings but you cannot use them for sorting. To select a value in a X_OF_MANY_LIST attribute, use the Select button. To select additional attributes, use CTRL-Select. Refer to "Scrolling list behavior" on page 15 for a review of list selection methods.

¹ It may be helpful to examine how the Razor database directory structure is organized by referring to the text and diagrams in Appendix A on page 253.
² label_name throughout this chapter refers to a label given to the attribute. This name should not contain any special characters (like commas, quotes, etc). The label name is the way the attribute is referred to in various Razor commands and controls.
³ The <label_name> for a LABEL attribute does, however, come in handy when customizing the colors of the various attributes on the issue form. See "X Resources" on page 273.
⁴ Up to 1024 items.
⁵ The length the field as it appears on the issue form may appear to be longer or shorter than the defined length. The number of characters entered is limited to the defined length. The field will be scrollable if necessary.
⁶ Razor will properly handle two-digit years, but the %Y format (four-digit year) is encouraged.
⁷ See "What will happen on the year 2000 rollover?" on page 338.
⁸ Up to 1024 items.