Topics of interest to OpenTrack system administrators include these:
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
otadmin -p proj -u xxx
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
otUnlockCR proj xxx
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.
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.
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
/etc/otqm -p xxx
- 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
/project/otbin//otCreateHeadHistFile -p xxx
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
rm headdb histdb
/project/otbin//otSplitHeadHistFile -p xxx
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.
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.
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).
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
mkdir /project/ot/foo
- 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.
cp /project/ot/motif/motif.def /project/ot/foo/foo.def
cp /project/ot/motif/motif.template.def /project/ot/foo/foo.template.def
- Edit foo.template.def
by changing the string 'motif' in the type field to 'foo'.
Project Name~(motif)~~proj~PROJ~5
^^^^^
- 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
project name: foo
- 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".
Make other changes as necessary with the help of manual page ot_defs.5,
section
"Project definition file".
- Create a file number under the new database base directory
containing the string '000001':
echo '000001' > /project/ot/foo/number
-
Create a directory named otdqueue under the new database base
directory
mkdir /project/ot/foo/otdqueue
- 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:
/etc/otKwikPix -p proj
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:
co -l
modify the file
ci -u
otcp
- 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
osfmount otbin
Give the following commands:
rm /project/ot/(OTproj)/{head,hist}db
rm /project/ot/(OTproj)/HeadHistFile
/project/otbin//otCreateHeadHistFile -p
/project/otbin//otSplitHeadHistFile -p
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.
- Add the following line to
/etc/inetd.conf
if the server is an ULTRIX system:
otd stream tcp nowait /etc/otd otd
or the following line if the server is an OSF/1 system:
otd stream tcp nowait root /etc/otd otd
Add the following line to /etc/services
otd 9560/tcp
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:
su
cd
cp otKwikPix /etc/otKwikPix
ln /etc/otKwikPix /etc/otSlowPix
cp otd otqm otAfterBoot otcl /etc
- Add the following line to /etc/fstab if the server is an ULTRIX system:
/u1/otdefs@ot8:/project/otdefs:rw:0:0:nfs:wsize=1024,rsize=1024,soft,retry=5:bg:
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)
cp countTable.tcl otAdmin.tcl otadmin /project/ot/tcl
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).
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.