1@node GNATS user tools 2@chapter The @sc{gnats} User Tools 3@cindex usage for the @sc{gnats} user tools 4@cindex invoking the @sc{gnats} user tools 5 6This chapter describes the user tools distributed with @sc{gnats}. The 7@sc{gnats} administrative and internal tools are described in 8@ref{Management,,@sc{gnats} Administration}. The user tools provide 9facilities for initial submission, querying and editing of Problem 10Reports: 11 12@table @code 13@item send-pr 14Used by anyone who has a problem with a body of work to submit a report 15of the problem to the maintainers of that work 16(@pxref{send-pr,,Submitting Problem Reports}). 17 18@item query-pr 19Used to query the @sc{gnats} database (@pxref{query-pr,,Querying the 20database}). 21 22@item edit-pr 23Used to edit Problem Reports (to record new data, to change the 24responsible party, etc.) (@pxref{edit-pr,,Editing existing Problem 25Reports}). 26@end table 27 28@menu 29* Environment:: Environment variables and GNATS tools 30* send-pr:: Submitting Problem Reports 31* edit-pr:: Editing existing Problem Reports 32* query-pr:: Querying the database 33* Emacs:: The Emacs interface 34@end menu 35 36@node Environment 37@section Environment variables and @sc{gnats} tools 38@cindex environment variables and GNATS tools 39@cindex @code{GNATSDB} 40 41All the @sc{gnats} user tools honor the @code{GNATSDB} environment 42variable which is used to determine which database to use. For a local 43database, it contains the name of the database to access. 44 45For network access via gnatsd, it contains a colon-separated list of 46strings that describe the remote database in the form 47 48@smalldisplay 49@var{server:port:databasename:username:password} 50@end smalldisplay 51 52Any of the fields may be omitted except for @var{server}, but at least 53one colon must appear; otherwise, the value is assumed to be the name of 54a local database. 55 56If @code{GNATSDB} is not set and no command-line options are used to 57specify the database, it is assumed that the database is local and that 58its name is @samp{default}. 59 60@node send-pr 61@section Submitting Problem Reports 62@cindex @code{send-pr} 63@cindex using @code{send-pr} 64@cindex invoking @code{send-pr} 65@cindex reporting problems with @code{send-pr} 66 67Use @code{send-pr} to submit Problem Reports to the database. 68@code{send-pr} is a shell script which composes a template for 69submitters to complete. 70 71@lowersections 72@include s-usage.texi 73@raisesections 74 75@c --------------------------------------------------------------- 76@node edit-pr 77@section Editing existing Problem Reports 78@cindex using @code{edit-pr} 79@cindex invoking @code{edit-pr} 80@cindex @code{edit-pr} 81 82Use @code{edit-pr} to make changes to existing PRs in the database. 83This tool can be invoked both from a shell prompt or from within GNU 84Emacs using @samp{M-x edit-pr}. 85 86@code{edit-pr} first examines the PR you wish to edit and locks it if it 87is not already locked. This is to prevent you from editing a PR at the 88same time as another user. If the PR you wish to edit is already in the 89process of being edited, @code{edit-pr} tells you the name of the person 90who owns the lock. 91 92You may edit any non-readonly fields in the database. We recommend that 93you avoid deleting any information in the @sc{Text} and @sc{MultiText} 94fields (such as @code{Description} and @code{How-To-Repeat} 95(@pxref{Fields,,Problem Report format}). We also recommend that you 96record the final solution to the problem in the @code{Fix} field for 97future reference. Note that heavily customized installations of 98@sc{gnats} may have differently named fields, and sites using such 99installations should provide their own set of routines and instructions 100regarding how PRs should be treated throughout their life span. 101 102After the PR has been edited, it is then resubmitted to the database, 103and the index is updated (@pxref{index file,,The @code{index} file}). 104For information on @code{pr-edit}, the main driver for @code{edit-pr}, 105see @ref{Internal utils,,Internal utilities}. 106 107If you change a field that requires a reason for the change, such as the 108@code{Responsible} or @code{State} fields in the default configuration, 109@code{edit-pr} prompts you to supply a reason for the change. A message 110is then appended to the @code{Audit-Trail} field of the PR with the 111changed values and the change reason. 112 113Depending on how the database is configured, editing various fields in 114the PR may also cause mail to be sent concerning these changes. In the 115default configuration, any fields that generate @samp{Audit-Trail} 116entries will also cause a copy of the new @samp{Audit-Trail} message to 117be sent. 118 119Mail received at the PR submission email address and recognized by 120@sc{gnats} as relating to an existing PR is also appended to the 121@samp{Audit-Trail} field, see @ref{follow-up via email}. 122 123@menu 124* edit-pr from the shell:: Invoking @code{edit-pr} from the shell 125* follow-up via email:: Following up via direct email 126@end menu 127 128@node edit-pr from the shell 129@subsection Invoking @code{edit-pr} from the shell 130@cindex @code{edit-pr} from the shell 131 132The usage for @code{edit-pr} is: 133 134@smallexample 135edit-pr [ -V | --version ] [ -h | --help ] 136 [-d @var{database} | --database @var{database}] @var{PR Number} 137@end smallexample 138 139@noindent 140Network-mode-only options: 141 142@smallexample 143 [--host @var{host} | -H @var{host}] [--port @var{port}] 144 [--user @var{user} | -v @var{user}] 145 [--passwd @var{passwd} | -w @var{passwd}] 146@end smallexample 147 148@noindent 149The options have the following meaning: 150 151@table @code 152@item -h, --help 153Prints a brief usage message for edit-pr. 154 155@item -V, --version 156Prints the version number for edit-pr. 157 158@item -d @var{database}, --database @var{database} 159Specifies the database containing the PR to be edited; if no database is 160specified, the database named @samp{default} is assumed. This option 161overrides the database specified in the @code{GNATSDB} environment 162variable. 163 164@item --host @var{host}, -H @var{host} 165Specifies the hostname of the gnatsd server to communicate with. This 166overrides the value in the @code{GNATSDB} environment variable. 167 168@item --port @var{port} 169Specifies the port number of the gnatsd server to communicate with. 170This overrides the value in the @code{GNATSDB} environment variable. 171 172@item --user @var{user}, -v @var{user} 173Specifies the username to login with when connecting to the gnatsd 174server. This overrides the value in the @code{GNATSDB} environment 175variable. 176 177@item --passwd @var{passwd}, -w @var{passwd} 178Specifies the password to login with when connecting to the gnatsd 179server. This overrides the value in the @code{GNATSDB} environment 180variable. 181@end table 182 183@code{edit-pr} calls the editor specified in your environment variable 184@code{EDITOR} on a temporary copy of that PR. (If you don't have the 185variable @code{EDITOR} defined in your environment, the default editor 186@code{vi} is used.) 187 188Edit the PR, changing any relevant fields or adding to existing 189information. When you exit the editor, @code{edit-pr} prompts you on 190standard input for a reason if you have changed a field that requires 191specifying a reason for the change. 192 193@node follow-up via email 194@subsection Following up via direct email 195@cindex follow-up via email 196@cindex subsequent mail 197@cindex related mail 198 199If you have some additional information for a PR and for some reason 200do not want to (or cannot) edit the PR directly, you may append 201the information to the Audit-Trail field by mailing it to the PR 202submission address. 203 204In order for GNATS to be able to recognize the mail as pertaining to an 205existing PR (as opposed to a new PR, see @ref{Submitting via e-mail,,}), 206the Subject mail header field must contain a reference to the PR. 207GNATS matches the Subject header against the regular expression 208 209@smallexample 210\<(PR[ \t#/]?|[-[:alnum:]+.]+/)[0-9]+ 211@end smallexample 212 213@noindent 214to determine whether such a reference is present. Any text may precede 215or follow the reference in the Subject header. If more than one reference 216is present, the first is used and the rest ignored. 217 218A PR reference matching the regular expression above has two parts. The 219second is the PR number (one or more digits). The first is either the 220capital letters 'PR' optionally followed by a separator character (blank, 221tab, hash mark or forward slash) or the category name followed by a 222forward slash. Following are some examples which match the regular 223expression: 224 225@smallexample 226PR 123 PR4567 PR#890 gnats/4711 227@end smallexample 228 229The PR number and the category (if present) are checked for existence, 230and if the outcome is positive, the mail is appended to the Audit-Trail 231field of the PR. Note that the PR need not belong to the category because 232PRs may move between categories. 233 234Outgoing emails sent by GNATS itself may be configured to have a Subject 235header field that refers to the PR in question: 236 237@smallexample 238Subject: Re: PR @var{category}/@var{gnats-id}: @var{original message subject} 239@end smallexample 240 241This makes it extremely easy to follow up on a PR by replying to such an 242email, see @ref{dbconfig file,,The @code{dbconfig} file} and the sample, 243default @code{dbconfig} file installed by @code{mkdb}. 244 245@c --------------------------------------------------------------- 246@node query-pr 247@section Querying the database 248@cindex using @code{query-pr} 249@cindex invoking @code{query-pr} 250@cindex @code{query-pr} 251@cindex querying individual problem reports 252 253Obtain information from the database by using the program 254@w{@code{query-pr}}. @code{query-pr} uses search parameters you provide 255to find matching Problem Reports in the database. You can invoke 256@code{query-pr} from the shell or from within Emacs. @code{query-pr} 257uses the same arguments whether it is invoked from the shell or from 258Emacs. 259 260PRs may be selected via the use of the @code{--expr} option, directly by 261number, or by the use of the (now deprecated) field-specific query 262operators. 263 264By default, query options are connected with a logical AND. For 265example, 266 267@smallexample 268query-pr --category=foo --responsible=bar 269@end smallexample 270 271@noindent 272only prints PRs which have a Category field of @samp{foo} and a Responsible 273field of @samp{bar}. 274 275The @code{--or} option may be used to connect query options with a logical 276OR. For example, 277 278@smallexample 279query-pr --category=baz --or --responsible=blee 280@end smallexample 281 282@noindent 283prints PRs which have either a Category field of @samp{baz} or a Responsible 284field of @samp{blee}. 285 286It should be emphasized, however, that the use of these field-specific 287options is strongly discouraged, since they exist only for compatibility 288with older versions of @sc{gnats} and are likely to be deleted in the next 289release. The expressions specified by the @code{--expr} option are much more 290flexible (see below). 291 292@menu 293* Invoking query-pr:: 294* Formatting query-pr output:: 295* Query expressions:: 296* Example queries:: 297@end menu 298 299@node Invoking query-pr 300@subsection Invoking @code{query-pr} 301 302From the shell, simply type @kbd{query-pr}, followed by any search 303parameters you wish to exercise. From Emacs, type @w{@kbd{M-x 304query-pr}}. @code{query-pr} prompts you for search parameters in the 305minibuffer. 306 307@cindex @code{query-pr} by mail 308@code{query-pr} can also be accessed by electronic mail, if your version 309of @sc{gnats} is configured for this. To use this feature, simply send 310mail to the address @w{@samp{query-pr@@@var{your-site}}} with command 311line arguments or options in the @code{Subject} line of the mail header. 312@sc{gnats} replies to your mail with the results of your query. The 313default settings for the @code{query-pr} mail server are 314 315@cindex the section on query-by-mail needs to be relocated 316@smallexample 317--restricted --state="open|analyzed|feedback|suspended" 318@end smallexample 319 320@noindent 321To override the @code{--state} parameter, specify 322@w{@code{--state=@var{state}}} in the @code{Subject} line of the mail 323header. You can not query on confidential Problem Reports by mail. 324 325The usage for @code{query-pr} is: 326 327@smallexample 328query-pr [--debug | -D] [--help | -h] [--version | -V] 329 [--output @var{file} | -o @var{file}] [--list-databases] 330 [--list-fields] [--list-input-fields] 331 [--responsible-address @var{name}] [--field-type @var{field}] 332 [--field-description @var{field}] 333 [--field-flags @var{field}] 334 [--adm-field @var{field}] [--adm-subfield @var{subfield}] 335 [--adm-key @var{key}] 336 [--valid-values @var{field}] 337 [--format @var{format} | -f @var{format}] 338 [--full | -F] [--summary | -q] 339 [--database @var{database} | -d @var{database}] [--and | -&] 340 [--or | -|] [--expr @var{expr}] [PR Number] 341@end smallexample 342 343Non-network-mode options: 344 345@smallexample 346 [--print-sh-vars] [--print-directory-for-database] 347@end smallexample 348 349Network-mode-only options: 350 351@smallexample 352 [--host @var{host} | -H @var{host}] [--port @var{port}] 353 [--user @var{user} | -v @var{user}] [--passwd @var{passwd} | -w @var{passwd}] 354 [--print-server-addr] 355@end smallexample 356 357Deprecated Options: 358@smallexample 359 [--list-categories | -j] [--list-states | -T] 360 [--list-responsible | -k] [--list-submitters | -l] 361 [--category @var{category} | -c @var{category}] 362 [--synopsis @var{synopsis} | -y @var{synopsis}] 363 [--confidential @var{confidential} | -C @var{confidential}] 364 [--multitext @var{multitext} | -m @var{multitext}] 365 [--originator @var{originator} | -O @var{originator}] 366 [--release @var{release} | -A @var{release}] 367 [--class @var{class} | -L @var{class}] [--cases @var{cases} | -E @var{cases}] 368 [--quarter @var{quarter} | -Q @var{quarter}] 369 [--keywords @var{keywords} | -K @var{keywords}] 370 [--priority @var{priority} | -p @var{priority}] 371 [--responsible @var{responsible} | -r @var{responsible}] 372 [--restricted | -R] [--severity @var{severity} | -e @var{severity}] 373 [--skip-closed | -x] [--sql | -i] [--sql2 | -I] 374 [--state @var{state} | -s @var{state}] 375 [--submitter @var{submitter} | -S @var{submitter}] 376 [--text @var{text} | -t @var{text}] 377 [--required-before @var{date} | -u @var{date}] 378 [--required-after @var{date} | -U @var{date}] 379 [--arrived-before @var{date} | -b @var{date}] 380 [--arrived-after @var{date} | -a @var{date}] 381 [--modified-before @var{date} | -B @var{date}] 382 [--modified-after @var{date} | -M @var{date}] 383 [--closed-before @var{date} | -z @var{date}] 384 [--closed-after @var{date} | -Z @var{date}] 385@end smallexample 386 387The options have the following meaning: 388@table @code 389 390@item --help, -h 391Prints a help message. 392 393@item --version, -V 394Displays the program version to stdout. 395 396@item --output @var{file}, -o @var{file} 397The results of the query will be placed in this file. 398 399@item --database @var{database}, -d @var{database} 400Specifies the database to be used for the query. If no database is 401specified, the database named default is assumed. (This option 402overrides the database specified in the @code{GNATSDB} environment 403variable; see @ref{Environment} for more 404information.) 405 406@item --list-categories, -j 407Lists the available PR categories for the selected database. 408 409@item --list-states, -T 410Lists the valid PR states for PRs in this database. 411 412@item --list-responsible, -k 413Lists the users that appear in the database's responsible list. 414 415@item --list-submitters, -l 416Lists the valid submitters for this database. 417@end table 418 419The previous --list-* options are deprecated and may be removed in 420future releases of @sc{gnats}; their functionality can be replaced with 421 422@smallexample 423query-pr --valid-values @var{field} 424@end smallexample 425 426@noindent 427where @var{field} is one of @code{Category}, @code{Class}, 428@code{Responsible}, @code{Submitter-Id}, or @code{State}. 429 430@table @code 431@item --list-databases 432Lists the known databases. 433 434@item --list-fields 435Lists the entire set of field names for PRs in the selected database. 436 437@item --list-input-fields 438Lists the fields that should be provided when creating a new PR for the 439currently-specified database. The fields are listed in an order that 440would make sense when used in a template or form. 441 442@item --field-type @var{field} 443Returns the data type contained in PR field @var{field}. The current 444set of data types includes @samp{text}, @samp{multitext}, @samp{enum}, 445@samp{multienum}, @samp{enumerated-in-file}, 446@samp{multi-enumerated-in-file}, @samp{date} and @samp{integer}. 447 448@item --field-description @var{field} 449Returns a human-readable description of the intended purpose of @var{field}. 450 451@item --field-flags @var{field} 452Returns the flags set for the field in the @file{dbconfig} file 453associated with the database, such as @code{textsearch} and 454@code{readonly}. @xref{Individual field configuration}. 455 456@item --adm-field @var{field} 457Used together with the @code{--adm-key} option, this returns a record 458from the administrative file (if any) associated with the field. For 459more material on administrative files, see @ref{administrative 460files,,Enumerated field administrative files}. 461 462@item --adm-subfield @var{subfield} 463Used together with the @code{--adm-field} and @code{--adm-key} options, 464this returns the contents of a particular subfield from the record 465specified by @code{--adm-field} and @code{--adm-key}. Subfields are 466treated in @ref{administrative files,,Enumerated field administrative 467files}. 468 469@item --adm-key @var{key} 470Used together with @code{--adm-field} to select a record from the 471administrative file associated with the field specified by 472@code{--adm-field}. @xref{administrative 473files,,Enumerated field administrative files}. 474 475@item --valid-values @var{field} 476For fields of type @samp{enum}, a list of valid values (one per line) is 477returned. Otherwise, a regular expression is returned that describes 478the legal values in @var{field}. 479 480@item --responsible-address @var{name} 481The mail address of @var{name} is returned; @var{name} is assumed to be 482a name either appearing in the database's responsible list, or is 483otherwise a user on the system. 484 485@item --print-sh-vars 486A set of @file{/bin/sh} variables is returned that describe the selected 487database. They include: 488 489@table @code 490@item GNATSDB 491The name of the currently-selected database. 492 493@item GNATSDB_VALID 494Set to 1 if the selected database is valid. 495 496@item GNATSDBDIR 497The directory where the database contents are 498stored. 499 500@item DEBUG_MODE 501Set to 1 if debug mode has been enabled for the 502database. 503 504@item DEFAULTCATEGORY 505The default category for PRs in the database. 506 507@item DEFAULTSTATE 508The default state for PRs in the database. 509@end table 510 511@item --print-server-addr 512Prints the information about a remote server database in the format 513suitable for the @code{GNATSDB} environment variable. This option 514works only in the network mode. 515 516@item --print-directory-for-database 517Returns the directory where the selected database is located. 518 519@item --format @var{format}, -f @var{format} 520Used to specify the format of the output PRs, See @ref{Formatting 521query-pr output} for a complete description. 522 523@item --full, -F 524When printing PRs, the entre PR is displayed. This is exactly 525equivalent to 526 527@smallexample 528query-pr --format full 529@end smallexample 530 531@item --summary, -q 532When printing PRs, a summary format is used. This is exactly equivalent 533to 534 535@smallexample 536query-pr --format @var{summary} 537@end smallexample 538 539@item --debug, -D 540Enables debugging output for network queries. 541 542@item --host @var{host}, -H @var{host} 543Specifies the hostname of the gnatsd server to communicate with. This 544overrides the value in the @code{GNATSDB} environment variable. 545 546@item --port @var{port} 547Specifies the port number of the gnatsd server to communicate with. 548This overrides the value in the @code{GNATSDB} environment variable. 549 550@item --user @var{user}, -v @var{user} 551Specifies the username to login with when connecting to the gnatsd 552server. This overrides the value in the @code{GNATSDB} environment 553variable. 554 555@item --passwd @var{passwd}, -w @var{passwd} 556Specifies the password to login with when connecting to the gnatsd 557server. This overrides the value in the @code{GNATSDB} environment 558variable. 559 560@item --and, -&, --or, -| 561These options are used when connecting multiple query operators 562together. They specify whether the previous and subsequent options are 563to be logically ANDed or logically ORed. 564 565@item --expr @var{expr} 566Specifies a query expression to use when searching for PRs. @xref{Query 567expressions}. 568@end table 569 570The remaining deprecated options are not described here, since their use 571is fairly obvious and their functionality is completely replaced by the 572use of the @code{--expr} option. 573 574@node Formatting query-pr output 575@subsection Formatting @code{query-pr} output 576@cindex query-pr output format 577 578Printing formats for PRs are in one of three forms: 579 580@table @var 581@item formatname 582This is a named format which is described by the database (specifically, 583these formats are described in the @file{dbconfig} file associated with the 584database). The default configuration contains five such formats: 585@samp{standard}, @samp{full}, @samp{summary}, @samp{sql}, and 586@samp{sql2}. 587 588The first three are the ones most commonly used when performing queries. 589standard is the format used by default if no other format is specified. 590 591Use of the latter two are discouraged; they are merely kept for 592historical purposes. Other named formats may have been added by the 593database administrator. 594 595@item fieldname 596A single field name may appear here. Only the contents of this field 597will be displayed. 598 599@item '"printf string" fieldname fieldname ...' 600This provides a very flexible mechanism for formatting PR output. (The 601formatting is identical to that provided by the named formats described 602by the database configuration, @xref{Named query definitions}. The 603@var{printf string} can contain the following % sequences: 604 605@code{%[positionalspecifiers]s}: Prints the field as a string. The 606positional specifiers are similar to those of printf, as +, - and digit 607qualifiers can be used to force a particular alignment of the field 608contents. 609 610@code{%[positionalspecifiers]S}: Similar to @code{%s}, except that the 611field contents are terminated at the first space character. 612 613@code{%[positionalspecifiers]d}: Similar to @code{%s}, except that the 614field contents are written as a numeric value. For integer fields, the 615value is written as a number. For enumerated fields, the field is 616converted into a numeric equivalent (i.e. if the field can have two 617possible values, the result will be either 1 or 2). For date fields, 618the value is written as seconds since Jan 1, 1970. 619 620@code{%F}: The field is written as it would appear within a PR, complete 621with field header. 622 623@code{%D}: For date fields, the date is written in a standard @sc{gnats} 624format. 625 626@code{%Q}: For date fields, the date is written in an arbitrary "SQL" 627format. 628@end table 629 630An example formatted query looks as follows (note that the whole format 631specification should be quoted): 632 633@smallexample 634query-pr --format '"%s, %s" Synopsis State' 635@end smallexample 636 637@node Query expressions 638@subsection Query expressions 639@cindex query expressions 640 641@noindent 642Query expressions are used to select specific PRs based on their field 643contents. The general form is 644 645@smallexample 646fieldname|"value" operator fieldname|"value" [booleanop ...] 647@end smallexample 648 649@var{value} is a literal string or regular expression; it must be 650surrounded by double quotes, otherwise it is interpreted as a fieldname. 651 652@var{fieldname} is the name of a field in the PR. 653 654@var{operator} is one of: 655 656@table @code 657@item = 658The value of the left-hand side of the expression must exactly match the 659regular expression on the right-hand side of the expression. 660@xref{Regexps,,Querying using regular expressions}. 661 662@item ~ 663Some portion of the left-hand side of the expression must match the 664regular expression on the right-hand side. 665 666@item == 667The value of the left-hand side must be equal to the value on the 668right-hand side of the expression. 669 670The equality of two values depends on what type of data is stored in the 671field(s) being queried. For example, when querying a field containing 672integer values, literal strings are interpreted as integers. The query 673expression 674 675@smallexample 676Number == "0123" 677@end smallexample 678 679@noindent 680is identical to 681 682@smallexample 683Number == "123" 684@end smallexample 685 686@noindent 687as the leading zero is ignored. If the values were treated as strings 688instead of integers, then the two comparisons would return different 689results. 690 691@item != 692The not-equal operator. Produces the opposite result of the == operator. 693 694@item <,> 695The left-hand side must have a value less than or greater than the 696right-hand side. Comparisons are done depending on the type of data 697being queried; in particular, integer fields and dates use a numeric 698comparison, and enumerated fields are ordered depending on the numeric 699equivalent of their enumerated values. 700@end table 701 702@var{booleanop} is either @samp{|} (logical or), or @samp{&} (logical 703and). The query expression 704 705@smallexample 706Category="baz" | Responsible="blee" 707@end smallexample 708 709@noindent 710selects all PRs with a Category field of @samp{baz} or a Responsible 711field of @samp{blee}. 712 713The not operator @samp{!} may be used to negate a test: 714 715@smallexample 716! Category="foo" 717@end smallexample 718 719@noindent 720searches for PRs where the category is not equal to the regular 721expression foo. 722 723Parentheses may be used to force a particular interpretation of the 724expression: 725 726@smallexample 727!(Category="foo" & Submitter-Id="blaz") 728@end smallexample 729 730@noindent 731skips PRs where the Category field is equal to @samp{foo} and the 732Submitter-Id field is equal to @samp{blaz}. Parentheses may be nested 733to any arbitrary depth. 734 735Fieldnames can be specified in several ways. The simplest and most 736obvious is just a name: 737 738@smallexample 739Category="foo" 740@end smallexample 741 742@noindent 743which checks the value of the category field for the value @var{foo}. 744 745A fieldname qualifier may be prepended to the name of the field; a colon 746is used to separate the qualifier from the name. To refer directly to a 747builtin field name: 748 749@smallexample 750builtin:Number="123" 751@end smallexample 752 753In this case, @samp{Number} is interpreted as the builtin name of the 754field to 755check. (This is useful if the fields have been renamed. For further 756discussion of builtin field names, see @ref{dbconfig file,,The 757@code{dbconfig} file}. 758 759To scan all fields of a particular type, the @var{fieldtype} qualifier 760may be 761used: 762 763@smallexample 764fieldtype:Text="bar" 765@end smallexample 766 767@noindent 768This searches all text fields for the regular expression @samp{bar}. 769 770Note that it is not required that the right-hand side of the expression 771be a literal string. To query all PRs where the PR has been modified 772since it was closed, the expression 773 774@smallexample 775Last-Modified != Closed-Date 776@end smallexample 777 778@noindent 779will work; for each PR, it compares the value of its Last-Modified field 780against its Closed-Date field, and returns those PRs where the values 781differ. However, this query will also return all PRs with empty 782Last-Modified or Closed-Date fields. To further narrow the search: 783 784@smallexample 785Last-Modified != Closed-Date & Last-Modified != "" & Closed-Date != "" 786@end smallexample 787 788@noindent 789In general, comparing fields of two different types (an integer field 790against a date field, for example) will probably not do what you want. 791 792Also, a field specifier may be followed by the name of a subfield in 793braces: 794 795@smallexample 796State[type] != "closed" 797@end smallexample 798 799@noindent 800or even 801 802@smallexample 803builtin:State[type] != "closed" 804@end smallexample 805 806@noindent 807Subfields are further discussed in @ref{dbconfig file,,The 808@code{dbconfig} file}. 809 810@c -------------------------------------------------------- 811 812@node Example queries 813@subsection Example queries 814@cindex example queries 815 816@noindent 817The following simple query: 818 819@smallexample 820query-pr --expr 'Category~"rats" & State~"analyzed" 821 & Responsible~"fred"' 822@end smallexample 823 824@noindent 825yields all PRs in the database which contain the field values: 826 827@smallexample 828>Category: rats @emph{and} 829>Responsible: fred @emph{and} 830>State: analyzed 831@end smallexample 832 833The following query: 834 835@smallexample 836query-pr --expr 'State~"open|analyzed"' 837@end smallexample 838 839@noindent 840yields all PRs in the database whose @code{State} values match either 841@samp{open} or @samp{analyzed} (@pxref{Regexps,,Querying using regular 842expressions}. This search is useful as a daily report that lists all 843Problem Reports which require attention. 844 845The following query: 846 847@smallexample 848query-pr --expr 'fieldtype:Text="The quick.*brown fox"' 849@end smallexample 850 851@noindent 852yields all PRs whose @sc{Text} fields contain the text @samp{The quick} 853followed by @samp{brown fox} within the same field. 854@xref{Regexps,,Querying using regular expressions}, which also contains 855further useful examples of query expressions. 856 857@include emacs.texi 858