Eric J. Ostrander's
ClearCase / ClearQuest pages.
ClearDDTS, how do I ...
CC integration   |   Classes   |   Enclosures & Attachments   |   Fields   |   master.tmpl   |   Misc.   |   Projects   |   Records   |   Reports & Queries   |   Security   |   States
Simple, case-insensitive search:

NOTE: Most of the examples require you to be logged in as ddts. The adminbug command has been shortened to ab for brevity. This is also a normal alias for ddts admins. This page was written mostly using DDTS 4.1, but has notes for DDTS 4.5 as well.
Classes
Back to the TOP
Create a class. (clas)
Remove a class. (dcls)
Rename a class. (rcls)
List projects belonging to a class. (projstat)
List all classes on the system. (projstat)
Configure the web interface on a per-class basis.
Clean cache on a per-class basis.
Set a default class on a per-user basis.

Enclosures & Attachments
Back to the TOP
Enclosures & Attachments
Add enclosures & attachments.
Remove enclosures & attachments.
Rename enclosures & attachments.
Edit enclosures & attachments.
Search enclosures & attachments.
Fully display enclosures (not links).

Fields
Back to the TOP
Set user specific field default values.
Set user specific date field format.

master.tmpl
Back to the TOP
master.tmpl

Misc.
Back to the TOP
Dependent picklists.
Maintenance mode. (smnt,emnt)
Licenses.
Site id.
Defaults.
Determine ClearDDTS version installed. (whichddts)
Determine/change the DDTS administrator(s). (mins)
Determine/change the database type being used. (chdb)
Move DDTS to a new location.
Configure the web interface on a per-class basis.
Set up distributed defect tracking. (conn,asub)
Toggle webddts toolbar animations.
Clean cache on a per-class basis.
View user preferences. (dumpdbm)
Reconfigure the web interface. (webconfigure)
Ensure DDTS permissions are set ok. (chddts)

Projects
Back to the TOP
Projects.
Create a project. (aprj)
Remove a project. (dprj)
Close a project. (cprj)
Open a project. (oprj)
Rename a project. (renm)
List all the projects. (lbug)
Modify a project's parameters. (mprj)
List a project's parameters. (lprj)
Change a project's class. (mprj)
List projects owned by this machine. (lown)
Move/copy a project. (sprj,rprj)
List projects being subscribed to by this machine. (lsub)
Subscribe to a remote project. (asub)
Remove a subscription to a remote project. (dsub)
Modify a subscription's parameters. (msub)
Print all project information. (projstat)

Records
Back to the TOP
Find bug reports. (findbug)
Remove a bug report. (rmbug)
Modify a bug report field value. (batchbug,patchbug)
Move bug reports between projects/classes.
Move bug reports between servers.
Clone a bug report.
View a bug report.
Create a parent/child relationship.
Customize a parent/child relationship.

Reports & Queries
Back to the TOP
Query.
Create or modify a report.
Search enclosures & attachments.

Security
Back to the TOP
General
Apache
Netscape

States
Back to the TOP
Create a new STATE.
states file
statenames file
Create a class.
The clas subcommand creates a directory ~ddts/class/classname. The classname is limited to 14 characters and standard UNIX naming conventions.
Before you begin:
-- define the defect life cycle
-- define information you want to associate with defects
-- identify an existing class as your class prototype
  # ab clas
Back to the INDEX.
Remove a class.
Before deleting a class, you must delete any projects associated with it. The dcls subcommand can be aborted with <CTRL-C> anytime before the end without harm. 
  # ab dcls
If the deleted class was the default class, such as "software", ensure the new default class is entered in the ~ddts/.ddtsrc file (or for any user using a .ddtsrc file). Never delete the special "ALL" class.

Back to the INDEX.
Rename a class.
The classname is limited to 14 characters and standard UNIX naming conventions. 
  # ab rcls
  # ab dbms
Back to the INDEX.
List projects belonging to a class. 
  # projstat -C class-name
Back to the INDEX.
List all classes on the system. 
  # projstat -k
Back to the INDEX.
Set a default class on a per-user basis.
Log into webddts as the desired user and go to Profile. Enter desired class under Default Class. Be sure to Clean Cache before leaving the page.

Back to the INDEX.
Enclosures & Attachments.
Enclosures contain text you add to describe the details and status of a defect. Enclosures are saved as part of the defect record to which they are attached. Attachments contain binary data (images, executables, and so on) or text. When an attachment is added, it is copied to the ~ddts/allbinaries/identifier directory instead of being part of the defect record itself, as in enclosures. Only a URL pointing to the attachment appears as part of the record. The URL appears as: 
http://server/all-bin/identifier/attachment
There is an alias in the web-server-home/conf/srm.conf file that points all-bin to the ~ddts/allbinaries directory.
NOTE: Do not use any special characters in the name of an attachment. The names must adhere to standard UNIX naming conventions.
NOTE: Enclosures are added to the end of the bug report flat file when modified. This isn't fatal, but can look funny if the enclosure, such as the initial "Problem" enclosure, is modified after the fact. That is, if the bug report is printed out via a script or something, the initial "Problem" enclosure will be last. This isn't true for field modifications; they always keep their relative position in the file.

Back to the INDEX.
Adding enclosures & attachments.
The "Add Enclosure" and "Add Attachment" buttons are located at the bottom of each bug report page when in the View/Modify defect mode. Adding an enclosure will let you type text directly into the bug report. The "History" enclosure is added automatically. Adding an attachment will let you type in the name of a file that is then copied to the ~ddts/allbinaries/Identifier directory with a URL placed in the bug report pointing to it.

Back to the INDEX.
Deleting enclosures & attachments.
To delete an enclosure, click on it to open it, then click on the "Remove" button at the bottom of the page an you're done. You cannot delete the "History" enclosure. Since attachments are just a URL pointing to a file, you cannot delete one via the web interface. If it is absolutely necessary to remove an attachment from a bug report, have the DDTS administrator do it manually. Delete the attachment file from the ~ddts/allbinaries/Identifier directory. If that was the only attachment in that dir, delete the Identifier dir as well. Then, remove the appropriate "Related-file::" line from the ~ddts/allbugs/sub-Identifier/Identifier file. Don't forget to run "ab dbms" when done.

