n_getsrchlst(), n_freesrchlst(), n_srchinfo(), n_freesrchinfo(), n_fillsrchlst() - Hit information

SYNOPSIS

#include <sys/types.h>
#include "tstone.h"
SRCHLST
{
 int n;                                /* number of elements in lst */
 SRCH lst[];                          /* list of Metamorph searches */
};
MMOFFS                                  /* Metamorph subhit offsets */
{
   int n;                               /* number if off's in array */
   MMOFFSE
   {
      long start;                 /* byte offset of start of region */
      long end;                           /* one past end of region */
   } *off;                                  /* array of offset info */
};
SRCHLST *n_getsrchlst(SERVER *se,TEXIS *tx);
SRCHLST *n_freesrchlst(SERVER *se,SRCHLST *sl);
int      n_fillsrchlst(SERVER *se,TEXIS *tx,FLDLST *fl);

SRCHI
{
 char *what;                               /* what was searched for */
 char *where;                                     /* what was found */
 int   len;                               /* length of where buffer */
};
SRCHI   *n_srchinfo(SERVER *se,SRCH *sr,int i);
SRCHI   *n_freesrchi(SERVER *se,SRCHI *si);

DESCRIPTION
These functions may be used within the hit callback function to obtain detailed information about any Metamorph queries that may have been used in the query. n_getsrchlst() takes the TEXIS handle passed to the hit callback function and returns a list of handles to all Metamorph searches associated with the query. These handles may then be used in calls to n_srchinfo(). SRCHLSTPN is returned on error. SRCHLST members:

int n -- The number of searches contained in lst.

SRCH lst[] -- The array of searches.

The SRCHLST returned by n_getsrchlst() should be freed by calling n_freesrchlst() when it is no longer needed.

n_fillsrchlst() fills in the SRCHLST *sl[] and MMOFFS mmoff[] arrays in the supplied FLDLST. This provides the Metamorph search handles, if any, for each individual field. This supercedes n_getsrchlst() because it is more generally useful. It also provides a list of all subhit offsets for each individual field. This greatly simplifies hit tagging if all you need is the offset information about each subhit. n_fillsrchlst() always returns non-zero meaning success.

The MMOFFS->off member is an array of start and end offsets of subhits within the field. MMOFFS->n is the number of entries in the off array. Each off is made of two members: long start and long end. Start is the byte offset of the subhit within the field. End is the byte offset of the end of the subhit within the field plus one (plus one makes for() loops easier to write). The offs array contains subhits from all Metamorphs that may have been applied to the field. Offsets are sorted in ascending order by start offset. Overall hit and delimiter offsets are not included in the MMOFFS list. MMOFFS contains the offsets that would be returned with indices 3-n of n_srchinfo(), but sorted.

Many queries do not need to apply Metamorph to the actual field as the index is sufficient to decide if there is a hit or not, and so will not return any hit information. If the query orders the results it is possible that the engine will have finished using the Metamorph engine before the results are returned to the user, and so the results are no longer available. If you need accurate hit-offset information it is suggested that you use the Metamorph API at the client side to search the field returned.

The memory allocated by n_fillsrchlst() should not be freed because it is managed automatically.

n_srchinfo() takes a search handle and the index of the sub-hit to return information about. It returns a SRCHI pointer on success or SRCHIPN on error or if the index is out of range. The index may be controlled by a loop to get information about all parts of the hit.

Index values and what they return:

xxxxxx = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx = xxxxxxxxxxxxxxxxxxxxx 
Index  > SRCHI->what points to   > SRCHI->where contains 
0      > The original query             > The whole hit         
1      > A regular expression           > The start delimiter   
2      > A regular expression           > The end delimiter     
3-n    > The "set" being searched for > The match             
       > as listed below                >

xxxxxxxxx = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
Set type  > SRCHI->what points to       
REX       > A regular expression               
NPM       > The npm query expression           
PPM       > The root word of the list of words 
XPM       > The "approximate" string

Each SRCHI returned by n_srchinfo() should be freed by calling n_freesrchi() when it is no longer needed.

CAVEATS
The subhit offsets returned by n_srchinfo() are not sorted.

SEE ALSO
n_xpminfo() and its example.