DTSEARCHINIT(3)

💖 NAME 💖

DtSearchInit — a library call that initializes the DtSearch online API for subsequent calls. Main-character setup step, no cap ✨

✨ SYNOPSIS ✨

#include &<Dt/Search.h>
int DtSearchInit(
void *argv0,
char *userid,
long switches,
char *ocf_file,
FILE *err_file,
char ***dbnames,
int *dbcount);

🫶 DESCRIPTION 🫶

Okay so DtSearchInit opens databases and other files and initializes the search engine API for subsequent requests. It must be the first online DtSearch function called — no jumping ahead, bestie. 🫶

DtSearchInit may be called only once, although DtSrReinit may be called at any time after DtSearchInit. Not me noticing the reinit loophole 💀

If this function fails, the caller should display the MessageList returned and exit; no subsequent requests will be possible.

So if it flops, it's giving end-of-program energy 😭

🎀 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. Like the API needs to know your name for the group chat 🫶
• 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. Short username, literally 💅
• switches — Specifies a set of bit switches used principally to enable printing debugging statements and controlling signal registration. It's giving control-panel energy 🎛️
  • 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. Highkey important signal lore ⚡
  • 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. Read-only is the default, no cap 🧊

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. Zero being the normal one is so iconic ✨

• 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 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. The search order is literally a scavenger hunt 🔎
• 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. stderr stays catching strays, periodt 💀
• 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. Array girlies, this one's for you 💖
• dbcount — Specifies a pointer to the int where the size of the dbnames array will be stored. Just the count, bestie 🔢

💅 RETURN VALUE 💅

DtSearchInit returns DtSrOK, and possible messages on the MessageList, if the API is successfully initialized. It returns DtSrFAIL and messages on the MessageList if the API cannot be successfully initialized. So it's either slay or sad-girl hours, no in-between 😭✨

🌈 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)

---

Okay bestie, that's the whole page. The footer/source-version line is DtSearchInit(library call) — no separate date text was on it, so that's the whole sign-off. xoxo 💅💖