Back to the INDEX.
Renaming enclosures & attachments.
To rename an enclosure, click on it to open it, then click on the "Rename" button at the bottom of the page an you're done. You cannot rename the "History" enclosure. Since attachments are just a URL pointing to a file, you cannot rename one via the web interface. If it is absolutely necessary to rename an attachment in a bug report, have the DDTS administrator do it manually. Rename the attachment file in the ~ddts/allbinaries/Identifier directory. Then, rename the appropriate "Related-file::" line in the ~ddts/allbugs/sub-Identifier/Identifier file. Don't forget to run the "ab dbms" command afterward.

Back to the INDEX.
Editing enclosures & attachments.
To edit an enclosure, click on it to open it, then click on the "Edit" button at the bottom of the page an you're done. You cannot edit the "History" enclosure. Since attachments are just a URL pointing to a file, you cannot edit one via the web interface. If it is absolutely necessary to edit an attachment in a bug report, edit the original version, delete the current attachment (see Deleting enclosures and attachments), and re-attach it.

Back to the INDEX.
Searching enclosures & attachments.
Use the "Complex Query" page. After setting the appropriate Project(s) and State(s), use the following "Field Name" values to search attachments:

Enclosure_name
Enclosure_text
Enclosure_count
History_text

Back to the INDEX.
Fully display enclosures (not links).
Logged into webddts, go to Profile -> Display Options. Select choice under View Enclosures. After applying the change, you may need to go back to Profile and Clean Cache to see the changes.

Back to the INDEX.
Set user specific field default values.
Log into DDTS via the web interface (webddts) as the desired user. Go to Profile -> Field Defaults. Choose a field to be given a default value. Enter the default value in the space provided. Date strings must be in yymmdd. Set the Sticky switch if you want a value entered in a defect to become the new default value for that field. Click Apply.
NOTE: This cannot be used to override system defaults. That is, if the administrator has already defined in the master template a default value for the field in question, this will not override that value.

Back to the INDEX.
Set user specific date field format.
Logged into webddts as the specific user, go to Profile -> Display Options. Set the desired format under Date Format. Once the change is applied, you may need to go back to Profile and Clean Cache to see the changes.

Back to the INDEX.
master.tmpl
On the web: http://www.rational.com/support/techpapers/parser/
In UNIX: man template
See the other section of this page for a discussion on Dependent picklists in the master.tmpl.
A good way to test template field derivations is to run wtform on the command-line. This avoids the tedious waiting for DDTS to actually write and update the database. For instance, to test the state transition of a specific bugid, use the following: 
  # wtform -a transition -i bugid -s state -v
The executable wtform lives in ~ddts/bin. The state is the single capital letter of the state to which you would like to test the transition. The   -v   option simply means verbose output. This assumes that bugid already exists. That is, this doesn't work for the Submit state. The executabe has many other options that can be exploited as well. Just type wtform on the command-line without any options to get a listing.
1) The actual code (if statements and such) cannot be left justified. Only group names, field names, etc ... can be up against the left side of the page.
2) There cannot be any trailing spaces after the last entry on a group's "set group_fields" line or the last entry will not be recognized.
3) You can use the "set" command to set a temporary variable, but it will not be recognized outside that particular field's derivation. Also, you cannot use the "set" command inside a paint (p) derivation.
4) You cannot create a field who's value can be seen by other field derivations and not have that value show up on the web screen.
5) The field name variable does not get a value assigned to it until after the field has been fully derived. During derivation, the variable $$ contains the value of field.
6) Any command, such as echo or whoami, will automatically set $$ without an explicit "set" command.
7) Even though it's easy to setup dependent picklists, you cannot make a field's name red (required) or black (not required) based on the answer in a previous field on the same form.
8) If you add fields, you must add them to the ~ddts/dbms/ddts database.cfg and schema_file files and then run "ab dbms". While adding fields to the master.tmpl shows up immediately, queries of the database will fail until those files are updated. NOTE: There can be no dashes, capital letter, colons, or characters other than lower-case and under scores in the schema_file. The mapping from the real fieldnames to the pseudo-names happens in the database.cfg.
9) There are only two ways to halt (error out) of the parsing of the master.tmpl file and they are "abort" and "false". The abort command will terminate the parsing immediately and echo the surrounding master.tmpl text to standard error (very ugly). The false command only terminates parsing after hitting the submit button. That is, the user will have already made changes before realizing the operation was illegal (not fair). Those are the only two ways to error out, so you have to live with one of them.
10) Even though a field may have been derived in a previous state and is now written in the flat file in the allbugs directory, you cannot reference that variable until after parsing has passed the associated field derivation again.
11) The following are necessary if adding an enclosure field to a state: a) Add a field called Related-file to the state (use an existing one as a template).
b) Create a file in the class directory containing the default message. This file is referenced by name in the Related-file field derivation.
c) Add the Enclosure-count fieldname to the "set group_fields" line for the state.
d) Add a enclosurename_encl entry to the "set group_fields" line for the state.
In addition, the field derivation line that contains that name seems to need to be enclosed in an "if" statement similar of this format: 
        if match $OPERATION v m
        or match $STATE$OPERATION Tp Tf
12) You cannot run custom Filter commands when the DDTS form is being initially processed. That is, if you want the default of a field to be the output of a script that you've written, it won't show up. In fact, the script won't even be executed. There is a very limited set of commands available to the parser when it first paints the screen, and customized scripts are not in that list. However, customized scripts CAN be used for post processing, such as mapping a user's real name to an email address or adding lines to an enclosure.
13) You cannot reset a default value of a field once it has been set in a previous state transition. That is, in some field derivations it is desirable to set a default value for the user to see. However, if that field already has a value from some previous modification of that bug report, there is no way to reset it to a default value in the master.tmpl. I.E. The value the shows up on the screen will be the value that was previously set.

Back to the INDEX.
Dependent picklists.
The contents of a field in a ddts form on the web can be dependent on the value from another field's picklist (oneof file). That is, if you chose a value in one field's drop-down list, the value picked will determine the values available in another field's picklist. As an example, there might be a field called "Charge-number" in the master.tmpl file whose oneof file contains a list of valid charge numbers for the project: 
Charge-number:          "Charge number: %-9.9s"
                        if match $OPERATION p m
                                oneof -f charges
                                required
                        fi
