Unlocking a CR

If a user gets a message that a CR is locked and cannot be updated, you can unlock it in two different ways.

Give the following command, where proj is the project and xxx is the CR number in question You will be prompted with an ls listing of the CR and its .edit file, which represents the copy that the user is working on. If the date of this .edit file is recent, another user may really be updating it currently: if so, you should not unlock it. Otherwise respond with 'y' when prompted.
The otadmin command may not have been installed on the server side too. If so, it will fail. In this case, log into the server machine for the project. (Find this either in the project's definition file in /project/ot (for example, /project/ot/motif/motif.def) or by reading about OT server machines at OSF.) Then give the command As before, you should check the date of the .edit to be sure that you won't remove a CR which another user is working on.

Log files

The OpenTrack otd server (/etc/otd) appends all the commands received from the client to a log file in /project/ot/serverV3.log. This size of this file grows in proportion to the number of CRs entered and updated, as well as their length. Queries cause only a few lines to be appended to the log file.

If there are problems with entering or updating CRs for a project, be sure to check the available space on the partition which contains /project/ot . If the log file has been very large, then give the following command

otadmin -p proj -x otNewLog This simply deletes any backups of the server log, moves the existing serverV3.log file to a backup form and starts a new logfile. See the manual page otadmin.1 for more information on this command.

Checking the OT queue directories

If you see that enters and updates are not reflected in short reports, look in /project/ot/xxx/otdqueue (where xxx is the name of the project in question) to see if there are a lot of old qi files. If there are, then there may have been a problem with the otd server. In this case otqm may have failed to complete its task of updating the headdb and histdb files in the project base directory. There are two methods for attacking this problem.

The first involves restarting the OT queue manager otqm. It takes a while to get the project consistent again this way, but there is less chance for complications. Follow these steps.

Make sure that otqm is not still running by running a process status command. If it is running and you can verify that it is hung - remember that it can take a very long time for the headdb or histdb files to be rewritten - then kill it.
Look for a file named otqm.lok in the project base directory. If it exists, remove it.
Give the command
You should be able to see the headdb and histdb files being written. When this is done, you may need to restart the otKwikPix server.

If this method does not work, a quicker but more complicated way is to use the otCreateHeadHistDbFile command (found in /project/otbin/xxx/ where xxx is a machine architecture). Follow these steps.

Disable access to the project.
Remove all the qi files in otdqueue.
Remove HeadHistFile (this file may not be present).
Give the command This should create a file HeadAndHist containing all the information in the header and history sections of the project's CRs.
When this command has completed, give the following commands This splits the HeadHistFile into headdb and histdb. The HeadAndHist is not needed at this point and may be deleted.
Edit the wrapper to enable project access and restart otKwikPix.

If there are few users on the system, you might try this operation without disabling access, but you would have to compare the times of the HeadAndHist file and the headdb file to insure that no changes had been made during the generation of HeadAndHist.

Restarting the otKwikPix server

Some projects expect the performance-enhancing otKwikPix server to be running all the time. If performance becomes slow you should make sure that the otKwikPix server is still running for that project. Do this by giving the following command.

otadmin -p proj -k See the manual page otadmin.1 for more information on this command.

Disabling access to an OT project

You disable access to a project by making a change to the OT wrapper: that is, to the client-side of things. The OT wrapper is in the sources in /project/ot/build/ot3.0.2/src/util/scripts/otWrapper.sh. The ot and ot_bugs entries in the directories /project/tools/bin/(platform) are hard links to the OT wrapper. Expressed differently, when you edit any one of them - for example /project/tools/bin/i386.OSF1/ot - you have edited all of them. Do not copy on top of them or "move" (mv) them because this means the i-number in the directory will be changed. Just invoke the editor of your choice and edit any of the ot or ot_bugs images.

The following lines appear as commented out in the wrapper:

# ot) projDisable=y; projName=ot ;; ... # ot|-pot) projDisable=y; projName=ot ;; When you know which project you want to disable, make its entries in these two case statements look like this. You can preserve the 'enabled' lines for this project by commenting it out. When you are ready to enable it again, remove the comment signs from the start of the original lines and delete the lines you added (with projDisable in them).

How to create a new OT database

The manual page ot.1 describes how to create an OT database. See the section "Using OT for personal databases". Here is a summary of the steps for the most typical case.

Choose a database name ("foo").
Choose a server machine on which the CRs are to be stored and log into that machine. If the directory /project/ot does not exist on this machine, create it. You probably should check to see if the OT server is installed on this system. There should be an otd entry in /etc/inetd.conf. If not, see "How to install OT on a server".
Create a base directory for the new project under /project/ot using the database name, for example
Pick an existing OT project as a model and copy the project definition file (for example, /project/ot/motif/motif.def) and the project metatemplate file (for example, /project/ot/motif/motif.template.def) into the new project's directory under the new project name.
Edit foo.template.def by changing the string 'motif' in the type field to 'foo'.
Make other changes to foo.template.def as required to get a template specific to the project. For a description of the fields in the metatemplate file see manual page ot_defs.5, in the section "Project Metatemplate File".
Edit foo.def by changing
- the project name field value to the new database name, for example
- the project leader field value to the mailname of the user who should receive mail after every change (enter or update) to the database
- the server host to the name of the server for this database
If you have copied the project definition file from another project, there may be TCL procedures defined at the end of this file. They may make references to fields in the metatemplate which you have removed, or to data files which you do not have in your project. These procedures are never mandatory so you may actually remove them until you have time to read the information in manual page ot_tcl.1, section "Configurable procedures".

"Project definition file"

Create a file number under the new database base directory containing the string '000001':
Create a directory named otdqueue under the new database base directory
If the project definition file makes reference to other files in the type definitions (e.g., "File type...") or in the TCL procedures, copy these files from the source directory and change the references in the project definition file accordingly (new directory name).
If otAfterBoot is executed in the server's /etc/rc.local file (ULTRIX systems) then add this project to the list of projects in its argument list.
If this project is large enough to require enhanced query performance add the following line to the /etc/rc.local file:

Modifying the project definition files for a project

Here are the steps to take when updating project definition files:

You should really disable access to the project while carrying out this procedure.
Check to make sure there are no files in the otdqueue directory. If there are, remove them.
rlogin to the corresponding OT server machine
cd /project/ot/(OTproj)
For each file to be modified, do the following:
If you have added lines to the metatemplate, deleted lines from it or altered their order, you MUST rebuild the headdb and histdb files. Do this by running the otCreateHeadHistFile and otSplitHeadHistFile programs. If /project/otbin is not visible, then Give the following commands: The otCreateHeadHistFile creates the file HeadHistFile and the otSplitHeadHistFile splits it into headdb and histdb. This can take anywhere from under a minute for a small (under 200 CRs) project to over a half-hour for a larger project (more than 10000 CRs).

After changing a metatemplate, each time a user updates a CR, ot automatically 'collates' the data in the CR to update to match the metatemplate. You may

remove blank lines from the metatemplate
remove non-blank lines from the metatemplate
re-order fields in the metatemplate

without having to worry about converting existing data to match the new format. Rearranging field order in the metatemplate should not be a problem. Note however that all header lines in the individual CRs are displayed on queries or enter/update operations, regardless of whether the field is still in the metatemplate or not. If you remove a field 'Severity', CRs already entered will still show that line regardless of whether there is data associated with it or not, but it will be placed at the end, after the header lines corresponding to fields still in the metatemplate.

What would cause problems later is one of the following actions:

Removing elements from an enumerated type in the metatemplate, e.g. Status now can be one of: open, closed, defer. If you update the metatemplate by removing 'defer' from the list of values for this field, all existing CRs with status 'defer' will be invalid for this field when updated again. We have no mechanism for handling this apart from the obvious one (update all the deferred CRs to a new state).
Add mandatory fields to the template. If you add a mandatory text field 'Site', none of the existing CRs will have this field before update. During update they will get the field with a blank value. The user must either specify a value at update time, or the OT admin would have to run an OT update for every CR lacking a value for this field.

How to install OT on a server

Add the following line to /etc/inetd.conf if the server is an ULTRIX system: or the following line if the server is an OSF/1 system: Add the following line to /etc/services If the projects served by this machine have values in the server port line other than 9560, then for each of these ports add a line like the one above with the port number substituted for 9560.
Install the OT binaries in /etc as follows:
Add the following line to /etc/fstab if the server is an ULTRIX system: This will ensure that the project definition repository is accessible from the OT server machine.
Create a directory /project/ot if none exists, as well as /project/ot/tcl, and copy the following scripts from the source directory (under util/scripts)

How to run a metric report

To run a monthly metrics report, give these commands, where xx is a digit corresponding to the month.

cd /project/otmisc/metrics/Scripts ./doMetrics.sh mv metricsReport ../countTable94xx.txt

See the dce and nmo directories under /project/otmisc/metrics/Scripts and their use in e.g. countTableDce.sh to learn how to query a project when the server's directory is not exported in /project/otdefs. You just create a directory in OT_DBPATH with the files and directories in the server project base directory (i.e., project definition file, project metatemplate file) but you should not include data directories here (i.e. d00, d01, etc).

How to configure a database with TCL procedures

Altering OT behavior on a project-specific basis is described in the manual page ot_def.5, "Configurable procedures". There are also examples of these procedures in the manual page. Here are the types of configuration you can provide.

Validate by procedure. Validation by default is against type (either built-in types like mailname, text etc or by user-enumerated lists), but by defining validateDepend you can validate a CR by checking interdependencies among fields (for example, many projects require a responsible engineer for a closed CR).
Notification configuration. Every value of type mailname is added to the To: list for OT notification, but you can either turn off the default behavior with the notifyExplicit procedure or add to the list with notifyDepend procedure.
Make changes to the CR after validation. You can change values at the server end immediately before a commit with the postProcess procedure.
Configure for use with the ode2ot utility. See also the manual page ode2ot.1.

Note that the TCL library in OT V3.0.2 has not been secured by any mechanism or standard (cf. safe-tcl) so the primitives open, close, etc are available to the OT TCL script writer.