NAME

dtsrocffile — Describes the format and syntax of DtSearch ocf files

SYNOPSIS

DTSROCFPATH=directory
HOME=directory
dtsearch.ocf
austext.ocf

DESCRIPTION

An ocf file is a user-generated file that identifies the databases to be accessed and the execution options to be enabled by one instance of an online DtSearch API search engine. Different ocf files typically apply to different instances of the engine. The file is opened and read by DtSearchInit and its valid contents apply throughout an engine session. It may be reread during a session under certain circumstances referred to as reinitialization, usually caused either by recognizable changes in database files during the session or by a change in the ocf file's modification time stamp.

Errors in an ocf file are typically either syntax errors or errors in databases referred to by the file. While the API expects the ocf file to be correct, most errors are not fatal. They usually result in a warning message and discard of the offending directive. But if no databases survive the initialization process, DtSearchInit will fail. For this reason, the only mandatory directive in an ocf file is at least one valid KEYTYPE directive for at least one valid and accessible database.

The default base file name for an ocf file is dtsearch.ocf, although the alternative name austext.ocf is also a valid default. The file is expected to be found in the directory specified by theDTSROCFPATH environment variable, in the current working directory, or in the HOME directory, in that order. However the complete path/file name may be fully respecified by an argument to DtSearchInit.

General Format

An ocf file can contain only ASCII characters.

Each line (character string terminated by an ASCII linefeed) contains 1 or more 'keywords', and optionally 1 or more 'values', all separated by token delimiter characters.

All token delimiters are equivalent and any combination of one or more of them is acceptable for separating keywords and values. Token delimiters are the ASCII space, tab, comma, or equal sign.

Keywords must begin in column 1, and the first character must be alphanumeric.

Empty lines and lines that begin with #, $, *, or ! in column one are discarded in their entirety as comments.

Any additional text beyond the last required value on a line is ignored as comments.

keyword [keyword] [...] [value] [...] [comments]

Keywords and/or values might be case sensitive, but usually are not. The principal exceptions are database names, which are always case sensitive, and file names and path names in operating systems like UNIX where such things are normally case sensitive.

Where a boolean value is required, any of the following are acceptable. Only enough of the first characters are parsed to distinguish between alternatives (case-insensitive):

(On)

(Of)f

(T)rue

(F)alse

(Y)es

(N)o

(E)nabled

(D)isabled

(1)

(0)

A missing value is taken for the affirmative.

The initialization function may provide defaults for missing values. Despite the defaults, an ocf file must be provided with at least the KEYTYPE(S) correctly completed for each database to be accessed by the engine.

If lines are duplicated or directives conflict, the last specified value(s) will be used.

Keywords and Options

KEYTYPES dddd = ['c'] label, ['c'] label, ...
KEYTYPE dddd = ['c'] label [comments]: These are the only required lines in an .ocf file. They identify the databases to be opened, the keytypes available in each opened database, and the character that distinguishes that keytype in the record key.
: Keytypes can be specified one at a time by several KEYTYPE lines, which include a provision for comments, or grouped together with one or more KEYTYPES lines. Both KEYTYPE and KEYTYPES specifications are additive; if some keytypes have already been specified for a database, the new ones are merely added to the previously defined ones.

dddd: 1- to 8-character dictionary name; case sensitive.
'c': The keytype character or ktchar for a keytype; a single, case sensitive, alphanumeric, ASCII character in single quotes. It identifies the first character of the database record key corresponding to the desired keytype.
: The ktchar value is optional; if a ktchar is not specified, the default is the first character of the label parameter that immediately follows it (described below). If a user config file specifies a ktchar, whether in the ktchar parameter or by default, that cannot be matched to a site file specification, it is ignored. The ktchar is paired with the subsequent label string. For example, if "...'r' Old_Records,..." appears in the site ocf file, a lowercase 'r' will be the ktchar for a record type labeled in user interfaces as "Old Records".
label: A 1- to 13-character symbolic string identifying the keytype. No spaces are allowed in the label string, but underscores will be replaced by spaces in the name field of the KEYTYPES structure. The string is used for record type labels in the user interface application. If there is no preceding ktchar parameter, the first character of the label is the identifying prefix character for the record type in record ids.
: Technically, the label parameter is optional following a ktchar specification. If two adjacent ktchar values in single quotes are detected, a generic label for the first one will be created which is derived from the ktchar value.

PATH dddd = path: This directive is optional.

dddd: 1- to 8-character dictionary name; case sensitive.
path: Where to find the associated database files. If no path is provided for a database, the engine assumes the current working directory.

LABEL dddd text...: This directive is optional. It assigns an arbitrary string to the database name, which will be returned by DtSearchInit and DtSearchReinit rather than the default 1 to 8 char database file name. It is typically used to provide an appropriate symbolic label string for a database for the user interface. Not otherwise used by the search engine.

Note:

: ALL text on the line immediately after the database name, except the terminating linefeed, is included in the label.

dddd: 1- to 8-character dictionary name; case sensitive.
text: The string value stored is all the text on the rest of the line after the database name.

WHITLIM = n: This directive is optional. It changes the default value of the words hitlimit variable in the engine. This variable will cause a word/stem search to abort if the results list grows to some ridiculously large value. For extremely large repositories the default may be too small, and for many smaller repositories it may be too large. The value of n should be be a positive integer in the range of a signed long integer.

ENVIRONMENT VARIABLES

DTSROCFPATH: Optional. Specifies a directory where the ocf file may be located.
HOME: Specifies an alternative directory in which to look for the ocf file if it is not found in DTSROCFPATH or the current working directory.

EXAMPLES

KEYTYPES xxx = 'A' 'b' 'C' Documents

Specifies that there are only 4 keytypes in the xxx database, whose keys each begin with A, b, C, and D, and creates generic user interface labels for the first three, and the label Documents for the last one.

keytype xxx Records
keytypes xxx 'r' Old_Records XYZs

Specifies that there are 3 keytypes in the xxx database, whose keys each begin with R, r, and X, and associates them with the labels Records, Old Records, and XYZs respectively.

PATH xxx = /usr/local/dt/etcsearch/databases/

LABEL helpdesk Level 2 Support Center Documents

whitlim = 300000