In this example, "charges" is a oneofs file in the class/oneofs subdirectory.
If you then want the burden codes to be dependent on which charge number is picked, you would then have a second field that might look like this: 
Burden-code:            "Burden-code: %-3.3s"
                        if match $OPERATION p m
				oneof -f $Charge-number.codes
                                required
                        fi
This then implies that there exists oneofs files, each with a unique name starting with the entries of the "charges" oneofs file. For example, if the "charges" oneofs file contains the entry 1234-5678, then there needs to be a oneofs file called "1234-5678.codes" containing a list of burden codes associated with the 1234-5678 charge-number. This hierarchal structure can be continued indefinitely, with the fact in mind that the number of oneofs files grows exponentially with each level of dependent depth. Also, keep in mind that since the dependent list's oneofs files are named after the entries in the parent oneofs file, those entries need to conform to standard UNIX naming rules.

NOTE: Even though it's easy to setup dependent picklists, you cannot make a field's name red (required) or black (not required) based on the answer in a previous field on the same form.

NOTE: If the dependent field derivation has an "if null" statement in it, that statement will only be picked up the first time the page is painted. That is, your default value will only be seen the first time. When the parent field is changed, the dependent field's value will be one of the values in the onoefs file. This is only true if the default value set in the "if null" statement is not one of the values in the oneofs file, such as 
Component:		if null
				echo ""
			fi
NOTE: Rational has patches for DDTS 4.1 on Solaris & HP-UX if dependent picklists are used via Microsoft Internet Explorer 4.x.

Back to the INDEX.
Maintenance mode.
Entering maintenance mode terminates all daemons and software can be safely updated. Requests for info can still be made, but ddts will take no action on them until after exiting maintenance mode. 
Enter
  # ab smnt
Exit
  # ab emnt
Back to the INDEX.
Licenses.
For versions 4.1 or later, DDTS uses the Flexlm license manager. The previously used individiual licenses have been converted to floating licenses at the rate of 3 individual to 1 floating. That is, if you had 28 individual licenses for DDTS 4.0, you would have 10 floating licenses after the upgrade to DDTS 4.1 and conversion to the Flexlm license scheme.
As of DDTS 4.5, Rational has re-introduced the node-locked (individual) licenses as an option. That is, 4.0 only had node-locked, 4.1 only had floating and 4.5 has either floating of node-locked. However, node-locked licenses do not work with webddts, which is the interface that most people use.
Licenses are converted by submitting a request via the web to Rational at http://www.rational.com/cgi-bin/www/ddts_license_reg.cgi. You will need to give them the old serial number, which is found by typing "ab type" as the ddts user before the upgrade. The serial number is a 7-digit number beginning with "14". Also run "showrev" and take note of the Hostname, Hostid, and Kernel version. The "ab type" command no longer works in DDTS 4.5. One must use "lmstat -f ddts" to get the same information. On some systems "lmstat -f ddts -c license-file".
The new license string will be requested when doing the install. The install will create a file in the ddts home directory called "license.dat". However, it's best to run the Flexlm license manager from a more common location; because other packages can also be using it and it's best to keep a central location and a common license file. The normal common location for the Flexlm stuff is in /usr/local/flexlm. This directory should contain the subdirectories bin, licenses and log. The bin directory contains all the lm* files from the ~ddts/bin directory of the DDTS install. The licenses directory has the license.dat file in it. The log directory has the lmgrd logfile in it, which is defined on the command-line when invoking lmgrd.
If additional licenses are added (for a given VENDOR) to an existing license file, they will have to be encoded by Rational and have the name "INCREMENT" instead of "FEATURE". That is, you can't just add other FEATURE lines to the file, otherwise it will only pick up on the last FEATURE line. So, a file should then have only one FEATURE line per VENDOR and the rest need to be INCREMENT lines (for that VENDOR). Once the new lines are added, run the lmreread command to update the license manager. Then run "lmstat -f ddts" to ensure that the additional licenses have been picked up properly. On some systems lmstat and lmreread need to have the "-c license-file" option to explicitly tell them where to find the license file.
NOTE: One common question that needs to be answered is, how many licenses are being used on average and what is the peak usage. GLOBEtrotter has a good utility to answer those questions called SAMreport.

Back to the INDEX.
Site id.
This procedure assumes you have a running DDTS installation. Also, it does not lead to the loss of any data.
NOTE: The site id is server wide. There is no way to make a project or class dependent site id. 
  # cp conf/submit.sites submit.sites.sav
  # ab dsbl
  # ab inst
  # ab dbms
  # ab alic
  # ab asub  (reconnect to all sites listed in submit.sites.sav)
The site id is stored in ~ddts/conf/def.seq.

Back to the INDEX.
Defaults.
The DDTS defaults page allows you to set your default class, where ddts home is, set query index fields and clean your cache if necessary. The information set on this page is stored in ~ddts/www/output in files that begin with your ddts login name. The _ini file is also where your Saved Queries are stored.

Back to the INDEX.
Determine ClearDDTS version installed.
The following command lives in ~ddts/bin: 
  # whichddts
There is also an empty file in the ddts home directory called version-* that tells what version is installed. 
  # ls ~ddts/version*
Back to the INDEX.
Determine and/or change the DDTS administrator(s).
DDTS administrators rcv mail when there is a problem with the system.
To determine the ddts administrator names: 
  # ab ladm
To change the adminstrator list: 
  # ab mins
The administrator's names are kept in the ~ddts/conf/administrator file.

Back to the INDEX.
Determine and/or change the database type being used.
To change the database type currently in use, execute the following and follow the prompts. 
  # ab chdb
To determine the database type currently in use, simply abort the above command without changing anything.

