query-pr

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 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.



GNATS                             August 2003                      query-pr(1)