<!-- $XConsortium: dtsrocfl.sgm /main/9 1996/10/31 09:47:15 cdedoc $ -->
<!-- (c) Copyright 1996 Digital Equipment Corporation. -->
<!-- (c) Copyright 1996 Hewlett-Packard Company. -->
<!-- (c) Copyright 1996 International Business Machines Corp. -->
<!-- (c) Copyright 1996 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1996 Novell, Inc. -->
<!-- (c) Copyright 1996 FUJITSU LIMITED. -->
<!-- (c) Copyright 1996 Hitachi. -->
<![ %CDE.C.CDE; [<RefEntry Id="CDE.INFO.dtsrocffile">]]>
<RefMeta>
<RefEntryTitle>dtsrocffile</RefEntryTitle>
<ManVolNum>special file</ManVolNum>
</RefMeta>
<RefNameDiv>
<RefName>dtsrocffile</RefName>
<RefPurpose>
Describes the format and syntax of DtSearch ocf files
</RefPurpose>
</RefNameDiv>
<RefSynopsisDiv>
<Synopsis>
<systemitem class="environvar">DTSROCFPATH</systemitem>=<Symbol Role="Variable">directory</Symbol>
<systemitem class="environvar">HOME</systemitem>=<Symbol Role="Variable">directory</Symbol>