Back to the INDEX.
Move DDTS to a new location.
If moving the DDTS install area to a new location on the same machine, it's easiest to just move the ddts home directory and then create a softlink from the old location to the new.
If the softlink is not an option, perform steps 2-5. If moving to a different server, perform all the following steps.
1) If FlexLM doesn't exist in the new location. Copy the entire flexlm directory from its location on the old server (usually /usr/local/flexlm) and install it on the new server. Also copy the /etc/init.d/flexlm startup file over and create links to it from /etc/rc2.d and /etc/rc3.d. Use the old server as a model. Don't forget to edit the license.dat file to reflect the new location.
2) Create/modify the /etc/passwd & shadow file entries for ddts.
3) Install a web server on the new DDTS server. If one already exists, modify the httpd.conf file so that any alias for ddts points to the new location. Use the old httpd.conf (or srm.conf) file as a model.
4) Modify any ddts crontab entries, if there are any.
5) Modify the ~ddts/bin/ddts.secure file, if it exists.

Back to the INDEX.
Configure the web interface on a per-class basis.
As of DDTS 4.5, certain attributes of the webddts interface can be configured on a class by class basis. The following are some of things that can be customized:
-- Prompt for a project before painting the screen (for dependent picklists).
-- Report gif-size.
-- Report generation in serial or parallel.
-- Report scaling.
-- Enclosure wrapping: Y or N.
-- Automatically expand enclosures: Y or N.
-- Active or inactive toolbar gifs.
See the ~ddts/class/class/web_conf file for details.

Back to the INDEX.
Set up distributed defect tracking.
The following procedure will allow two installations of DDTS to see and trade bug reports between their projects. This procedure assumes that DDTS is already installed and running at both sites. Site-A is a site wishing to export some of its projects and Site-B is at the rcving end. Both sites need not export all or any of their projects. That is, the connection/distribution can be unidirectional. For the class in which the "shared" project lives, the master.tmpl and associated files (onoefs, *.encl, etc...) need to be agreed upon by both site administrators sent/set up manually. Only bug reports get propogated automatically.
1) At Site-A, decide which projects are to be exported. Place the names of those projects in ~ddts/conf/export. Only projects listed in the DDTS export file will be available to the remote site. The syntax for the file is: site-id: project(s). Example: 
EJOqa: proj_3.0 admin
TEKcc: * !proj_3.0
*: *
In this example, the remote site designated by the site-id EJOqa can log bugs against the proj_3.0 and admin projects. The site designated by the site-id TEKcc can log bugs against any project except proj_3.0. Both the site-id and project can utilize UNIX metacharacters: "*", "?", "[" and "]". The third line states that any site other than EJOqa or TEKcc can subscribe to any project. The lines are ordered. If a site-id matches a line, it looks no further. An empty file or no file means that nothing is exported.
2) At Site-B, use the syntax described in (1) to create ~ddts/conf/import. This file tells the local DDTS which projects you will allow to be installed on your system.
3) Connect the two sites. At one or the other site, issue the following command. This will set up communications (email) between the two ddts users at each site so that users can see the other's classes and projects. The conn subcommand does not actually transmit any data, but merely opens the door betweeen the sites. 
  # ab conn
4) Even though the door was opened in step (3) and the export/import files are filled in, the projects are still not propogating data. Each project needs to be subscribed to. The following command asks for a subscription to a project. That is, it is run from the rcving end. If the export file on the remote end, the import file on the local end are configured and "ab conn" has been run, the project will automatically transmit data. A person at Site-B can now submit defects against the subscribed project as if that project were local. DDTS handles the transmission. This has the affect of copying all remote data to your local system for that project. 
  # ab asub
NOTE: When the asub command is run, the two sites are synchronized WRT the project in question. Now a user can log bugs against that project. When the bug goes to the NEW state, it is propogated to all other remote sites. This is also true for other state transitions and bug report modifications. However, this is not true for commands such as rmbug. If you delete a bug report, the bug report has to be deleted manually from the other site. If not, it will automatically resynchronize back to your site when the ddtsclean cron job runs at night.

Back to the INDEX.
Toggle webddts toolbar animations.
Toggling on and off the toolbar animations that appear in webddts can only be done on a user specific basis. Log into webddts as the specific user and go to Profile -> Display Options. Set desired behaviour under Toolbar Animation. Once the change is applied, you may need to go back to Profile and Clean Cache to see the changes.

Back to the INDEX.
Clean cache on a per-class basis.
Part of the default DDTS install is to create a file called CLEAN in the ~ddts/www/cache directory. This file causes all files older than it to be cleaned periodically. To set cache cleaning on a class by class basis, create a file called CLEAN.. Change the modification date on the file to reflect how far back you want to keep cached files for that class.

Back to the INDEX.
View user preferences.
User preferences, such as phone, email, queries, etc.. are entered via the Profile button in webddts. If not logged in as a particular user, one can still view those preferences by going to ~ddts/www/user_prefs. The user files there are binary and must be viewed with the following command: 
  # dumpdbm user
Back to the INDEX.
Reconfigure the web interface.
Customizations to the main DDTS web screen are mostly done in the file ~ddts/www/perl_modules/WTForm.pm. If that file, or any other file related to the web, is customized, as the ddts user run: 
  # webconfigure
Customizations to the actual record forms is done via a master.tmpl file. Those changes do not require a webconfigure.

Back to the INDEX.
Ensure DDTS permissions are set ok.
During routine maintenance of DDTS files, permissions can be inadvertently reset to less than optimal. As the ddts user, run the following command to check installed file permissions. The check is not exhaustive though. 
  # chddts
Back to the INDEX.
Projects. (general)
1) There must be at least one project in a class before the class can be used.
2) The project control and notify lists are kept in ~ddts/projects/project.
3) General info about the project is kept in a file called ~ddts/proj.info/project.
4) Project status is checked every night via the ddtsclean cron job which calls projck.

Back to the INDEX.
Create a project.
Add a project to an existing class. The project name is limited to 14 characters and standard UNIX naming conventions.
Before begining, identify the following:
-- defect class to which the project will belong
-- people to notify when a defect changes states
-- people authorized to perform certain state transitions
-- project managers
The project must:
-- have a unique name in the ClearDDTS network
-- reference valid UNIX users and groups
Can use <Esc> to go backwards in the aprj subcommand. 
  # ab aprj
