DtSearchMessages(library call) DtSearchMessages(library call)
NAME
DtSearchMessages -- Access and manipulate messages on the DtSearch MessageList
SYNOPSIS
#include <Dt/Search.h>
int DtSearchHasMessages(
,
void DtSearchAddMessage(
const char *msg,
char *DtSearchGetMessages(
,
void DtSearchFreeMessages(
);
DESCRIPTION
The DtSearch online search engine may assemble detailed user messages to explain various errors and failures. These messages are designed
to provide a user with enough information to correct the error. Often more than one message is assembled onto the MessageList as the
result of a single API call. The calling code may also append messages to the MessageList prior to display to the user. All messages
remain on the MessageList and new messages are appended to the preexisting list until the list is specifically freed by the calling code.
DtSearchHasMessages returns zero if the MessageList is empty, and returns nonzero if there are any information or error messages currently
on the MessageList.
DtSearchAddMessage appends a message to the end of the MessageList. A message is defined as a zero-terminated C string.
DtSearchGetMessages returns a static text buffer containing all current messages on the MessageList. The messages are returned as a single
flat, zero-terminated C string, with two ASCII linefeed characters between messages (giving the appearance of a blank line between mes-
sages). It is expected that the calling code will display the text in a message dialog box or its equivalent. The returned buffer address
is valid until the next call. If the MessageList is currently empty, this function returns a pointer to an empty string.
DtSearchFreeMessages clears all messages on the MessageList. It is usually called after the user has dismissed a dialog box displaying the
current messages.
SEE ALSO DtSrAPI(3)
DtSearchMessages(library call)
Check Out this Related Man Page
DtSearchInit(library call) DtSearchInit(library call)
NAME
DtSearchInit -- 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);
DESCRIPTION
DtSearchInit 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 registration.
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 |DtSrInRDEBUG)
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 function
looks for an ocf file with a base name of either dtsearch.ocf or austext.ocf in the directory specified by the DTSROCFPATH envi-
ronment 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 messages. 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 VALUE
DtSearchInit 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 argument.
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 ALSO DtSrAPI(3), DtSearchReinit(3), DtSearchGetMessages(3), dtsrocffile(4), DtSearch(5)
DtSearchInit(library call)