Index of Section 1 Manual Pages
| Interix / SUA | query-pr.1 | Interix / SUA |
query-pr(1) GNATS User Utilities query-pr(1)
NAME
query-pr - query problem reports in the GNATS database
SYNOPSIS
query-pr
[--output file | -o file]
[--list-databases] [--list-fields]
[--list-input-fields]
[--responsible-address address]
[--field-type type]
[--field-description description]
[--valid-values values]
[--format format | -f format]
[--full | -F] [--summary | -q]
[--database database | -d database]
[--and | -&] [--or | -|]
[--expr expr]
[--debug | -D]
[--help | -h] [--version | -V]
[PR ...]
Non-network-mode options:
[--print-sh-vars] [--print-directory-for-database]
Network-mode-only options:
[--host host | -H host] [--port port]
[--user user | -v user]
[--passwd passwd | -w passwd]
Deprecated Options
[--list-categories | -j] [--list-classes | -J]
[--list-responsible | -k] [--list-submitters | -l]
[--list-states | -T]
[--category category | -c category]
[--synopsis synopsis | -y synopsis]
[--confidential confidential | -C confidential]
[--multitext multitext | -m multitext]
[--originator originator | -O originator]
[--release release | -A release]
[--class class | -L class]
[--cases cases | -E cases]
[--quarter quarter | -Q quarter]
[--keywords keywords | -K keywords]
[--priority priority | -p priority]
[--responsible responsible | -r responsible]
[--restricted | -R]
[--severity severity | -e severity]
[--skip-closed | -x] [--sql | -i] [--sql2 | -I]
[--state state | -s state]
[--submitter submitter | -S submitter]
[--text text | -t text]
[--required-before date | -u date]
[--required-after date | -U date]
[--arrived-before date | -b date]
[--arrived-after date | -a date]
[--modified-before date | -B date]
[--modified-after date | -M date]
[--closed-before date | -z date]
[--closed-after date | -Z date]
DESCRIPTION
Queries the GNATS database according to options and re-
turns either selected Problem Reports (PRs) or other re-
quested information. query-pr can query PRs located in
either a local database or via gnatsd.
PRs may be selected via the use of the --expr option, di-
rectly by number, or by the use of the (now deprecated)
field-specific query operators.
By default, query options are connected with a logical
AND. For example,
query-pr --category=foo --responsible=bar
only prints PRs which have a Category field of foo and a
Responsible field of bar.
The --or option may be used to connect query options with
a logical OR. For example,
query-pr --category=baz --or --responsible=blee
prints PRs which have either a Category field of baz or a
Responsible field of blee.
The use of these options is strongly discouraged, as they
will be deleted in the next release. The expressions
specified by the --expr option are much more flexible.
OPTIONS
--help, -h
Prints a (rather longish) help message.
--version, -V
Displays the program version to stdout.
--output file, -o file
The results of the query will be placed in this file.
--database database, -d database
Specifies the database to be used for the query. If
no database is specified, the database named default
is assumed. (This option overrides the database
specified in the GNATSDB environment variable; see
the ENVIRONMENT VARIABLES section for more informa-
tion.)
--list-categories, -j
Lists the available PR categories for the selected
database.
--list-classes, -J
Lists the available PR classes for the selected
database.
--list-responsible, -k
Lists the users that appear in the database's respon-
sible list.
--list-submitters, -l
Lists the valid submitters for this database.
--list-states, -T
Lists the valid PR states for PRs in this database.
The previous --list-* options are deprecated and will be
removed in the next release; their functionality can be
replaced with
query-pr --valid-values field
where field is one of Category, Class, Responsible, Sub-
mitter-Id, or State.
--list-databases
Lists the known databases.
--list-fields
Lists the entire set of field names for PRs in the
selected database.
--list-input-fields
Lists the fields that should be provided when cre-
ating a new PR for the currently-specified
database. The fields are listed in an order that
would make sense when used in a template or form.
--field-type field
Returns the data type contained in PR field field.
The current set of data types includes text, multi-
text, enum, multienum, integer, date, and text-
with-regex-qualifier.
--field-description field
Returns a human-readable description of the intend-
ed purpose of field.
--valid-values field
For fields of type enum, a list of valid values
(one per line) is returned. Otherwise, a regular
expression is returned that describes the legal
values in field.
--responsible-address name
The mail address of name is returned; name is as-
sumed to be a name either appearing in the
database's responsible list, or is otherwise a user
on the system.
--print-sh-vars
A set of /bin/sh variables is returned that de-
scribe the selected database. They include:
GNATSDB
The name of the currently-selected database.
GNATSDB_VALID
Set to 1 if the selected database is valid.
GNATSDBDIR
The directory where the database contents
are stored.
DEBUG_MODE
Set to 1 if debug mode has been enabled for
the database.
DEFAULTCATEGORY
The default category for PRs in the
database.
DEFAULTSTATE
The default state for PRs in the database.
--print-directory-for-database
Returns the directory where the selected database
is located.
--format format, -f format
Used to specify the format of the output PRs, See
FORMATS below for a complete description.
--full, -F
When printing PRs, the entre PR is displayed. This
is exactly equivalent to
query-pr --format full
--summary, -q
When printing PRs, a summary format is used. This
is exactly equivalent to
query-pr --format summary
--debug, -D
Enables debugging output for network queries.
--host host, -H host
Specifies the hostname of the gnatsd server to com-
municate with. This overrides the value in the
GNATSDB environment variable.
--port port
Specifies the port number of the gnatsd server to
communicate with. This overrides the value in the
GNATSDB environment variable.
--user user, -v user
Specifies the username to login with when connect-
ing to the gnatsd server. This overrides the value
in the GNATSDB environment variable.
--passwd passwd, -w passwd
Specifies the password to login with when connect-
ing to the gnatsd server. This overrides the value
in the GNATSDB environment variable.
--and, -&, --or, -|,
These options are used when connecting multiple
query operators together. They specify whether the
previous and subsequent options are to be logically
ANDed or logically ORed.
--expr expr
Specifies a query expression to use when searching
for PRs. See the QUERY EXPRESSIONS section.
The remaining deprecated options are not described here,
since their use is fairly obvious and their functionality
is completely replaced by the use of the --expr option.
(Some sort of shorthand option for querying fields may ap-
pear in the next release.)
FORMATS
Printing formats for PRs are in one of three forms:
formatname
This is a named format which is described by the
database (specifically, these formats are described
in the dbconfig file associated with the database).
The default configuration contains five such for-
mats: standard, full, summary, sql, and sql2.
The first three are the ones most commonly used
when performing queries. standard is the format
used by default if no other format is specified.
Use of the latter two are discouraged; they are
merely kept for historical purposes.
Other named formats may have been added by the
database administrator.
fieldname
A single field name may appear here. Only the con-
tents of this field will be displayed.
'"printf string" fieldname fieldname . . .'
This provides a rather flexible mechanism for for-
matting PR output. (The formatting is identical to
that provided by the named formats described by the
database configuration.) The printf string can
contain the following % sequences:
%[positionalspecifiers]s: Prints the field as a
string. The positional specifiers are similar to
those of printf, as +, - and digit qualifiers can
be used to force a particular alignment of the
field contents.
%[positionalspecifiers]S: Similar to %s, except
that the field contents are terminated at the first
space character.
%[positionalspecifiers]d: Similar to %s, except
that the field contents are written as a numeric
value. For integer fields, the value is written as
a number. For enumerated fields, the field is con-
verted into a numeric equivalent (i.e. if the field
can have two possible values, the result will be
either 1 or 2). For date fields, the value is
written as seconds since Jan 1, 1970.
%F: The field is written as it would appear within
a PR, complete with field header.
%D: For date fields, the date is written in a stan-
dard GNATS format.
%Q: For date fields, the date is written in an ar-
bitrary "SQL" format.
An example printf formatted query (note the quoting
of the whole format specification):
query-pr --format '"%s, %s" Synopsis State'
QUERY EXPRESSIONS
Query expressions are used to select specific PRs based on
their field contents. The general form is
fieldname|"value" operator fieldname|"value"
[booleanop ...]
value is a literal string or regular expression; it must
be surrounded by double quotes, otherwise it is interpret-
ed as a fieldname.
fieldname is the name of a field in the PR.
operator is one of:
= The value of the left-hand side of the expression
must exactly match the regular expression on the
right-hand side of the expression.
~ Some portion of the left-hand side of the expres-
sion must match the regular expression on the
right-hand side.
== The value of the left-hand side must be equal to
the value on the right-hand side of the expression.
The equality of two values depends on what type of
data is stored in the field(s) being queried. For
example, when querying a field containing integer
values, literal strings are interpreted as inte-
gers. The query expression
Number == "0123"
is identical to
Number == "123"
as the leading zero is ignored. If the values were
treated as strings instead of integers, then the
two comparisons would return different results.
!= The not-equal operator. Produces the opposite re-
sult of the == operator.
<,> The left-hand side must have a value less than or
greater than the right-hand side. Comparisons are
done depending on the type of data being queried;
in particular, integer fields and dates use a nu-
meric comparison, and enumerated fields are ordered
depending on the numeric equivalent of their enu-
merated values.
booleanop is either | [or], or & [and]. The query expres-
sion
Category="baz" | Responsible="blee"
is identical to the second query example with --or given
earlier; it selects all PRs with a Category field of baz
or a Responsible field of blee.
The not operator ! may be used to negate a test:
! Category="foo"
searches for PRs where the category is not equal to the
regular expression foo.
Parenthesis may be used to force a particular interpreta-
tion of the expression:
!(Category="foo" & Submitter-Id="blaz")
skips PRs where the Category field is equal to foo and the
Submitter-Id field is equal to blaz. Parenthesis may be
nested to any arbitrary depth.
Fieldnames can be specified in several ways. The simplest
and most obvious is just a name:
Category="foo"
checks the value of the category field for the value
"foo".
A fieldname qualifier may be prepended to the name of the
field; a colon is used to separate the qualifier from the
name. To refer directly to a builtin field name:
builtin:Number="123"
In this case, Number is interpreted as the builtin name of
the field to check. (This is useful if the fields have
been renamed. For more discussion of builtin field names,
see dbconfig(5).)
To scan all fields of a particular type, the fieldtype
qualifier may be used:
fieldtype:Text="bar"
searches all text fields for the regular expression bar.
Note that it is not necessary that the right-hand side of
the expression be a literal string. To query all PRs
where the PR has been modified since it was closed, the
expression
Last-Modified != Closed-Date
will work; for each PR, it compares the value of its Last-
Modified field against its Closed-Date field, and returns
those PRs where the values differ. However, this query
will also return all PRs with empty Last-Modified or
Closed-Date fields. To further narrow the search:
Last-Modified != Closed-Date & Last-Modified != ""
& Closed-Date != ""
In general, comparing fields of two different types (an
integer field against a date field, for example) will
probably not do what you want.
Also, a field specifier may be followed by the name of a
subfield in braces:
State[type] != "closed"
or even
builtin:State[type] != "closed"
Subfields are further discussed in dbconfig(5).
QUERY BY MAIL
query-pr can also be accessed by electronic mail, if your
version of GNATS is configured for this. To use this fea-
ture, simply send mail to the address query-pr@your-site
with command line arguments or options in the Subject:
line of the mail header. GNATS replies to your mail with
the results of your query. The default settings for the
query-pr mail server are shown below; to override the
--state parameter, specify --state=state in the Subject:
line of the mail header. You can not query on confiden-
tial Problem Reports by mail.
--restricted --state="open|analyzed|feedback|suspended"
ENVIRONMENT VARIABLES
The GNATSDB environment variable is used to determine
which database to use. For a local database, it contains
the name of the database to access.
For network access via gnatsd, it contains a colon-sepa-
rated list of strings that describe the remote database in
the form
server:port:databasename:username:password
Any of the fields may be omitted except for server, but at
least one colon must appear; otherwise, the value is as-
sumed to be the name of a local database.
If GNATSDB is not set, it is assumed that the database is
local and that its name is default.
SEE ALSO
Keeping Track: Managing Messages With GNATS (also in-
stalled as the GNU Info file gnats.info)
databases(5), dbconfig(5), delete-pr(8), edit-pr(1) file-
pr(8), gen-index(8), gnats(7), gnatsd(8), mkcat(8),
mkdb(8), pr-edit(8), query-pr(1), queue-pr(8), send-pr(1).
COPYING
Copyright (c) 1993, 94, 95, 96, 1997, 1999, 2003, Free
Software Foundation, Inc.
Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified ver-
sions of this manual under the conditions for verbatim
copying, provided that the entire resulting derived work
is distributed under the terms of a permission notice
identical to this one.
Permission is granted to copy and distribute translations
of this manual into another language, under the above con-
ditions for modified versions, except that this permission
notice may be included in translations approved by the
Free Software Foundation instead of in the original En-
glish.
GNATS August 2003 query-pr(1)