The results of aprj are stored the file ~ddts/projects/project/proj.control & proj.notify. The prompts that show up in the aprj command itself are kept in the file ~ddts/class/class/admin.tmpl/aprj2.tmpl. Note that the files mprj2.tmpl and aprj2.tmpl (notify) are identical as are mprj3.tmpl and aprj3.tmpl (control).

Back to the INDEX.
Remove a project.
This command will completely remove a project from the DDTS system along with its related bug reports. Rational recommends just "closing" the project so that the historical data is retained. 
  # ab dprj
  # ab dbms
Back to the INDEX.
Close a project.
When a project is closed, it is taken off the network so that no more bugs will be logged against it. However, all the defect information associated with it is retained so that users can run comparative metrics or query the database. 
  # ab cprj
Back to the INDEX.
Open a project.
Open a previously closed project. The project with again be avaliable to log bugs against. 
  # ab oprj
Back to the INDEX.
Rename a project.
Be aware that people on the network may already be familiar with the current name. Renaming it may cause confusion. 
  # ab renm
  # ab dbms
Back to the INDEX.
List all the projects.
List all the known projects and give a brief description of each. It does not show closed projects. 
  # ab lbug
Back to the INDEX.
Modify a project's parameters.
The mprj subcommand can be used to add or delete members from notification lists, add or delete project managers or change mail paths to subscribing machines. This subcommand asks all the same questions as if you were creating it for the first time. Can use <Esc> to go backwards in the mprj subcommand. 
  # ab mprj
The results of mprj are stored the file ~ddts/projects/project/proj.control & proj.notify. The prompts that show up in the mprj command itself are kept in the file ~ddts/class/class/admin.tmpl/mprj2.tmpl. Note that the files mprj2.tmpl and aprj2.tmpl (notify) are identical as are mprj3.tmpl and aprj3.tmpl (control).
As of DDTS 4.5, the DDTS admin can add names to custom group lists and add those groups during mprj. The group file is ~ddts/conf/group and has the format: 
grp1: bob john ejo
mygroup: ejo john
For group names listed in the proj.control file, DDTS will attempt to authenticate them as the following (in order): UNIX group, DDTS group. If a particular user's username does not fall within one of those, the bottom of the webddts page will not even give them the option to transition to that state.
NOTE: A name in a group's list cannot be the name of another group. No nested groups.

Back to the INDEX.
List a project's parameters.
This subcommand lists all the project's parameters to the screen. 
  # ab lprj
Back to the INDEX.
Change a project's class.
Simply change the name of the class in the mprj subcommand. 
  # ab mprj
Back to the INDEX.
List projects owned by this machine. 
  # ab lown
Back to the INDEX.
Move/copy a project.
Projects can be bundled up and moved from machine to machine. The sprj subcommand copies all project related files to the ~ddts/projects/project-name directory for easy tar'ing. Be sure to manually place any project dependent oneofs files there as well. 
  # ab sprj
  # cd ~ddts/projects
  # tar cvf project-name.tar project-name
Then, restore the project on the new machine. The project name can be changed during restore if desired. 
  # cd ~ddts/projects
  # tar xvf project-name.tar
  # ab rprj
  # ab dbms
If this was a move and not just a copy of the project, simply delete it from the original machine. 
  # ab dprj
Back to the INDEX.
List projects subscribed to by this machine.
These projects are owned by another machine, but can be seen by this machine. 
  # ab lsub
Back to the INDEX.
Subscribe to a remote project.
This subcommand is run on the machine that wants the subscription. The success of this subcommand depends on whether the server that owns the project allows general subscriptions. Use the mprj subcommand on the exporting machine to allow subscriptions. The project must be imported in the ~ddts/conf/import file and seen by the lbug subcommand. The project must be exported by the owner machine via their ~ddts/conf/export file. Before a project can be subscribed to, the "ab conn" command will have to be run to connect the two sites. 
  # ab asub
Back to the INDEX.
Remove a subscription to a remote project.
This does not destroy data on the local machine. To completely remove a project from the system, use the dprj subcommand after removing the subscription. 
  # ab dsub
Back to the INDEX.
Modify a subscription's parameters.
This subcommand is analogous to the aprj, mprj, & asub subcommands. 
  # ab msub
Back to the INDEX.
Print all project information. 
  # projstat -p project
Back to the INDEX.
Find bug reports.
In DDTS before 4.5, the webddts String Query uses the findbug options.
In DDTS 4.5+, from webddts Query & Report, search for bugs based on criteria via an already created bug query or Create one yourself. If the bug number is already know, type it in View Defect. In most cases a substring of the number is all that is needed. That is, if the bug number ends in 15 and there are no other defects ending in 15, simply typing "15" will be sufficient.
In xddts, Select -> Complex Query & Sort...
From the CLI, the ddts findbug command has many options. Listed below are just a couple examples. For a complete listing, see findbug man page. The findbug command lives in ~ddts/bin. 
List bugs against the adminproject.
  # findbug -p adminproject
List bugs assigned to a user.
  # findbug -u p29330
List bugs in the Closed state.
  # findbug -C
List the contents of the bugs, not just the bug report number.
  # findbug -d
Back to the INDEX.
Remove a bug report.
Rational software recommends transitioning unnecessary bug reports to an appropriate state, such as Rejected, vice deleting them from the database. If your DDTS system is distributed, it will be necessary to run the identical command on each machine locally. The rmbug command lives in ~ddts/bin. Before running rmbug, ddts should be put into maintenance mode. Don't use the   -r   option, just run "ab dbms" afterward. NOTE: The third example listed here will not work in maintenance mode because findbug needs the daemons to be running. 
  # rmbug XXXyy00011
-- or --
  # rmbug XXXyy00011 XXXyy00015 XXXyy00017
-- or --
  # findbug -p adminproject Resolved-on before 980818 | rmbug
  #
  # ab dbms
Back to the INDEX.
Modify a bug report field value.
If you just want to change the value of a field in one bug report, query for the bug report in question in the web browser and use the "Modify Defect" button. Alternatively, you can pipe the output of findbug to batchbug to repair one field or simple call batchbug by itself. 
  # batchbug options -i bug-id
-or-
  # findbug options | batchbug options
