DTSRAPI(3)

📦
version 2.5.3 · 2 versions
, in nixos 26.05

okay so bestie, you're looking at DtSrAPI, and it's a library call page — the manual entry that describes the overview, constants, and structures for the DtSearch online API. Buckle up, because this is part 1 and it's giving reference material in the best way 💅

✨ NAME ✨

DtSrAPI — describes overview, constants, and structures for DtSearch online API. periodt.

💖 DESCRIPTION 💖

The DtSearch API gives you programmatic access to the DtSearch search and retrieval engine. The API functions live in the library libDtSr, and they're directly linked into user-written search programs. no cap.

Search and retrieval of DtSearch databases is available through three essential API functions:

  • DtSearchInit — opens databases and other files, and generally initializes the search engine for subsequent requests. it's the setup bestie 🎀
  • DtSearchQuery — is passed a user query and some search options, performs the requested search, and returns a linked list of structures called a results list, representing the objects satisfying the search. The results list contains abstracted information about the documents suitable for display to an end user, as well as private information used for subsequent retrievals. main character energy fr fr 🔥
  • DtSearchRetrieve — retrieves an object given data from a results list node. When a results list contains all the information an application needs, retrieval by DtSearch may not be required. For example, when the documents themselves are not stored in DtSearch databases and the document references are available from the results list, the calling program may access the objects directly. lowkey convenient 💅

🌸 DtSearch MessageList 🌸

All functions can potentially return multiple messages on a global linked list of messages called the MessageList. Most unsuccessful return codes append at least one message to the MessageList, but even successful returns may append messages, and multiple messages are always possible. so don't assume silence means perfection, bestie 😭

Messages are standard C text strings terminated by a zero byte, and were designed to be displayed directly to users. cute and functional 🎀

Several API utility functions are available for manipulating the MessageList.

🦋 Fatal API Errors 🦋

Certain fatal errors will require an immediate abort from the engine. By default, fatal error messages will be written to the stderr, but can be written to a text file specified in DtSearchInit. highkey important 🚨

All API aborts are implemented through a call to DtSearchExit. DtSearchExit() ensures cleanup of a number of system resources before the final call to exit. Developers can add an additional user exit to DtSearchExit to specify additional emergency clean up before process exit. the way that's both iconic and terrifying 🫶

👑 CONSTANTS 👑

💜 Function Return Code Constants 💜

Most API functions return one of a set of standard integer return codes. The return code DtSrOK means complete success; other return codes indicate various levels of negative results or failure. vibe check on every return, bestie ✨

  • DtSrOK — normal, affirmative, successful response. slay 💖
  • DtSrNOTAVAIL — generic negative response. For example, no hits on search, no such record, etc. it's giving "nothing here" 🫠
  • DtSrFAIL — miscellaneous unsuccessful engine returns. not the moment 😭
  • DtSrREINIT — engine reinitialized, request canceled. Often returned when invalid database name detected. Caller should clean up and call DtSearchReinit(). okay so reset era 🔄
  • DtSrERROR — fatal caller programming error. bestie, that's on you 💀
  • DtSrABORT — fatal engine failure, caller must abort. no cap, this one's serious 🚨

🌈 Language Numbers 🌈

Each DtSearch database is associated with an integer representing, among other things, the natural language of its documents. These constants are used throughout the API to identify the supported languages. iykyk 🌍

  • DtSrLaENG — 0 — English, ASCII char set (default)
  • DtSrLaENG2 — 1 — English, ISO Latin-1 char set
  • DtSrLaESP — 2 — Spanish, ISO Latin-1 char set
  • DtSrLaFRA — 3 — French, ISO Latin-1 char set
  • DtSrLaITA — 4 — Italian, ISO Latin-1 char set
  • DtSrLaDEU — 5 — German, ISO Latin-1 char set
  • DtSrLaJPN — 6 — Japanese, EUC, auto kanji compounds
  • DtSrLaJPN2 — 7 — Japanese, EUC, listed kanji compounds
  • DtSrLaLAST — 7 — last supported DtSrLa constant

⭐ Other General Constants ⭐

  • DtSrVERSION — DtSearch version number string. the flex 💅
  • DtSrMAX_KTNAME — maximum string length of a keytype name.
  • DtSrMAX_DB_KEYSIZE — maximum size of the unique document key.
  • DtSrMAXWIDTH_HWORD — largest possible word or stem size.
  • DtSrMAX_STEMCOUNT — maximum number of boolean search terms.

🎀 DtSrObjdate Type 🎀

