Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DtSrAPI(library	call)					 DtSrAPI(library call)

       DtSrAPI	--  Describes overview,	constants, and structures for DtSearch
       online API

       The DtSearch API	provides programmatic access to	 the  DtSearch	search
       and retrieval engine. The API functions are located in the library lib-
       DtSr, and are directly linked into user written search programs.

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

		 Opens	databases  and	other files, and generally initializes
		 the search engine for subsequent requests.

		 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.

		 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  di-

   DtSearch MessageList
       All  functions  can  potentially	 return	 multiple messages on a	global
       linked list of messages called the MessageList. Most  unsuccessful  re-
       turn  codes  append  at	least one message to the MessageList, but even
       successful returns may append messages, and multiple messages  are  al-
       ways possible.

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

       Several API utility functions are available for manipulating  the  Mes-

   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.

       All  API	 aborts	 are  implemented  through a call to DtSearchExit. Dt-
       SearchExit() ensures cleanup of a number	of system resources before the
       final  call  to exit. Developers	can add	an additional user exit	to Dt-
       SearchExit to specify additional	 emergency  clean  up  before  process

   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.

       DtSrOK		  Normal,   affirmative,  successful  re-
       DtSrNOTAVAIL	  Generic negative response. For example,
			  no hits on search, no	such record, etc.
       DtSrFAIL		  Miscellaneous	 unsuccessful  engine re-
       DtSrREINIT	  Engine reinitialized,	request	canceled.
			  Often	 returned  when	 invalid database
			  name detected. Caller	should	clean  up
			  and call DtSearchReinit().
       DtSrERROR	  Fatal	caller programming error.
       DtSrABORT	  Fatal	  engine   failure,  caller  must

   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.

       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.
       DtSrMAX_KTNAME		Maximum	string length of a  keytype
       DtSrMAX_DB_KEYSIZE	Maximum	size of	the unique document
       DtSrMAXWIDTH_HWORD	Largest	possible word or stem size.
       DtSrMAX_STEMCOUNT	Maximum	number	of  boolean  search

   DtSrObjdate Type
       DtSrObjdate  is	a  typdef  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 min-
       imize space.

       DtSrObjdate are based on	the western Gregorian  calendar	 and  are  not
       guaranteed to map to other time locales.

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

       12 bits = tm_year   (0 -	4095, years  since  1900  (1900	 -
       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)

   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.

       The  primary  identifier	for a keytype is the keytype character ktchar.
       The ktchar identifies the subset	of the database	that has that  charac-
       ter 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.

       An  array  of  DtSrKeytype structures is	maintained by the API for each
       database	after API initialization.  The	API  function  DgSearchGetKey-
       types() 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 ap-
       plication  must	ensure	that the boolean reflects the current state of
       the user's desires prior	to any search. Typically this is done by  hav-
       ing  the	 keytypes  array  track	 user interface	toggle buttons for the

   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	satis-
       fied the	query.

       link	 Pointer to the	next results list node.

       flags	 (reserved)

       objflags	 The  constant DtSrFlNOTAVAIL means that the object is not re-
		 trievable from	the search engine.

       objuflags User flags from database record. These	are not	 used  by  Dt-
		 Search	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 typi-
		 cally	used  by  application  code  to	 identify  and	launch

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

		 DtSrObjUNKNOWN		  Document type	unknown	or not	ap-
		 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.

   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 Dt-
       SearchQuery, 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	 is  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.

       DtSrAPI(3),  DtSearchInit(3),  DtSearchReinit(3),  DtSearchExit(3), Dt-
       SearchGetKeytypes(3),	DtSearchSetMaxResults(3),    DtSearchGetMaxRe-
       sults(3),  DtSearchQuery(3), DtSearchRetrieve(3), DtSearchHighlight(3),
       DtSearchValidDateString(3),  DtSearchMergeResults(3),   DtSearchSortRe-
       sults(3),  DtSearchFreeResults(3),  DtSearchHasMessages(3), DtSearchAd-
       dMessages(3),  DtSearchGetMessages(3),	DtSearchFreeMessages(3),   Dt-

							 DtSrAPI(library call)


Want to link to this manual page? Use this URL:

home | help