Ubuntu Manpage: query-pr - query problem reports in the GNATS database

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  returns  either  selected  Problem
       Reports  (PRs) or other requested 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, directly 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
information.)

--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 responsible 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, Submitter-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 creating 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, multitext, enum, multienum, integer, date, and text-with-regex-
qualifier.

--field-description field
Returns a human-readable description of the intended 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 assumed 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 describe 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 communicate 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 connecting to the gnatsd server. This
overrides the value in the GNATSDB environment variable.

--passwd passwd, -w passwd
Specifies the password to login with when connecting 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 appear 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 formats: 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 contents of this field will be
displayed.

´"printf string" fieldname fieldname . . .´

This provides a rather flexible mechanism for formatting 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 converted 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 standard GNATS format.

%Q: For date fields, the date is written in an arbitrary "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 interpreted 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 expression 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 integers. 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 result 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 numeric comparison, and enumerated fields are
ordered depending on the numeric equivalent of their enumerated values.

booleanop is either | [or], or & [and]. The query expression
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 interpretation 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 feature, 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 confidential 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-separated 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 assumed 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.

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 versions 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 conditions for modified versions, except  that  this  permission
       notice may be included in translations approved by the Free Software Foundation instead of
       in the original English.