<filename>dtsearch.ocf</filename>
<filename>austext.ocf</filename>
</Synopsis>
</RefSynopsisDiv>
<RefSect1>
<Title>DESCRIPTION</Title>
<Para>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
<function>DtSearchInit</function> 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.
</Para>
<Para>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, <function>DtSearchInit</function>
will fail. For this reason, the only mandatory directive in an ocf file
is at least one valid <Symbol>KEYTYPE</Symbol> directive for at least
one valid and accessible database.
</Para>
<Para>The default base file name for an ocf file is
<filename>dtsearch.ocf</filename>, although the alternative name
<filename>austext.ocf</filename> is also a valid default. The file is
expected to be found in the directory specified by the<systemitem class="environvar">DTSROCFPATH</systemitem> environment variable, in the
current working directory, or in the <systemitem class="environvar">HOME</systemitem> directory, in that order. However
the complete path/file name may be fully respecified by an argument to
<function>DtSearchInit</function>.
</Para>
<refsect2>
<Title>General Format</Title>
<para>An ocf file can contain only ASCII characters.
</Para>
<Para>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.
</Para>
<Para>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.
</Para>
<Para>Keywords must begin in column 1, and the first character
must be alphanumeric.
</Para>
<Para>Empty lines and lines that begin with <literal>#</literal>,
<Literal>$</Literal>, <literal>*</literal>, or <literal>!</literal> in
column one are discarded in their entirety as comments.
</Para>
<Para>Any additional text beyond the last required value on a line
is ignored as comments.
</Para>
<programlisting>
keyword [keyword] [...] [value] [...] [comments]
</programlisting>
<Para>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.
</Para>
<Para>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):
</para>
<informaltable>
<tgroup cols="2">
<colspec align="left" colwidth="1.12in">
<colspec align="left" colwidth="2.49in">
<tbody>
<row>
<entry><para>(On)</para></entry>
<entry><para>(Of)f</para></entry>
</row>
<row>
<entry><para>(T)rue</para></entry>
<entry><para>(F)alse</para></entry>
</row>
<row>
<entry><para>(Y)es</para></entry>
<entry><para>(N)o</para></entry>
</row>
<row>
<entry><para>(E)nabled</para></entry>
<entry><para>(D)isabled</para></entry>
</row>
<row>
<entry><para>(1)</para></entry>
<entry><para>(0)</para></entry>
</row>
</tbody></tgroup></informaltable>
<Para>A missing value is taken for the affirmative.
</Para>
<Para>The initialization function may provide defaults for missing values.
Despite the defaults, an ocf file must be provided with at least the
<literal>KEYTYPE(S)</literal> correctly completed for each database to be
accessed by the engine.
</Para>
<Para>If lines are duplicated or directives conflict, the last
specified value(s) will be used.
</Para>
</refsect2>
<refsect2>
<Title>Keywords and Options</Title>
<variablelist>
<varlistentry><term>KEYTYPES <emphasis>dddd</emphasis> = ['<emphasis>c</emphasis>'] <emphasis>label</emphasis>, ['<emphasis>c</emphasis>'] <emphasis>label</emphasis>, ...</term>
<term>KEYTYPE <emphasis>dddd</emphasis> = ['<emphasis>c</emphasis>'] <emphasis>label</emphasis> [<emphasis>comments</emphasis>]</term>
<listitem>
<para>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.
</para>
<para>Keytypes can be specified one at a time by several
<Symbol>KEYTYPE</Symbol> lines, which include a provision for
comments, or grouped together with one or more
<Symbol>KEYTYPES</Symbol> lines. Both <Symbol>KEYTYPE</Symbol> and
<Symbol>KEYTYPES</Symbol> specifications are additive; if some
keytypes have already been specified for a database, the new ones are
merely added to the previously defined ones.
</para>
<variablelist>
<varlistentry><term><emphasis>dddd</emphasis></term>
<listitem>
<para>1- to 8-character dictionary name; case sensitive.
</para>
</listitem>
</varlistentry>
<varlistentry><term>'<emphasis>c</emphasis>'</term>
<listitem>
<para>The keytype character or <emphasis>ktchar</emphasis> 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.
</para>
<para>The <emphasis>ktchar</emphasis> value is optional; if a
<emphasis>ktchar</emphasis> 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 <emphasis>ktchar</emphasis>,
whether in the <emphasis>ktchar</emphasis> parameter or by default, that
cannot be matched to a site file specification, it is ignored. The
<emphasis>ktchar</emphasis> 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 <emphasis>ktchar</emphasis> for a record type
labeled in user interfaces as "Old Records".
</para>
</listitem>
</varlistentry>
<varlistentry><term><emphasis>label</emphasis></term>
<listitem>
<para>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 <Symbol>KEYTYPES</Symbol> structure.
The string is used for record type labels in the user interface
application. If there is no preceding <emphasis>ktchar</emphasis>
parameter, the first character of the label is the identifying prefix
character for the record type in record ids.
</para>
<para>Technically, the <emphasis>label</emphasis> parameter is optional
following a <emphasis>ktchar</emphasis> specification. If two adjacent
<emphasis>ktchar</emphasis> values in single quotes are detected, a
generic label for the first one will be created which is derived from
the <emphasis>ktchar</emphasis> value.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry><term>PATH <emphasis>dddd</emphasis> = <emphasis>path</emphasis></term>
<listitem>
<para>This directive is optional.
</para>
<variablelist>
<varlistentry><term><emphasis>dddd</emphasis></term>
<listitem>
<para>1- to 8-character dictionary name; case sensitive.
</para>
</listitem>
</varlistentry>
<varlistentry><term><emphasis>path</emphasis></term>
<listitem>
<para>Where to find the associated database files.
If no path is provided for a database,
the engine assumes the current working directory.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry><term>LABEL <emphasis>dddd</emphasis> <emphasis>text</emphasis>...</term>
<listitem>
<para>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.
</para>
<note><para>ALL text on the line immediately after the database name,
except the terminating linefeed, is included in the label.
</para></note>
<variablelist>
<varlistentry><term><emphasis>dddd</emphasis></term>
<listitem>
<para>1- to 8-character dictionary name; case sensitive.
</para>
</listitem>
</varlistentry>
<varlistentry><term><emphasis>text</emphasis></term>
<listitem>
<para>The string value stored is all the text
on the rest of the line after the database name.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry><term>WHITLIM = <emphasis>n</emphasis></term>
<listitem>
<para>This directive is optional. It changes the default value of the words
<Symbol Role="Variable">hitlimit</Symbol> 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 <emphasis>n</emphasis> should be be a
positive integer in the range of a signed long integer.
</para>
</listitem>
</varlistentry>
</variablelist>
</RefSect2>
</RefSect1>
<RefSect1>
<Title>ENVIRONMENT VARIABLES</Title>
<variablelist>
<varlistentry><term><systemitem class="environvar">DTSROCFPATH</systemitem></term>
<listitem>
<para>Optional. Specifies a directory where the ocf file may be located.
</para>
</listitem>
</varlistentry>
<varlistentry><term><systemitem class="environvar">HOME</systemitem></term>
<listitem>
<para>Specifies an alternative directory in which to look for the ocf file if
it is not found in <systemitem class="environvar">DTSROCFPATH</systemitem> or the current working
directory.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<RefSect1>
<Title>EXAMPLES</Title>
<programlisting>
KEYTYPES xxx = 'A' 'b' 'C' Documents
</programlisting>
<para>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 <literal>Documents</literal>
for the last one.
</para>
<programlisting>
keytype xxx Records
keytypes xxx 'r' Old_Records XYZs
</programlisting>
<para>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
<literal>Records</literal>, <literal>Old Records</literal>, and
<literal>XYZs</literal> respectively.
</para>
<programlisting>
PATH xxx = /etc/dtsearch/databases/
</programlisting>
<programlisting>
LABEL helpdesk Level 2 Support Center Documents
</programlisting>
<programlisting>
whitlim = 300000
</programlisting>
</refsect1>
<RefSect1>
<Title>SEE ALSO</Title>
<Para>&cdeman.DtSearchInit;,
&cdeman.DtSrAPI;,
&cdeman.DtSearch;
</Para>
</RefSect1>
</RefEntry>