Because batchbug updates the database for each record it processes, it is inefficient if the output of findbug produces more than a few bug numbers. Batchbug will send mail to the submitter if "Notify submitter" is "Y".
Some useful options:
-n Suppress email notification.
-l   seconds Attempt to obtain a lock on the defect before modifcation every 5 seconds up to seconds.
-s Create a new defect.
-b   filename Take the record numbers from the specified file.
-i   identifier Only modify the specified Identifier.
-t   template Use the specified template instead of the one belonging to its Class.
-d   filename Send the output to the specified file instead of updating the database.
-e   path   title Specify an enclosure to add. Give the path to the enclosure file and a name for it.
-r   old-name   new-name Rename the specified enclosure.
-R   enclosure Delete the specified enclosure.
fieldname   value Add a new field to the defect.
If you want to modify field values en masse, use command-lines similar to the following. See the findbug and patchbug man pages for the many options and usage. 
  # patchbug options { -b filename | Identifier }
-or-
  # findbug options | patchbug options
Patchbug options (must use -a or -d):
-t Update the defect's timestamp.
-a   fieldname   value Modify the value of fieldname.
-d   fieldname Remove fieldname from the record.
Remember that patchbug does not update the database, so when the modifications are complete, you still need to run "adminbug dbms". Also, if moving between classes, remember to change to a new project as well, and vice versa.

