Provided by: gnats-user_4.1.0-2_amd64 bug

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.

SEE ALSO

       Keeping Track: Managing  Messages  With  GNATS  (also  installed  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 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.