n_setqry(), n_search(), n_closesrch() - Query handling functions

SYNOPSIS

#include "napi.h"
SRCH *n_setqry(SERVER *se,str q)
int   n_search(SERVER *se,SRCH *sr)
SRCH *n_closesrch(SERVER *se,SRCH *sr)
int   n_regqryed(SERVER *se,void *usr,func cb)
      func cb(void *usr,QRY *q);

DESCRIPTION
These functions comprise the real work that is to be performed by the network API server. The client program will call the n_setqry() function with a SERVER * and a string containing the user's query . The server will then return a SRCH * which will be used as the second argument to the n_search() and n_closesrch functions. If there is an error then the n_setqry() will return the value SRCHPN . A query edit callback will be called by n_setqry() if one has been registered by n_regqryed().

The effects of any of search parameter modification calls ( like setls() for example ) are frozen with respect to the open SRCH *. If you need to change any characteristic of the search you must close, modify and then re-open the search. The API's are implemented in this fashion so that all query operations work as deltas off the prior query instead of having to completely re-setup the parameters each time.

The client program may have as many SRCH *s open simultaneously as it needs. This is to say that you are not limited to one handle per open server connection. This can be handy if you are trying to create some kind of remote message processing system.

To initiate the actual search the program makes a call to the n_search() function. The server will begin to call the client's callback routine that was set in the n_reghitcb() call. The n_search() function will return 0 on error or true if all goes well. NOTE: It is not considered an error for there to be zero hits located by a search. A client's callback routine will never be invoked in this instance.

A call to the n_closesrch() function will clean-up after you are done using a SRCH *. You should make a call to this function as soon as the SRCH * is no longer needed, otherwise, precious server resources will be allocated for no reason. n_closesrch() will always return a SRCHPN.

If a query edit callback has been registered by n_regqryed() it will be called after a successful equiv lookup and before the search is initialized. It is called with the void pointer provided to n_regqryed() and a QRY pointer that contains everything about the query.

The user query edit function is intended for those applications that wish to process the results of the command line/thesaurus lookup process before the remainder of the n_setqry() processing occurs.

The return value from the query edit callback determines whether to go ahead with the search or not. A return value of non-zero means ok, go ahead with search initialization. A return value of zero means error. An error return from the query edit callback will then cause n_setqry() to return an error.

The QRY structure passed to the query edit callback is defined as follows:

QRYITEM                             /* everything about a search item */
{
 int  logic;                                /* logic of item: LOGI... */
 int  pmtype;                             /* pattern matcher: PMIS... */
 int  thresh;                     /* XPM threshold if pmtype==PMISXPM */
 str *eqvs;                                          /* list of terms */
 str *clas;                 /* list of classifications, 1:1 with eqvs */
};
QRY                           /* everything about the query for qryed */
{
 QRYITEM qi[MAXSELS]; /* list of items, only ni filled in, rest NULLs */
 int     ni;                                     /* number of qi used */
 int     intersects;                  /* intersections, (-1) if unset */
};

QRYITEM qi[MAXSELS] -- A list of search items.

int ni -- A count of how many items in qi are used. Unused items have all of their pointer members set to NULL.

int intersects -- The intersection quantity specified in the query via @ or (-1) if not set.

int logic -- The set logic being applied to the search item. It will be one of: LOGIAND, LOGISET, LOGINOT.

int pmtype -- The pattern matcher that will be used to find the item. It will be one of: PMISREX, PMISSPM, PMISPPM, PMISNPM, PMISXPM.

int thresh -- The threshold percentage used by XPM if pmtype is PMISXPM. Otherwise it has no meaning.

str *eqvs -- A list of the pattern or string being searched for and all of its equivalences. This always will have one item except when pmtype is PMISPPM.

str *clas -- A list that parallels the eqvs list and contains the classifications for each term in eqvs.

EXAMPLE

int
qryed(usr,q)                          /* query edit callback function */
void *usr;
QRY *q;
{                           /* just print everything for this example */
 int i, j;
 QRYITEM *qi;

 printf("ni=%d, intersects=%d\n",q->ni,q->intersects);
 for(i=0;i<q->ni;i++)                       /* loop through all terms */
    {
     qi=q->qi+i;                  /* alias the pointer for simplicity */
     printf("logic=%d, pmtype=%d, thresh=%d\n",
            qi->logic,qi->pmtype,qi->thresh);
     for(j=0;*qi->eqvs[j]!='\0';j++)         /* loop through all eqvs */
         printf("   \"%s\";\"%s\"\n",qi->eqvs[j],qi->clas[j]);
    }
 return(1);                                     /* say ok to continue */
}

{
 SERVER *se;
 SRCH *sr;
 ...
 n_regqryed((void *)NULL,qryed);     /* setup the query edit callback */
 if((sr=n_setqry(se,query))!=SRCHPN)               /* setup the query */
    {
     if(!n_search(se,sr))                            /* find all hits */
         puts("n_search() failed");
     n_closesrch(se,sr);                         /* cleanup the query */
    }
 ...
}

CAVEATS
Don't count on the closeserver() call to perform automatic n_closeqry() calls for you.