n_xpminfo(), n_freexpmi() - Hit information

SYNOPSIS

#include <sys/types.h>
#include "tstone.h"
XPMI *n_xpminfo(SERVER *se,SRCH *sr,int index);
XPMI *n_freexpmi(SERVER *se,XPMI *xi);

DESCRIPTION
These functions may be used within the hit callback function to obtain detailed information about any search terms that may have used the approximate pattern matcher (XPM). n_xpminfo() is called with the index of the desired XPM.

It returns a structure containing everything about that XPM. It returns XPMIPN if index is out of bounds.

To get all XPM subhits put n_xpminfo() in a loop with index starting at zero and incrementing until XPMIPN is returned.

Each valid structure returned by n_xpminfo() should be freed by calling n_freexpmi() when it is no longer needed.

The XPMI structure contains the following members:

XPMI                                                    /* XPM Info */
{
 word  thresh;             /* threshold above which a hit can occur */
 word  maxthresh;                          /* exact match threshold */
 word  thishit;                             /* this hit's threshold */
 word  maxhit;                      /* max threshold located so far */
 char *maxstr;                    /* string of highest value so far */
 char *srchs;                            /* string being search for */
};

CAVEATS
Don't expect XPMI.thresh to be the percentage entered in the query passed to n_setqry(). It is an absolute number calculated from that percentage and the search string.

EXAMPLE

int
hit_handler(usr,tx,fl)
void *usr;  /* my user-data pointer */
TEXIS *tx;  /* Texis API handle */
FLDLST *fl; /* The field list data structure */
{
 ...
 MYAPP   *ts=(MYAPP *)usr;
 SERVER  *se=ts->se;
 SRCHLST *sl;
 SRCHI   *si;
 XPMI    *xi;
 int      i, j, k;

 ...
 sl=n_getsrchlst(se,tx);        /* get list of Metamorphs for query */
 if(sl!=SRCHLSTPN)
    {
     for(i=0;i<sl->n;i++)                     /* for each Metamorph */
         {
          SRCH *sr= &sl->lst[i];                           /* alias */
                                          /* loop thru all sub-hits */
            /* the zero index for n_srchinfo is the whole hit       */
            /* the one  index for n_srchinfo is the start delimiter */
            /* the two  index for n_srchinfo is the end delimiter   */
            /* the remaining indices are the subhits                */
          for(j=0;(si=n_srchinfo(se,sr,j))!=SRCHIPN;j++)
              {
               char *p, *e;              /* scratch buffer pointers */
               switch(j)
               {
                case 0 :printf(" HIT    (%s):%d:",si->what,si->len);
                        break;
                case 1 :printf(" S-DELIM(%s):%d:",si->what,si->len);
                        break;
                case 2 :printf(" E-DELIM(%s):%d:",si->what,si->len);
                        break;
                default:printf(" SUB-HIT(%s):%d:",si->what,si->len);
                        break;
               }
               for(p=si->where,e=p+si->len;p<e;p++)
                   if(*p<32 && *p!='\n' && *p!='\t')
                      printf("\\x%02x",*p);
                   else
                      putchar(*p);
               printf("\n");
               n_freesrchi(se,si);            /* free any mem in si */
              }
          for(k=0;(xi=n_xpminfo(se,sr,k))!=XPMIPN;k++)
             {                                    /* loop thru XPMs */
              printf("XPM: \"%s\": thresh %u, maxthresh %u, thishit %u",
                     xi->srchs,xi->thresh,xi->maxthresh,xi->thishit);
              printf("\n   : maxhit %u, maxstr \"%s\"\n",
                     xi->maxhit,xi->maxstr);
              n_freexpmi(se,xi);                  /* free mem in xi */
             }
         }
     n_freesrchlst(se,sl);
    }
 ...

 return(1);          /* tell the server to keep giving me more hits */
}

SEE ALSO
The example program netex3.c, n_reghitcb(), n_getsrchlst(), n_srchinfo().