DtSearchInit(library call) DtSearchInit(library call)
NAMEDtSearchInit — Initialize the DtSearch online API for subsequent calls
SYNOPSIS
#include <Dt/Search.h>
int DtSearchInit(
void *argv0,
char *userid,
long switches,
char *ocf_file,
FILE *err_file,
char ***dbnames,
int *dbcount);
DESCRIPTIONDtSearchInit opens databases and other files and initializes the search
engine API for subsequent requests. It must be the first online
DtSearch function called.
DtSearchInit may be called only once, although DtSrReinit may be called
at any time after DtSearchInit.
If this function fails, the caller should display the MessageList
returned and exit; no subsequent requests will be possible.
ARGUMENTS
argv0 Specifies the program name to be assembled into usage, error,
and debug messages from the API. It is intended to be the
value of argv[0] from main.
userid Specifies a 1- to 8-character name to use for log messages to
distinguish between users and applications where multiple
copies of the engine are running.
If NULL, the first 8 characters of the LOGNAME environment
variable are used.
switches Specifies a set of bit switches used principally to enable
printing debugging statements and controlling signal regis‐
tration.
DtSrInNOLOCALE
Do not execute setlocale within DtSearchInit.
DtSrInSIGNAL
Register DtSearch abort signal handlers.
DtSrInENAB_NOHUP
Reenable NOHUP for offline background programs.
This is also the normal action unless DtSrInSIGNAL
has been specified, in which case normal action is
to abort on SIGHUP signal.
DtSrInIDEBUG
Writes initialization trace messages to err_file.
DtSrInSDEBUG
Writes query and search trace messages to err_file.
DtSrInRDEBUG
Writes document retrieval trace messages to
err_file.
DtSrInANY_DEBUG
Equivalent to (DtSrInIDEBUG | DtSrInSDEBUG |DtSrIn‐
RDEBUG)
DtSrInRDWR
Opens database files for both read and write. The
default is read-only.
For example, to enable trace statements only for search and
retrieval operations, pass switches as (DtSrInSDEBUG |
DtSrInRDEBUG). Pass zero for switches for most normal API
operations.
ocf_file Specifies the fully qualified path and base file name of the
API ocf configuration file. If NULL, the initialization func‐
tion looks for an ocf file with a base name of either
dtsearch.ocf or austext.ocf in the directory specified by the
DTSROCFPATH environment variable, in the current working
directory, or in the HOME directory, in that order. See
dtsrocffile(4) for the format of an ocf file.
err_file Specifies a pointer to a previously opened text stream file
where the API will write fatal error and debug trace mes‐
sages. The normal value passed for err_file is NULL, in which
case such messages will be written to stderr.
dbnames Specifies an address where a pointer to an array of static
database name string pointers will be placed. Each string
identifies a single database successfully opened by this
function.
A database name string from this array will be used in most
later API function calls.
The dbn member in DtSrResult is an index into this array.
dbcount Specifies a pointer to the int where the size of the dbnames
array will be stored.
RETURN VALUEDtSearchInit returns DtSrOK, and possible messages on the MessageList,
if the API is successfully initialized. It returns DtSrFAIL and mes‐
sages on the MessageList if the API cannot be successfully initialized.
ENVIRONMENT VARIABLES
LOGNAME First 8 characters are used for userid if that argument is
not passed.
DTSROCFPATH
Specifies a directory where the API configuration ocf file
may be located. Used in lieu of specifying the ocf_file argu‐
ment.
HOME Specifies an alternative directory in which to look for the
ocf file if the ocf_file argument is not passed, if the
DTSROCFPATH environment variable is not specified, or if the
ocf file is not found either in the DTSROCFPATH directory or
in the current working directory.
SEE ALSODtSrAPI(3), DtSearchReinit(3), DtSearchGetMessages(3), dtsrocffile(4),
DtSearch(5)
DtSearchInit(library call)