DtSrObjdate is a typdef (yes, that's the exact spelling in the source, bestie — not me 😭) for an unsigned integer used as a date/time stamp for documents.

DtSearch queries may be qualified by document date ranges. The data type packs certain standard struct tm fields into bitmap fields to minimize space. efficient queen 👑

DtSrObjdate are based on the western Gregorian calendar and are not guaranteed to map to other time locales. so like, calendar behavior is not universal, noted 🗓️

DtSearch objdates have a range from 1900 to 5995 inclusive and a resolution of 1 minute. From hi order bits to low:

  • 12 bits = tm_year — (0 - 4095, years since 1900 (1900 - 5995))
  • 4 bits = tm_mon — (0 - 11, month name index)
  • 5 bits = tm_mday — (1 - 31, day of month)
  • 5 bits = tm_hour — (0 - 23, hours since midnight)
  • 6 bits = tm_min — (0 - 59, minutes since top of hour)

💖 STRUCTURES 💖

okay bestie, this is where the actual data shapes live — the little structs that carry all the search tea ☕✨

🎀 DtSrKeytype Type 🎀

       typedef struct {
           char        is_selected;
           char        ktchar;
           char        name   [ DtSrMAX_KTNAME+1];
       }       DtSrKeytype;

A DtSearch keytype references a logical subset of the database. periodt.

The primary identifier for a keytype is the keytype character ktchar. The ktchar identifies the subset of the database that has that character as the first character of its document keys.

The DtSrKeytype structure associates the ktchar with a short name string for use in user GUI labels identifying the keytype, and provides a boolean selection toggle for the keytype. cute little label-maker energy 💅

An array of DtSrKeytype structures is maintained by the API for each database after API initialization. The API function DgSearchGetKeytypes() is used to access the array.

The is_selected boolean in each array node indicates whether the user has selected that keytype to be returned in the current search. The application must ensure that the boolean reflects the current state of the user's desires prior to any search. Typically this is done by having the keytypes array track user interface toggle buttons for the database. so like… keep the toggles in sync, bestie 😭

✨ DtSrResult Structure ✨

       typedef struct _DtSrResult {
           struct _DtSrResult *link;
           long        flags;
           long        objflags;
           long        objuflags;
           long        objsize;
           DtSrObjdates         objdate;
           short       objtype;
           short       objcost;
           int         dbn;
           DB_ADDR     dba;
           short       language;
           char        reckey [DtSrMAX_DB_KEYSIZE];
           int         proximity;
           char        *abstractp;
       }       DtSrResult;

The API function DtSearchQuery returns a results list upon successful completion of a search. A results list is a linked list of DtSrResult structures, where each node represents a database document that satisfied the query. linked-list realness 🔥

  • link — Pointer to the next results list node.
  • flags — (reserved)
  • objflags — The constant DtSrFlNOTAVAIL means that the object is not retrievable from the search engine.
  • objuflags — User flags from database record. These are not used by DtSearch and are available for application definition.
  • objsize — In uncompressed bytes.
  • objdate — Zero is the null date; document is 'undated'.
  • objtype — Document type from database header record. Objtype is typically used by application code to identify and launch browsers.

Values above x1000 (4096) are set aside for application definition. The following constants identify defined values:

  • DtSrObjUNKNOWN — Document type unknown or not applicable
  • DtSrObjTEXT — Generic, unformatted flat text
  • DtSrObjBINARY — Generic binary object
  • DtSrObjSGML — Generic SGML formatted document
  • DtSrObjHTML — HTML formatted document
  • DtSrObjPOSTSCR — Postscript document
  • DtSrObjINTERLF — Interleaf document
  • DtSrObjDTINFO — DtInfo document
  • objcost — (reserved)
  • dbn — Database number; index into dbnames array from DtSearchInit and DtSearchReinit.
  • dba — Atomic document identifier within a database.
  • language — Language number of the database DtSrLa... constant).
  • reckey — Document's unique database key. The first character of reckey is the keytype character.
  • proximity — Sort field for ranking results lists. Derived from frequency of occurrence statistics for the query words in the document. Often displayed to users as the subjective 'distance' between the document and the query, in other words a measure of the likelihood that the document will satisfy the user's needs.
  • abstractp — Document's abstract string from the database.

ngl this struct is giving “main character energy” — it carries the whole search result on its back 🫶

🦋 DtSrHitword Structure 🦋

       typedef struct {
           long        offset; /* word location in cleartext */
           long        length; /* length of word */
       }       DtSrHitword;

Given a text string and the array of search terms returned from DtSearchQuery, DtSearchHighlight will generate a table of offsets and lengths where the search terms are located in the text. The table is typically used to highlight the search terms in the text in a manner appropriate to the application's user interface.

The DtSrHitword structure is one element in the table. For each search term to be highlighted, offset specifies the beginning byte for the term, and length specifies the extent of the term in bytes. highlighting slay ✨

🌈 SEE ALSO 🌈

okay bestie, that's the whole page 💖 the footer on this one is DtSrAPI(library call) — and there's no date listed, so she's timeless like a little Unix ghost 🎀✨. now go forth and highlight those hitwords, fr fr 💅

📦 where this page comes from