Back to the INDEX.
Move bug reports between servers.
Unfortunately there is no straight forward way to move a set of bug reports to a different DDTS server. The following steps will work but are tedious. If there are many to be transferred, the editing steps would best be automated with a script and sed commands. This procedure assumes that the same master.tmpl file is used on both servers.
1) Copy all the flatfiles in question from the ~/ddts/allbugs/* directories on the old server to a temporary location on the new server.
2) Run rmbug on the bug reports on the old server to delete them.
3) On the new server, determine the next bug number to be assigned by examining the ~ddts/conf/def.seq file.
4) Rename each of the newly moved bug report files to sequential numbers beyond that listed in the def.seq file using the same site id that is on the new server.
5) Edit all the bug reports and change the following fields (and any others that depend on names on the old server) to the appropriate new values:
Start
Identifier
Project
Class
End
6) Move the newly named/edited bug report flat files to the appropriate subdirectory of allbugs. Ensure they each have 664 permission.
7) Edit the def.seq file to the new next available bug number.
8) Run "adminbug dbms" and test the new reports.

Back to the INDEX.
Clone a bug report.
To clone a bug report, view the record and click on the "Clone" button at the bottom of the page. This will bring up a page asking what project to send it to. It will not be a complete clone though, as the bug report is reset back to the New state. However, this can be customized via the clone.prompt file in the class directory. Links are not copied.
NOTE: Ensure the project that the record is being sent to belongs to a class that uses the same (or similar) master.tmpl file as the originating class.

Back to the INDEX.
View a bug report.
In DDTS 4.0/1 webddts, Query by ID.
As of DDTS 4.5 webddts, the bug number can be referenced directly from the "http://" line in the web browser: http://hostname/ddts/ddts_main?id=identifier
In DDTS 4.5, Query & Report -> View Defect:
In xddts, Select -> Select Project, Class & State... (use the keyboard arrows to surf the index)
From the CLI: 
  # dumpbug identifier
-or-
  # findbug options | dumpbug
-or-
  # dumpbug -b buglist
Some useful dumpbug options:
-m Use to protect special characters if sending output to a mail program.
-n Suppress the row of asterisks that normally accompanies each record.
-h Convert output to simple html.
-r Suppress the printing of enclosures.
-t   template Specify an alternate template file (default master.tmpl).
-R Raw dump of record. Forces -n and ignores -t.

Back to the INDEX.
Create a parent/child relationship (link).
In webddts, view the record to be either the parent or child. You must have write access to both tickets. At the bottom of the ticket, click on the Links button. Simply type the name of the parent(s) and children. If there is more than one, place a space between the IDs.

Back to the INDEX.
Customize a parent/child relationship.
Nothing yet!

Back to the INDEX.
Queries (DDTS 4.1).
In DDTS 4.5+, Query & Report.
In DDTS prior to 4.5, to run a query from the web interface, click on the either the "Query" or "Query ID" buttons. The "Query ID" button is a basic request for a specific bug number, which you must know apriori. The "Query" button has four options: Simple, Complex, Form, and String.
Simple Allows basic search criteria.
Complex Allows a search based on selected fields.
Form Allows a search based on ranges of field values.
String Based on the syntax of the findbug command.
Access queries through the "Query & Report" button on the webddts front page. If a search is to be repeated often, the parameters can be saved.
The queries are saved in a binary file called ~ddts/www/user_prefs/username. To view one of those files use the dumpdbm command while inside the directory. This is also the file that contains the order of the output fields set via Defaults in the "Set Query Index Fields" button. You can Query on an existing saved query or Create one. Shared queries show up for everyone, but can only be created by the ddts user.
The saved queries are brought forward and reformatted during a 4.1-4.5+ upgrade. If a saved query could not be reformatted properly, it will still show up as a Saved Query with an asterisk next to it and will run, but cannot be edited. In DDTS 4.5, you can now run queries across all classes by searching the special "ALL" class. However, for the query to work, the ALL class master.tmpl must contain all fields from the other class's master.tmpl files on which you would like query.
Queries can also be run from the command line using the findbug command. The syntax for it can be simple or very complex. See the DDTS findbug man page for a complete list of options.

Back to the INDEX.
Create or modify a report.
The reports that are accessible through the web interface "Reports" button are scripts that live in ~ddts/bin. The name that appears in the menu is equated to a specific script via the ~ddts/class/$Class/report conf file; that is, the list of available reports is class dependent. Each of the reports listed in that conf file point to a specific script. The shell script, say dawk01.sh, is responsible for the findbug query and in turn calls a corresponding dawk01 awk script that formats the output. The output can go to the web browser, a file, or directly to a printer.
To modify a report, simply edit the shell script to change which bug reports are being reported on and/or edit the awk script to change how the output is formatted/filtered.
To create a new report, add an appropriate line to the report conf file in the class/$Class directory that points to your new script.
In DDTS 4.5+, you can now generate gif images directly from the report page.

Back to the INDEX.
General security.
If the CM administrator or manager wants to ensure that nobody can transition a state unless they are authorized, the DDTS webpages will have to have password security. That is, without security anyone can log in to DDTS as anyone else and transition a bug report posing as that other person. This section will set up password authentication for the DDTS website. The passwords discussed here are in no way tied to the general UNIX login password system. This page contains security implementation steps for the Apache and Netscape web servers. The Apache web server is free. The Netscape web server is free for a test drive only. It will need to be purchased if the intent is for permanent use.

Back to the INDEX.
Apache
The following steps were written for the Apache (NCSA) web server 1.3.9; which is assumed to already be installed and running with your DDTS installation. The latest Apache web server can be downloaded from http://www.apache.org/httpd.html.

Login as root in one window and ddts in another.

As root, modify the access.conf (or httpd.conf on new Apache versions) file.

Add the following to the end of web-server-home/(conf or etc)/(access.conf or httpd.conf). 
    <Directory ddts-home>
    AuthName     "DDTS Users"
    AuthType     Basic
    AuthUserFile ddts-home/.htpasswd
    <Limit GET>
      require valid-user
    </Limit>
    </Directory>
AuthName can be any title you want for the username/passsword window.
The AuthUserFile can go anywhere, but should reside with the secured webpage for clarity.

Initialize the password file.

As ddts, cd to where the .htpasswd file is to be located and type the following. The username does not have to correspond the a user's UNIX login. However, to facilitate the sending of mail notices from DDTS, they should be the same. 
  # web-server-home/(support or bin)/htpasswd  -c .htpasswd  username
  # chmod  644  .htpasswd
For subsequent additions of users, leave the   -c   option off; it's only used once to create the initial .htpasswd file.

Restart the http daemon.

There should be a start script in /etc/init.d on SVR4 systems: 
  # cd /etc/init.d
  # ./httpd stop
  # ./httpd start
If not, find the httpd daemon's PID owned by root. A "kill -1" will not totally kill the daemon, but only force it to reread its configuration files. 
  # kill -1 PID
Allow users to change their own DDTS password.
Even though the the web server facilitates authentication for web pages, there is no way for a user to change their own password. All of the below mentioned pieces are available in a tar file change_passwd.tar.Z.
1) As root, in a directory, such as /tmp, extract the tar file.
2) As root, cd to the HTTPD-User-Manage-1.52 directory and: 
  # perl Makefile.PL
  # make
  # make test
  # make install
3) As ddts, modify the ~ddts/www/perl_modules/WTForm.pm file. For installs prior to 4.5, place the following lines at the end of the list of .gif files that show up in the toolbar. 
<p>
<a href="/cgi-bin/user_manage.pl?realm=DDTS" target="new_window">
<img src="$ENV{WT_IMAGEDIR}/chpasswd.jpg" border="0" alt="Password" name="Password" width=50 height=50></a>
For 4.5 and later, place the following in the toolbar subroutine. Place immediately above the line that reads "print TOOLBAR $self->html_footer();". 
print TOOLBAR <<EOT;
<p>
<a href="/cgi-bin/user_manage.pl?realm=DDTS" target="new_window">
<img src="$ENV{WT_IMAGEDIR}/chpasswd.jpg" border=0 alt="Change Password" name="Change Password" width=50 height=50></a>
<br><center><font size=$fontsize>Password</font></center>
EOT
4) As ddts, place the chpasswd.jpg file in the ~ddts/www/images directory and give it 444 permissions.
5) As root, place the user_manage script in the web-server-home/cgi-bin directory as user_manage.pl and give ownership to ddts:ddts with setuid 4755 permissions.
6) As root, configure the user_manage.pl script. At the least, the following will need to reflect your configuration:
$CONFIG_FILE The path to your realms.conf file.
$ADMIN_GROUP The name of the DDTS administrators group. Most likely "ddts".
7) As root, create/modify the web-server-home/conf/realms.conf file and ensure the following. Ensure permissions on that file are at least 644. 
<Realm DDTS>
        Type            text
        Authentication  Basic
        Users           ddts-home/.htpasswd
</Realm>
8) As root, ensure the perl script extension is recognized by adding a line such as "AddHandler   cgi-script   .pl" to the web-server-home/conf/(srm or httpd).conf file.
9) As root, have the httpd daemon reread its config files. 
  # kill -1 `ps -ef | awk '/httpd/{ if($1 == "root") print $2 }'`
10) As ddts, update the WebDDTS interface. 
  ddts> webconfigure
11) Test the results. After the webconfigure is complete and you are once again at the DDTS front page, there should be a "key" icon in the toolbar on the bottom left. If you click on that icon, a second page will appear asking for confirmation of your current password. Once the Submit button is pressed, the next page should prompt for a new password. Once the Change is pressed, it should report "Password for username has been changed.".

Back to the INDEX.
Netscape
The following steps were written for the Netscape Enterprise web server 3.63 SP3; which is assumed to already be installed and running with your DDTS system. The latest Netscape web server can be downloaded from http://www.iplanet.com/downloads/testdrive/detail_161_243.

Open up two windows, one as root and the other as ddts.
Modify the obj.conf file.

As root, change directory to web-server-home/https-server_name/config. Add the following lines at the top of the obj.conf file, right after the other Init directives: 
Init fn="load-modules" funcs="htaccess-init,htaccess-find" \
  shlib="web-server-home/plugins/htaccess/bin/htaccess.so"
Init fn="htaccess-init"
Add the following line to <Object name="cgi">. Insert above any ObjectType or Service directives. 
PathCheck fn="htaccess-find"
Place the following in a file called .htaccess in ddts-home/www. Ensure it has at least 644 permissions. 
AuthName     "DDTS Users"
AuthType     Basic
AuthUserFile ddts-home/.htpasswd
<Limit GET>
    require valid-user
</Limit>
AuthName can be any title you want for the username/passsword window. The AuthUserFile can go anywhere, but can reside with the secured webpage for clarity. However, if security is of prime concern, the password file should be kept in a non web-served directory.

WARNING! Modifying the obj.conf file by hand will cause the Netscape Server Administration browser to issue a warning the next time the obj.conf is modified from that interface. Simple do what it says and select "Undo" the first time through. This will save your manual changes permanently. Unfortunately, you will have re-enter the modification you were just trying to do. After that, your manual modifications and all modifications from the Administration tool will be saved. If you don't select "Undo" the first time through. This will save your manual changes permanently. Unfortunately, you will have re-enter the modification you were just trying to do. After that, your manual modifications and all modifications from the Administration tool will be saved. If you don't select Undo when it warns you to, the change you are working on at the moment will get recorded, but all your manual changes entered previously will be lost.

Restart the nt-https daemon.

Generally, there is a startup script in the /etc/init.d directory for starting and stopping the web daemon. This would have been set up when the web server was installed. If not, find the web daemon's PID owned by root (or other special user). A "kill -1" will not totally kill the daemon but only force it to reread its configuration files. For Netscape Enterprise, the daemon is named ns-https. 
  # kill -1 PID
Alternatively, one can start the Netscape Server Administration page and stop & start the server there.

Initialize the .htpasswd file.

As ddts, one can simply use a copy of an existing password file, pared down so that there are only two fields: username:encrypted-password. However, if you want to create username passwords from scratch, you will need the htpasswd executable (use <Shift>-left_click). 
  # cd ~ddts
  # htpasswd -c .htpasswd username
The -c option is only needed upon initial creation of the .htpasswd file. Subsequent username additions still need the passwd filename as an argument, just without the -c option. Ensure the .htpasswd file has at least 644 permissions.

Back to the INDEX.
Create a new STATE.
~ddts/class/class/master.tmpl:
1) Add the new state to the "case" statement in the field called STATE.
2) Add the state fields in the template at the location it appears in the defect life cycle. That is, if the new state called VERIFY is logically between the RESOLVE and CLOSE states, place the code between those two in the master.tmpl. Use an existing state's fields as a starting point.
3) Add a "set group_fields" line at the end of the template. The actual name of that field is arbitrary, as it gets unset anyway. Again, use an existing field as a model.
~ddts/class/class/states:
Create a set of entries related to the new state. See states file or the DDTS Admin manual for more information.
~ddts/class/class/statenames:
This file simply maps the state letter to English words. See statenames file or the DDTS Admin manual for more information.
~ddts/class/class/admin.tmpl:
These files are templates used by the adminbug subcommands aprj (add project) and mprj (modify project) to prompt the user for information about the project control and notify. The files ending in 2 are for notfity and the ones ending in 3 are for control. In most installations the aprj2.tmpl & mprj2.tmpl will be identical; likewise for aprj3.tmpl & mprj3.tmpl. Simply use the existing text as a model to add your new state.
~ddts/class/class/user.index (xddts only)
Add a user index template file for the new state to this directory. Use an existing template as a model.
~ddts/class/class/summary.print (xddts only)
Add a template to this directory to define how a summary should be printed. Use an existing template as a model.
~ddts/bin
Modify the report awk scripts to include the new state letter. Most likely to need modifying are: dawk01, dawk04, dawk08 and dawk06.sh. Remember to save a backup of your modified versions somewhere outside the bin directory, as these will be overwritten if DDTS is upgraded.
~ddts/dbms/ddts/database.cfg:
This file contains a mapping of the actual fieldname to that used by the database. The left column is the name of the fields exactly as they appear in the master.tmpl. The right column is the mapped version of that name. The mapped version can only contain lower-case letters and underscores.
~ddts/dbms/ddts/schema_file:
This file contains the names of the fields as they were mapped in the database.cfg file. The left column is the fieldname and the right is either an integer denoting the number of characters in that field, or it's the word "datetime" to denote this is a date field.
NOTE: The new state will run fine without modifying the database.cfg and schema_file files, but you will not be able to see your new fields when doing queries. Also, remember to run "adminbug dbms" if either of those files are modified.

Back to the INDEX.
states file
The ~ddts/class/class/states file controls which state transitions are allowed by anyone at all. Whether a particular user can transition to a certain state is handled on a project by project basis in a ~ddts/projects/project/proj.control file. The states file is a simple set of three letters (triplet) that denote the states being controlled. Column 1 is the state from which you are transitioning. Column 2 is the state to which you are allowing a transition. Column 3 is a state through which the transition must traverse before getting to its destination state. For instance, a transition might be from state R (Resolve) to state C (Close). The states file entry for this would simply be "R C C".
However, if you mandate that before a ticket can be closed, the resolution must be verified, you can have the transition traverse another page/state V (Verify). That page may contain a field that can only be filled in by a user other than the resolver. The states file entry would then be "R C V". This same functionality could also be implemented with the following set of states file lines:
R V V
V C C
Comments are allowed in the states file with a caveat. Any line that does not begin with three capital letters (triplet) is considered a comment and ignored by the system. That is, there is no need to place a pound sign "#" a the begining of the comment. However, there is the oddity that if you comment-out one of the triplets it may or may not actually get commented-out. For instance, if your commented-out triplet is the last one for that state, it can be simply commented-out with a pound sign at the begining of the line. However, if there are any triplets after that commented-out line, the commented-out one will still show up. An example might be: 
...
C F F 
#C V V      (does not show up)
...

...
C F F
#C V V      (is still seen as a valid transition)
C A A
...

...
C F F
Removed by EJO 990807. C V V   (is a valid comment)
C A A
...
NOTE: The STATE letters S, N, & F are reserved and cannot be used for states other that their predefined ones.

Back to the INDEX.
statenames file
This file simply maps the state's letter to English words used by the DDTS system and an attribute character describing the state. The first column is the state letter, the second is the attribute character (see below) and third and fourth are plain names for the state in the present and past tenses respectively. 
s   Pseudo.  Goes through it, but does not stay. (Submit)
u   Unresolved.  Generally any state before it gets assigned. (New)
a   Unresolved.  Any state already assigned but no yet resolved. (Assign)
r   Resolved. (Resolved)
x   Dead end.  Not part of the main stream. (Duplicate)
o   Dead end.  Not part of the main stream, but should be included in metrics. (Postpone)
Back to the INDEX.


Return to the home page .

This page last modified: 09/20/2006