316 lines
12 KiB
Plaintext
316 lines
12 KiB
Plaintext
<!-- $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>
|