*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->HP-UX 11i man pages -> DtSrAPI (3)              


 DtSrAPI(library call)                                 DtSrAPI(library call)

 NAME    [Toc]    [Back]
      DtSrAPI - Describes overview, constants, and structures for DtSearch
      online API

 DESCRIPTION    [Toc]    [Back]
      The DtSearch API provides programmatic access to the DtSearch search
      and retrieval engine. The API functions are located in the library
      libDtSr, and are directly linked into user written search programs.

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

      DtSearchInit    [Toc]    [Back]
                Opens databases and other files, and generally initializes
                the search engine for subsequent requests.

      DtSearchQuery    [Toc]    [Back]
                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.

      DtSearchRetrieve    [Toc]    [Back]
                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.

    DtSearch MessageList    [Toc]    [Back]
      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.

      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

    Fatal API Errors    [Toc]    [Back]
      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.

                                    - 1 -       Formatted:  January 24, 2005

 DtSrAPI(library call)                                 DtSrAPI(library call)

      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

 CONSTANTS    [Toc]    [Back]
    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
      DtSrNOTAVAIL       Generic negative response. For example,
                         no hits on search, no such record, etc.
      DtSrFAIL           Miscellaneous unsuccessful engine
      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    [Toc]    [Back]
      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
      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    [Toc]    [Back]
      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

                                    - 2 -       Formatted:  January 24, 2005

 DtSrAPI(library call)                                 DtSrAPI(library call)

    DtSrObjdate Type    [Toc]    [Back]
      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
      minimize 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
      resolution 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)

 STRUCTURES    [Toc]    [Back]
    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
      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.

      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

    DtSrResult Structure    [Toc]    [Back]

                                    - 3 -       Formatted:  January 24, 2005

 DtSrAPI(library call)                                 DtSrAPI(library call)

      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.

      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

                Values above x1000 (4096) are set aside for application
                definition. The following constants identify defined values:
                DtSrObjUNKNOWN           Document type unknown or not
                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

                                    - 4 -       Formatted:  January 24, 2005

 DtSrAPI(library call)                                 DtSrAPI(library call)

      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    [Toc]    [Back]
      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 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.

 SEE ALSO    [Toc]    [Back]
      DtSrAPI(3), DtSearchInit(3), DtSearchReinit(3), DtSearchExit(3),
      DtSearchGetKeytypes(3), DtSearchSetMaxResults(3),
      DtSearchGetMaxResults(3), DtSearchQuery(3), DtSearchRetrieve(3),
      DtSearchHighlight(3), DtSearchValidDateString(3),
      DtSearchMergeResults(3), DtSearchSortResults(3),
      DtSearchFreeResults(3), DtSearchHasMessages(3),
      DtSearchAddMessages(3), DtSearchGetMessages(3),
      DtSearchFreeMessages(3), DtSearch(5)

                                    - 5 -       Formatted:  January 24, 2005
[ Back ]
 Similar pages
Name OS Title
DtSearchReinit HP-UX Reinitialize the DtSearch online API
DtSearchInit HP-UX Initialize the DtSearch online API for subsequent calls
unistd HP-UX standard structures and symbolic constants
langinfo HP-UX language information constants
limits HP-UX implementation-specific constants
langinfo IRIX language information constants
pxfconst IRIX Returns the value associated with symbolic constants
math HP-UX math functions, constants, and types
constant IRIX Perl pragma to declare constants
ep IRIX FORTRAN numeric characteristic constants
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service