NAME

Liz::Nextrieve - Search with Nextrieve in a Liz::SQL database module


SYNOPSIS

 use Liz::Nextrieve;

 $nextrieve = new Liz::Nextrieve;


EXAMPLES

 #!/usr/local/bin/perl

 use Liz::Nextrieve;


DESCRIPTION

The Liz::Nextrieve package allows the use of the Nextrieve search engine with many added features. To be able to create these features, information about the search database (such as location and search results) is kept in a Liz::SQL compatible database.


CLASS METHODS

The following methods can be called without an object specification, but as a class method such as Liz::Nextrieve->method().


engines

Return list of identification names of all Nextrieve search engines in the database specified.

Input Parameters

 1 wildcard specification to match
   (default: all)
 2 reference to routine that performs connect
   (default: &Connect from caller's namespace)
Output Parameters

 1 reference to list of identification names in the current database
 2 reference to hash with full names
 3 reference to hash with version info


new

Create a new Liz::Nextrieve object. Creates connection or re-establishes connection with the MySQL database.

Input Parameters

 1 Liz::SQL compatible handle
 2 identification name of search engine
   (default: default search engine for database)
Output Parameters

 1 instantiated object
Example

 $hn = new HN;
 $search = Liz::Nextrieve->new( $hn,'hospitorg' );
 $search = $hn->SearchEngine( 'hospitorg' );


delete

Delete one or more queries from the Liz::Nextrieve database without first having to create an object for each query to be deleted.

Input Parameters

 1..N message ID's to be deleted


INDEXING METHODS

The following methods allow indexing for a search engine.


Index

Index the list of files previously indicated, e.g. with a call to method Tree.

Input Parameters

 1 directory in which to place the resulting indexes
   (default: 'indexes')
 2 type of information to be indexed
   (default: 'html', other values: ascii, mail and auto)
Output Parameters

 1 flag: whether successful


CACHING METHODS

The following methods are related to the cached queries in the MySQL database.


CleanCache

Remove the queries that are older than the specified time from the currently cached in the database. Use method ResetCache to remove all cached entries from the cache.

Input Parameters

 1    expiration time of the cached queries in minutes
      (default: 480 minutes = 8 hours)
Output Parameters

 1..N ID's of queries that have been removed
Example

 $search->CleanCache;
 $search->CleanCache( 4*60 );


Queries

Return all queries that have currently been cached in the database since the last time the Nextrieve database was re-indexed.

Output Parameters

 1..N queries that were entered
Example

 $queries = join( "\n",$search->Queries );
 print "The following queries are cached:\n$queries\n";


ResetCache

Remove all queries currently cached in the database. Use method CleanCache to only deletee entries older than a specific number of minutes.

Example

 $search->ResetCache;


MappedName

Return the mappedname field of a specific hit (indicated by ordinal number) of a specific cached query (indicated by ID). Usually used for click-through pages. In some applications (e.g. Search.NL), the mappedname field is actually used as a URL.

Input Parameters

 1 ID of the query of which to return the mappedname
 2 ordinal number of hit of which to return the mappedname
   (default: 1)
Output Parameters

 1 mappedname of the indicated hit
Example

 <PERL>Redirect( 'http:/'.SearchNL->new->SearchEngine->MappedName( $ID,$hit ) )</PERL>


SEARCH METHODS

The following methods allow indexing for a search engine.


Search

Search for the indicated query in the database.

Input Parameters

 1 query to search for
 2 first search result to be returned
   (default: 1)
 3 number of search results to return
   (default: rest)
Output Parameters

 1 number of hits returned
 2 number of hits found


FetchRow

Fetch a row of the search result as specified with the Fields method. Automatically fetches next row of the search result if no specific entry is specified.

Input Parameters

 1 entry in result list of which to obtain row
   (default: next, starts at value specified with Search)
Output Parameters

 1 array with values in order of fields specification


CONTENT METHODS

The following methods allow changes to information that is associated with an entire search engine.


Cached

Return whether the last search result was already cached in the mySQL database before the query was done.

Output Parameters

 1 flag: whether result of query was cached


ID

Return the ID with which the query was cached in the MySQL database.

Output Parameters

 1 ID with which the query was cached


Name

Specify or return the current name of the search engine.

Input Parameters

 1 new name of the search engine
   (default: no change)
Output Parameters

 1 current/old name of nextrieve


Resource

Specify or return the current Nextrieve resource information of the object. Is usually called internally only, but can also be use from the ``outside''.

Input Parameters

 1 new resource information
   (default: no change)
Output Parameters

 1 current/old resource information


UTILITY METHODS

The following methods can be easy to use with a search engine.


PreviousNext

Return the HTML code to display to create a dual row of buttons to allow the user to page through the search result.

Input Parameters

  1 directory in which images are located
  2 height of images to be used (the same for all)
  3 name of image for previous entry
  4 width of image for previous entry
  5 name of image for current entry
  6 width of image for current entry
  7 name of image for other entry
  8 width of image for other entry
  9 name of image for next entry
 10 width of image for next entry
Output Parameters

 1 HTML (if any) to be inserted
Example

  </PERL>
  $buttons = $search->PreviousNext(
   '/vsb',15,
   'b_vorige.gif',35,
   'b_niet.gif',11,
   'b_wel.gif',11,
   'b_volgen.gif',41 );
  </PERL>
  <IF $buttons>
   <FORM><HIDDEN query $query><HIDDEN fuzzy $fuzzy>$buttons</FORM>
  <ENDIF>


AUTHOR

Elizabeth Mattijsen ( lizperl@INC.nl )


COPYRIGHT

(C) 1998-1999 International Network Consultants


HISTORY

Version 0.36, 13 October 1999

Method PreviousNext now does not set width and height of current and other image if it is not the first batch of results. This should save almost 1 K in traffic per subsequent request on Search.NL.

Methods Name and Resource now call TableMeta in a scalar context to prevent side-effects of the list context behaviour of TableMeta.

Version 0.35, 30 September 1999

Now no longer adds Exporter to ISA: it wasn't necessary.

Version 0.34, 2 September 1999

Method CleanCache now returns the ID's of the queries that have been removed.

Version 0.33, 31 August 1999

Method CleanCache now correctly calculates the timestamp: before the timestamp was calculated in GMT. now correctly calculates the timestamp: before the timestamp was calculated in GMT.

Version 0.32, 29 August 1999

Added LOCK TABLES sections around DELETE in <CleanCache> as the absence seems to place MySQL in a deadlock position, and thus lets MySQL crash on Search.NL.

Version 0.31, 27 August 1999

Adapted method CleanCache in such a way that the cleaning is not done in 2 large queries, but instead in a lot of smaller queries, causing less interference with search queries of other processes.

Version 0.30, 25 August 1999

New method MappedName added: return the filename of a specific cached query and hit number.

New method CleanCache added: clean the cache of entries older than a specific number of minutes.

Version 0.29, 24 August 1999

Method Search now updates the ``requested'' field in the database so that a record is kept of how many times a cached query was used.

New method ResetCache, to reset the database cache. Adapted Index to call this method.

Class method engines now calls Liz::SQL's ``sets'' to create list.

Method new now calls Liz::SQL's ``new'' to create database handle.

Changed to new source typography.

Version 0.28, 9 July 1999

Changed all CREATE TABLEs to the new Liz::SQL 'create' method.

Version 0.27, 23 June 1999

Changed from using method ``Exists'' to ``Count'' in method new so that it can check for the existence of a table much more quickly.

Version 0.26, 28 January 1999

Changed database format so that large previews, as a result of preview appending for identical files when using the distinct option, ar now also allowed, well up to 64K that is.

Version 0.25, 27 January 1999

Added support for Distinct option in the Nextrieve.pm module. It is now possible to indicate to only receive different filenames in the result, even if there is more than one match in a file.

Added support for database version upgrade.

Version 0.24, 6 October 1998

Reduced memory footprint by only using fully qualified global variables.

Version 0.23, 17 September 1998

New method Queries returns the queries that are currently cached already.

Version 0.22, 24 August 1998

Method Search now sets the query cached flag. Also, empty result lists are no longer cached, preventing Nextrieve errors from polluting the SQL database from faulty results.

New method Cached returns whether the result of a query was cached in the SQL database.

Version 0.21, 13 August 1998

Simplified method delete to use single queries instead of a loop.

Method engines now returns a reference to a hash for the names instead of just another list.

Version 0.2, 24 June 1998

New method PreviousNext added: returns HTML for a bar with buttons from which the user may select a page of the search result.

Version 0.1, 20 June 1998

First version of this true Perl module.