% Studienarbeit von Ulrike Steffens
%
% Universitaet Hamburg
% Fachbereich Informatik
% Arbeitsbereich DBIS
%
% Anhang: Tycoon Schnittstellen f"ur das System INQUERY
% 2.4.96

\chapter{Tycoon Schnittstellen f"ur das System INQUERY}
\label{ti}
\section{{\em Dbinfo.ti}: Zugang zu INQUERY Datenbanken}
\label{dbinfo}
\begin{xple}
\k{interface} Dbinfo
(* System:  Inquery
   File:       Dbinfo.ti
   Author:  Ulrike Steffens
   Date:     10-Oct-1995
   Purpose: Operations to administer the databases of an INQUERY 
                information retrieval system
*)

\k{import}
   list
   word
   :DbinfoHidden

\k{export}

  T $<$:\k{Ok}

  \k{Let} Representation = \k{Tuple} db :word.T  isOpen :Bool \k{end}
  (* External Representation of Dbinfo.T *)

  getRepresentation(t :T) :Representation

  error :\k{Exception end}
\newpage
  new(dbName, stopWordFile :String
        defaultBeliefValue, termFrequency :Real) :T
  (* Create a new dbinfo structure given the name of the
  database used, the name of a stopword file,
  the name of a relevance file, the default belief value
  and the default term frequency value *)        

  free(db :T) :\k{Ok}
  (* Free a dbinfo structure *)

  opendb(db :T) :\k{Ok}
  (* Open a database for use by the INQUERY retrieval system.
  Currently only one database can be open at a time *)

  closedb(db :T) :\k{Ok}
  (* Close a database, should be called before opening a new
  database and before exiting from an INQUERY session *)

  getDatabaseList(directoryName :String) :list.T(String)
  (* Return a list of databases available for INQUERY in a
  certain directory *)

  setName(db :T dbName :String) :\k{Ok}
  (* Set the name field of a dbinfo structure *)

  getName(db :T) :String
  (* Get the name field of a dbinfo structure *)

  setStopWordFile(db :T stopWordFile :String) :\k{Ok}
  (* Set the stopword name field of a dbinfo structure *)
	
  setTermFrequency(db :T termFrequency :Real) :\k{Ok}
  (* Set the term frequency field of a dbinfo structure *)

  setDefaultBeliefValue(db :T defaultBeliefValue :Real) :\k{Ok}
  (* Set the default belief value of a dbinfo strucure  *)

  setStopping(db :T onOff :Bool) :\k{Ok}
  (* Set stopword processing on or off *)
\newpage
  setStemming(db :T onOff :Bool) :\k{Ok}
  (* Set word stemming on or off *)

  getStopping(db :T) :Bool
  (* Get stopword processing flag *)

  getStemming(db :T) :Bool
  (* Get stemming processing flag *)

\k{end};
\end{xple}

\section{{\em Query.ti}: Parsing und Auswertung von Anfragen}
\label{query}

\begin{xple}
\k{interface} Query
(* System:  Inquery
   File:       Query.ti
   Author:  Ulrike Steffens
   Date:     10-Oct-1995
   Purpose: Operations to generate and evaluate queries for 
               the use by an INQUERY information retrieval system
*)
	    
\k{import}
   list
   dbinfo

\k{export}

   T $<$:String
   (* A parsed Query *)

   Info $<$:\k{Ok}
   (* Stores query term information containing the parsed 
   query string and a list giving information about each term
   in the query *)

   BeliefElement $<$:\k{Ok}
   (* Information about one retrieved element, a part of :Result.
   May be accessed by getElementDocID and getElementBelief *)
\newpage
   Results $<$:\k{Ok}
   (* Information about all retrieved elements. May be accessed by   
   getResultDefaultBelief, getResultDocCount and getResultBeliefList *)

   error :\k{Exception end}

   check(db :dbinfo.T qstring :String) :Info
   (* Parse a query string storing information about each of the
   recognized term. The resulting information can be accessed by
   the following getInfo-functions. Raise exception if empty
   qstring is checked   *)

   getInfoErrorCode(info :Info) :String
   (* Return possible error code of checking process *)

   getInfoErrorOffset(info :Info) :Int
   (* Return offset of error in query. Only meaningful if
   error code is not ''no error'' *)

   getInfoParsed(info :Info) :T
   (* Return the final parsed query resulting of checking process *)

   getInfoNumOfTerms(info :Info) :Int
   (* Return the total number of terms in the query *)

   getInfoNumOfStopWords(info :Info) :Int
   (* Return the number of stop words in the query *)

   getInfoNumOfNotFound(info :Info) :Int 
   (* Return the number of non-indexed words in the query *)

   getInfoNumOfTransformers(info :Info) :Int
   (* Return the number of transformers identified during
   checking process *)

   getParsed(db :dbinfo.T queryString :String) :T
   (* Process a parsed query string. Processing is the same 
   as that done by check, except that a history of the 
   processing steps is not retained in an :Info. Raise exception
   if empty qstring is parsed *)

   initTransformer(transformerName :String onOff :Bool) :\k{Ok}
   (* Turn a named query transformer on or off. Available right
   now are: ''stop\_phrases'', ''location'', ''hyphens\_caps'', ''company\_tags''
   and ''retain\_capitalized\_stopwords''. For more infromation about
   transformers see documentation *)

   initAllTransformers(onOff :Bool) :\k{Ok}
   (* Turn on or off all query transformers *)

   setStemming(onOff :Bool) :\k{Ok}
   (* Set stemming flag during query processing. Query stemming
   is on by default *)

   getStemming() :Bool
   (* Get the current value of the query stemming flag *)

   eval(db :dbinfo.T queryString :String) :Results
   (* Evaluate the unparsed query and return the results in
   a belief list. A feedback function may display the progress
   of evaluation, but can be a function doing nothing *)

   evalTopN(db :dbinfo.T queryString :String 
                maxRetrievedDocs :Int) :Results
   (* Evaluate the unparsed query returning a belief list
   containing no greater than maxDocs documents, apart from
   that identical to function ''eval'' *)

   evalParsed(db :dbinfo.T parsedQuery :T) :Results
   (* Evaluate the parsed query and return the results in a 
   belieflist. A feedback function may display the progress of
   evaluation *)

   evalParsedTopN(db :dbinfo.T parsedQuery :T 
                         maxRetrievedDocs :Int) :Results
   (* Evaluate the parsed query returning a belief list
   containing no greater than maxDocs documents, apart from
   that identical to function ''evalParsed'' *)

   getResultDefaultBeliefValue(results :Results) :Real
   (* Return the default belief value of a set of retrieved elements *)
\newpage
   getResultNumOfRetrievedDocs(results :Results) :Int
   (* Return the number of retrieved elements *)

   getResultBeliefList(results :Results) :list.T(BeliefElement)
   (* Return a list of all retrieved elements *)

   getElementDocID(beliefElement :BeliefElement) :Int
   (* Return the document id of a retrieved element *)

   getElementBeliefValue(beliefElement :BeliefElement) :Real
   (* Return the belief value of a retrieved element *)

\k{end};
\end{xple}

\section{{\em Docs.ti}: Zugang zu Dokumenten}
\label{docs}

\begin{xple}
\k{interface} Docs
(* System:  Inquery
   File:       Docs.ti
   Author:  Ulrike Steffens
   Date:     10-Oct-1995
   Purpose: Operations to administer documents retrieved by the
               INQUERY information retrieval system.
*)

\k{import}
   dbinfo
   query

\k{export}

   T $<$:\k{Ok}
   (* The actual document consisting of a number of component fields *)

   FieldType $<$:\k{Ok}

   newField(:String) :FieldType
   (* Return a new value of type FieldType in behalf of a certain
   database *)
\newpage
   FID :FieldType
   FSOURCE :FieldType
   FTEXT :FieldType
   FTITLE :FieldType
   (* Determines which component field of a retrieved document
   is actually worked with. Take into consideration that not all
   possible combinations of Mode and FieldType actually make sense *)

   Match $<$:\k{Ok}
   MatchesArray $<$:\k{Ok}
   (* Helpful structures to find out where the query has matched
   with the retrieved document, processed in dependence of a single
   document component field *)

   Field $<$:\k{Ok}
   (* One document might consist of several component fields *)

   error :\k{Exception end}

   get(db :dbinfo.T docID :Int parsedQuery :query.T) :T
   (* Retrieve document specified by ''id'' in database. Get certain
   match information about a specified query string. Don't forget
   to free the document after use! *)

   free(doc :T) :\k{Ok}
   (* Free the internal buffer that contains document text *)

   getField(doc :T fieldType :FieldType) :Field
   (* Get component fields of a document *) 
	
   getFieldText(docField :Field) :String
   (* Get text out of a document field *)

   getNumOfFieldMatches(docField :Field) :Int
   (* Get the number of matches out of a document field *)

   getFieldMatches(docField :Field) :MatchesArray
   (* Get matches out of a document field *)

   numOfDocsInCollection(db :dbinfo.T) :Int
   (* Get number of documents in INQUERY database specified *)

   numOfTermPostingsInCollection(db :dbinfo.T term :String) :Int
   (* Get number of documents in which a term occurs for the
   specified database *)
 
   termFrequencyInCollection(db :dbinfo.T term :String) :Int
   (* Get the total number of occurrences of a term in the
   specified collection *)

   externalToInternalID(db :dbinfo.T exID :String) :Int
   (* Convert an external document id to its internal INQUERY equivalent *)

   internalToExternalID(db :dbinfo.T inID :Int) :String
   (* Convert INQUERY's internal document id to it's external equivalent *)

   sortMatchesByPosition(matches :MatchesArray) :\k{Ok}
   (* Sort a list of query term matches by position (offset) *)

   rewindMatchList(matches :MatchesArray) :\k{Ok}
   (* Rewind the current match pointer to the beginning of the match list *)

   getNextMatch(matches :MatchesArray) :Match
   (* Get the item from a list of matches *)

   getPreviousMatch(matches :MatchesArray) :Match
   (* Get the previous match from a list of matches *)

   getNumOfMatches(matches :MatchesArray) :Int
   (* Get the number of matches out of a MatchesArray *)

   getMatchTerm(match :Match) :String  
   (* Return a term string from the match *)

   getMatchOffset(match :Match) :Int
   (* Return the value from a match offset field, raise error
   if match is empty *)

   getMatchLength(match :Match) :Int 
   (* Return value in a match length field, raise error if match is empty *)

   getMatchEnd(match :Match) :Int
   (* Return end offset value in a match, raise error if match is empty *)

   addNewIndex(name, description :String) :Int
   (* Add a new index for field retrieval *)

\k{end};
\end{xple}
