NAME
batchbug - add or modify multiple fields in one or more bugs
SYNOPSIS
batchbug [-n] [-l lockwait] [-s | -S | -b bugbox | -i bugid]
[-t templatefile] [-d debugfile]
[-e path title] ... [-r oldtitle newtitle] ...
[-R title] ... [fieldname value] ...
DESCRIPTION
The batchbug utility is used to create or make changes to
one or more ClearDDTS bug records without interactive I/O,
that is, in batch mode. The batchbug utility is useful for
automated test scripts or hardware diagnostics that need to
automatically submit defects without human interaction.
Unlike patchbug(1), the batchbug utility immediately applies
the changes to the ClearDDTS database, and by default,
causes appropriate notification E-mail to be sent to users
regarding the changes.
The -n option suppresses all notification E-mail about the
transaction(s) performed. It is suggested that this option
be used when processing large numbers of bugs. Note also
that patchbug(1) may be more appropriate for large numbers
of bugs.
The -l lockwait option requires batchbug to acquire a lock
on the specified defect before modification. If the record
is already locked batchbug will attempt to acquire the lock
every 5 seconds up to lockwait seconds. If lockwait seconds
expires and the record lock has not been acquired batchbug
returns with an exit status of 2.
The -s option specifies that a new bug is to be submitted
instead of modifying an existing bug. In this case,
batchbug will allocate a new record ID number and
automatically initialize the "Start", "End", and
"Identifier" fields with that number.
The -S option is like the -s option except that the newly
created Identifier field is printed to stdout upon
completion.
If the -b bugbox option is specified, batchbug reads record
IDs from the named bugbox file, and makes the same changes
to each specified defect record.
If the -i option is specified, the bugid argument is the
identifier of a bug record to be modified (for instance,
XXXxx12345). Only one bugid can be used with the -i option.
If none of the -s, -b, or -i options are specified, batchbug
reads bugids from the standard input and makes the same
changes to each specified defect record.
The -t templatefile argument specifies the name of a
template file (formatted as described in template(5)) to be
executed. The templatefile can be used either to initialize
the various required defect record fields of a newly
submitted defect (the -s option), or to update fields in an
existing defect. Care should be taken with the templatefile
not to use the "%s" directive as this will cause interactive
I/O to occur and thus frustrate the automatic (batch) nature
of batchbug(1).
The -d debugfile argument specifies the name of a debug file
into which the resulting defect is placed (one defect only).
No change is made to the database. This may be used for
debugging run strings and template files.
The -e option specifies that an enclosure is to be added to
the defect record. The path argument is the name of the
file to be added as an enclosure. The title is the title
for the enclosure. The path and title arguments must be
specified as pairs. Note that if title has embedded blanks
it must be surrounded by quotes ("") so that the shell
passes it as one parameter. If an enclosure with a title of
title already exists in the defect record it is overlayed
with the new enclosure file specified in path.
The -r option allows you to rename an enclosure from
oldtitle to newtitle. An enclosure named oldtitle must
exist and there cannot be an enclosure already named
newtitle.
The -R option allows you to delete an enclosure named title.
An enclosure named title must exist first.
The fieldname and value arguments must be specified as
pairs. Each fieldname must be followed by a value. Note
that if value has embedded blanks it must be surrounded by
quotes ("") so that the shell passes it as one parameter.
These fieldname and value pairs are applied to the defect
record before the templatefile is executed thus these values
may be used to change the defect record and also used as
flags passed into the templatefile to guide its executation.
If fieldname already exists in the defect record it is
overlayed with the new value. The batchbug utility will
change each existing fieldname in the defect record to have
the corresponding value, or if fieldname doesn't exist in
the defect record, batchbug will add it.
After making the modification(s) to each defect record, the
record's Timestamp field is incremented to distinguish it
from previous copies of the same record. Then, the defect
record is passed to the bugs.in(1) daemon for incorporation
into the ClearDDTS database. Note that machines subscribing
to the Project associated with the defect will also receive
the new copy.
If batchbug is run without any parameters it simply forces
the ClearDDTS system to examine all the work directories to
see if there is any pending work.
WARNINGS
Note that batchbug modifies defect records without the
validity checking provided by the ClearDDTS master.tmpl
template file mechanism.
Be careful with the run string! The path and title must be
specified as pairs and all of the title should be enclosed
in quotes (""). In addition, fieldname and value must be
specified as pairs and all of the value should be enclosed
in quotes (""). An incorrectly specified run string can
damage a bug record.
The Updated-by field is not modified unless explicitly asked
to do so. This may generate E-mail notification with an
incorrect Subject line in some cases. If you wish to be
logged as the person who made the last change, you should
update this field in addition to the others that you modify.
This utility is powerful and therefore dangerous. Make sure
you understand what batchbug does before you run it. Note
that Appendix B of the ClearDDTS Administration Manual
describes the fields that must be modified to move a bug
from state to state.
EXAMPLES
The following modifies bug CMMaa00030 by executing template
file /tmp/hello, adding the enclosure in file /etc/passwd
with a title of Big Problem. It also adds a field called
Foo with a value of Bar Bar. A lock on CMMaa00030 is
required before the transaction is made.
batchbug -l999999 -i CMMaa00030 -t /tmp/hello \
-e /etc/passwd "Big Problem" Foo "Bar Bar"
See the ~ddts/class/software/batchbug directory for batchbug
template files that will make all state transitions shipped
with ClearDDTS.
See ~ddts/class/software/batchbug/* directory for examples
of how to use batchbug. In particular, look at the README
file.
BUGS
The batchbug utility should be run on the server where
ClearDDTS is installed. It may be run on a client system,
however, care should be exercised not to run afoul of the
NFS client side kernel file cache. The NFS client system
keep an in memory cache of files. Thus a batchbug change to
a file, immediately followed by another change may cause the
normal read-modify-write cycle of batchbug to read old data
and attempt to update from old data. Run batchbug on the
client via rsh(1) (or remsh(1)) if possible.
We have only seen this problem once in over two years in an
application that made repeated changes to the same bug over
and over again (a poor design). It is very unlikely that
you will see the problem. This problem can be eliminated by
using a 5 second sleep(1) between calls to batchbug or by
modifying the default client side mount(1) paramenters. See
the mount(1) man page where the ac* parameters are discussed
with regard to the NFS cache.
SEE ALSO
bugs.in(1), ddtsd(1), patchbug(1), template(5),
~ddts/class/software/batchbug/*
Appendix A: Contents of a Defect Record in the ClearDDTS
Administrator's Guide