dbconfig(5)

NAME
dbconfig - GNATS database configuration file

DESCRIPTION
The dbconfig configuration file is, oddly enough, used to control the configuration of a GNATS database. Each database has its own individual copy of the file, which is located in the gnats-adm administrative subdirectory of the database.

The file contains 6 major sections, which must appear in this order:

    Overall database configuration
    Individual field configuration
    Named query definitions
    Audit-trail and outgoing email formats
    Index file description
    Initial PR input fields

Individual descriptions of each section will appear below. (It is helpful to refer to the supplied default configuration, which contains examples of most of the available configuration options.)

It is very helpful if the administrator has a reasonably good understanding of the overall GNATS PR process before trying to create or edit a database configuration.

FILE FORMAT
The file is a free-form ASCII file. Whitespace is completely optional, and is ignored. Braces ({}) are used to delimit sections within the file. Non-keyword values must generally be surrounded with double quotes. Newline characters within double quotes must be proceeded with a backslash (`\') character, and are not included in the final resulting string; to include a newline character in a value, use the \n combination instead.

Overall Database Configuration
The overall database options are controlled with the database-info section:

    database-info {
        [options]
    }
The following options may be present:

debug-mode true|false
    If set to true, the database is placed into debug mode. This causes all outgoing email to be sent to the gnats-admin user listed in the responsible adm file.

    The default value is false.

keep-all-received-headers true|false
    If set to true, all of the Received: headers for PRs submitted via email are kept in the PR; otherwise, only the first one is kept.

    The default value is false.

notify-about-expired-prs true|false
    If set to true, notification email about expired PRs is sent via the at-pr command. Otherwise, required times for PR fixes are not used.

    The default value is false.

send-submitter-ack true|false
    When new PRs are submitted to the database, an acknowledgement email will be sent to the submitter if send-submitter-ack is set to true. This is in addition to the normal notification mail to the person(s) responsible for the new PR.

    The default value is false.

libexecdir "path"
    Used to specify the directory where the GNATS adminstrative executables can be found; in particular, at-pr and mail-pr are invoked from this directory.

    The default value is the empty string, which is unlikely to be useful.

business-day-hours day-start - day-end
    Used to specify the hours that define a business day in 24-hour format; the times are inclusive. A single dash separates the two values. The values are used to determine if a PR required completion time has expired.

    The default values are 8 for day-start, and 17 for day-end.

business-week-days week-start - week-end
    Used to specify the start and ending days of the business week, where 0 is Sunday, 1 is Monday, etc; the days are inclusive. These values are used to determine if a PR required completion time has expired.

    The default values are 1 for week-start, and 5 for week-end.

create-category-dirs true|false
    If set to true, database directories for categories are automatically created as needed; otherwise, they must be created manually (usually with the mkcat script). It is suggested that the value be left to true.

    The default value is true.

Individual field configuration
Each field in a PR is described with a field entry. It has the general structure
    field "fieldname" {
        description "string"
        [ field-options ... ]
        datatype [ datatype-options ... ]
        [ on-change { edit-options ... } ]
    }

fieldname is used as the field header in the PR. The > and : field markers should not be present in the name.

The order in which the field configurations appear in the configuration file determines the order that they appear in the PR text. There is no required order, unlike previous versions of GNATS; multitext and the Unformatted fields can appear anywhere in the PR.

The following options may be present within the field section:

builtin-name "name"
    Indicates that this field corresponds to one of the GNATS builtin fields.

    GNATS has several fields which are required to be present in a PR, and this option is used to map their external descriptions to their internal usage. The internal fieldnames are:

    Name | Meaning
    number | The PR's unique numeric identifier
    category | The category that the PR falls into
    synopsis | The one-line description of the PR
    confidential | If "yes", the PR is confidential
    severity | How severe is the PR?
    priority | What's the PR's priority?
    responsible | Who's responsible for the PR?
    state | What's the frequency, Kenneth?
    submitter | The user that submitted the PR
    arrival-date | When did the PR arrive?
    last-modified | The date of the last PR modification
    audit-trail | The audit-trail of various changes to the PR

    For these builtin fields, a matching field description must appear in the database configuration. Otherwise, the configuration will be considered invalid, and errors will be generated from the GNATS clients and gnatsd.

description "description text"
    A one-line human-readable description of the field. Clients can use this string to describe the field in a help dialog; the string is returned from the FDSC command in gnatsd, and is also available via the --field-description option in query-pr.

    This entry must be present in the field description; there is no default value.

query-default exact-regexp|inexact-regexp
    Used to specify the default type of searches performed on this field. This is used when the ^ search operator appears in a query, and is also used for queries in query-pr that use the old --field query options.

    If the option is not given, the default search is exact-regexp).

textsearch
    If this option is present, the field will be searched when the user performs a --text search from query-pr. The field is also flagged as a textsearch field in the set of field flags returned by the FIELDFLAGS command in gnatsd.

    By default, fields are not marked as textsearch fields.

read-only
    The field contents may not be edited; they must be set when the PR is initially created. In general, this should only be used for fields that are given internal values rather than fields supplied by the user.

    By default, fields are editable by the user.

Field datatypes

datatype [ options ... ]
    Describes the type of data to be stored in the field, and must be present in each field description.

    The available datatypes are:

text [ matching { "regexp" [ "regexp" ... ]  } ]
    The text datatype is the most commonly used type; it is a one-line text string.

    If the matching qualfifier is present, the data in the field must match at least one of the specified regexps. Otherwise, no restriction is placed on what values may appear in the field.

multitext [ { default "string" } ]
    The field can contain multiple lines of text.

    If the default option is present, the field will default to the specified string if the field is not given a value when the PR is initially created. Otherwise, the field will be left empty.

enum {
    values {
        "string" [ "string" ... ]
    }
    [ default "string" ]
}

    Defines an enumerated field, where the value in the PR field must match an entry from a list of specified values.

    The list of allowed values is given with the values option, which must be present.

    If a default option is present, it is used to determine the initial value of the field if no entry for the field appears in an initial PR (or if the value in the initial PR is not one of the acceptable values). However, the value in the default statement is not required to be one of the accepted values; this can be used to allow the field to be initially empty, for example.

    If no default option is specified, the default value for the field is the first value in the values section.

multienum {
    values {
        "string" [ "string" ... ]
    }
    [ separators "string" ]
    [ default "string" ]
}

    The multienum datatype is similar to the enum datatype, except that the field can contain multiple values, separated by one or more characters from the separators list.

    If no separators option is present, the default separators are space (` ') and colon (':').

enumerated-in-file {
    path "filename"
    fields {
        "name" [ "name" ... ]
    } key "name"
    [ allow-any-value ]
}
    The enumerated-in-file type is used to describe an enumerated field with an associated administrative file, which lists the legal values for the field, and may optionally contain additional fields that can be examined by query clients or used for other internal purposes. It is similar to the enum datatype, except that the list of legal values is stored in a separate file.

    filename is the name of a file in the gnats-adm administrative directory for the database.

    The format of the administrative file is a simple ASCII text file. Fields within the file are separated with colons (`:'). Lines beginning with an octothorpe ('#') are ignored as comments. Records within the file are separated with newlines.

    The field option is used to name the fields in the administrative file. There must be at least one field, which is used to list the legal values for the field. If the administrative file is empty (or does not contain any non-empty non-comment lines) then the PR field must be empty.

    The key option is used to designate which field in the administrative file should be used to list the legal values for the PR field. The value must match one of the field names in the field option.

    If the allow-any-value option is present, then the value of the PR field is not required to appear in the administrative file; any value will be accepted.

date
    The date datatype is used to hold dates. Date fields may be empty, or must contain a correctly-formatted date.

    No defaults or other options are available. The field is left empty if no value for the field is given in the initial PR.

integer [ { default "integer" } ]
    Integer fields are used to hold numbers. They may be empty, or must contain a value composed entirely of digits, with an optional leading sign.

    If the default option is present, the field will have the value of integer if the field is not given a value when the PR is initially created. Otherwise, the field will be left empty.

Edit controls
The on-change section is used to specify one or more actions to be performed when the field value is edited by the user. It has the general form
    on-change [ "query-expression" ] {

        [ add-audit-trail ]

        [ audit-trail-format {
            format "formatstring"
            [ fields { "fieldname" ... } ]
        } ]

        [ require-change-reason ]

        [ set-field|append-to-field "fieldname" {
            "format-string" [ fieldlist ]
        } ]
    }

The optional query-expression controls whether or not the actions in the on-change section are taken. If the expression fails to match, the actions are skipped.

The add-audit-trail option indicates that an entry should be appended to the builtin audit-trail field when this field is changed. The format of the entry is controlled by the optional audit-trail-format section within the field, or by the global audit-trail-format section. (See the Audit-trail and outgoing email formats section for more information.)

The require-change-reason option specifies that a change reason must be present in the PR when this field is edited. This option only makes sense if an audit-trail entry is required, as the change reason is otherwise unused.

The set-field and append-to-field options are used to change the value of the field fieldname in the PR. The supplied format is used to format the value that will be placed in the field (for more information, see the Audit-trail and outgoing email formats section of this manual). append-to-field appends the resulting formatted string to the existing field contents, while set-field completely replaces the contents.

Any field may be edited by the set-field or append-to-field option (the read-only option on a field is ignored). However, the changes are subject to the usual field content checks.

There is a global on-change section that is executed once for each PR edit.

Named query definitions
When queries are performed via query-pr, they can refer to a query format described via the query section:
    query "queryname" {
        format "formatstring"
        [ fields { "fieldname" [ "fieldname" ... ] } ]
    }
formatstring is as described in the query-pr(1) manpage; it contains a string with printf(3)-like % escapes. The output of the query is then formatted as specified by the format string.

The fields option lists the fields to be used with the format string. If the fields option is present without a format option is, then the listed fields are printed out as just their contents separated by newlines.

The named query formats full, standard and summary must be present in the database configuration. full and summary correspond to the query-pr options --full and --summary, while standard is used when no format option is given to query-pr.

Audit-trail and outgoing email formats
These formats are smilar to the named query formats, but they include more options. They are used for formatting audit-trail entries and for outgoing email messages.

There is currently only one audit-trail format, defined by the audit-trail-format option:
    audit-trail-format {
        format "formatstring"
        [fields { "fieldname" [ "fieldname" ... ] } ]
    }
For those fields that require an audit-trail entry, the audit-trail text to be appended is formatted as described by this format. The per-field audit-trail-format is used in preference to this one, if it exists.

formatstring and fieldname are similar to those used by the named query format. fieldname may also be a format parameter, which is a context-specific value. [Format parameters are distinguished from fieldnames by a leading dollarsign (`$').]

The following format parameters are defined for audit-trail-format entries:

$FieldName
    The name of the field for which an audit-trail entry is being created.

$OldValue
    The old value of the field.

$NewValue
    The new field value.

$EditUserEmailAddr
    The email address of the user editing the field.

$CurrentDate
    The current date.

$ChangeReason
    The reason for the change; may be blank if no reason was supplied.

These parameters may be used anywhere a fieldname can appear.

SEE ALSO
Keeping Track: Managing Messages With GNATS (also installed as the GNU Info file gnats.info) and Reporting Problems Using send-pr (also installed as the GNU Info file send-pr.info).

gnats(7), send-pr(1), edit-pr(1), query-pr(1), file-pr(8), queue-pr(8), rmcat(8), gen-index(8), mkcat(8).

COPYING
Copyright (c) 2000 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.