The ZServer has been designed to hide the details of the Z39.50 protocol and minimize the effort required to interface it with a variety of IR applications. A high-level list of the tasks involved in such an effort must include the following:
What follows is a listing of the main files which describe the ap_services interface:
/*----------------------------------------------------------------------------*
* AP_SERVICES function specifications
*
* The following functions define the interface to the ap_services layer, which
* mediates between the application-independent zservices layer and the IR
* application, which knows nothing of the zservices and Z39.50 as such.
*
* The interface is composed of 5 functions which must be implemented:
*
* ap_initdb
* ap_closedb
* ap_delete
* ap_search
* ap_present
*
* and 4 functions which are optional - not even stubs are required:
*
* ap_zqtran \
* ap_help \
* ap_feedback > not called if function does not exist
* ap_generic /
*
* Ap_help, ap_feedback, and ap_generic use the standard Z39.50 Search
* request and a non-standard convention on query content to provide
* applications with a simple way of implementing help, feedback and
* other commands not yet supported by the ZServer.
*
* ZServer expects one of the following return codes from each of these
* functions:
*
* RET_OK - operation succeeded
* results valid
* ZServer should continue processing requests
*
* RET_ERROR - operation did not succeed
* results may be incomplete and/or invalid
* ZServer can continue processing request
* check in error_info structure for more info
*
* RET_FAIL operation did not succeed
* results may be incomplete and/or invalid
* ZServer should not continue processing request
* check in error_info structure for more info
*
*----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------
* Given an intialized database and a query, search the database using the
* query and return a result set and/or error information.
*
* This function must be implemented.
*
* Usage: Will be called in response to a Z39.50 Search request.
*----------------------------------------------------------------------------*/
int ap_search (AP_QUERY* query,
db_tuple* db,
AP_RESULT_SET* result_set,
AP_ERROR_DATA* error_info);
/*-----------------------------------------------------------------------------
* Given a result set, an index into it, and formatting information, return
* the formatted information associated with the result set item and/or
* error information.
*
* This function must be implemented.
*
* Usage: Called in response to a Z39.50 Present request.
*----------------------------------------------------------------------------*/
int ap_present (AP_RESULT_SET* result_set,
int doc_i,
STR_BUF* buf,
AP_FORMAT_DATA* format,
AP_ERROR_DATA* error_info);
/*-----------------------------------------------------------------------------
* Given a result set, delete it.
*
* This function must be implemented but may do nothing.
*
* Usage: Called in response to a Z39.50 search request to allow the
* application to release resources associated with the result set.
*----------------------------------------------------------------------------*/
int ap_delete (AP_RESULT_SET* result_set,
AP_ERROR_DATA* error_info);
/*-----------------------------------------------------------------------------
* Given a database specification, initialize the database and return an
* updated specification and/or error information.
*
* This function must be implemented.
*
* Usage: Called in response to a Z39.50 search request if the database
* being searched has not been initialized.
*----------------------------------------------------------------------------*/
int ap_initdb (db_tuple* db,
AP_ERROR_DATA* error_info);
/*-----------------------------------------------------------------------------
* Given a database specification, close the database and return an updated
* specification and/or error information.
*
* This function must be implemented.
*
* Usage: Called whenever the server decides a database should be
* released.
*----------------------------------------------------------------------------*/
int ap_closedb (db_tuple* db,
AP_ERROR_DATA* error_info);
/*----------------------------------------------------------------------------
* Given a Z39.50 Query structure, database information, and the protocol
* version in force, translate the Z39.50 into whatever the application
* finds useful.
*
* Note: any application-specific query storage must be released by the
* application - e.g. via ap_search when the search is completed. Query
* data that must persist across search requests can be stored in the
* application-specific part of the result.
*
* This function need not be implemented. A default query translation routine
* will be invoked if ap_zqtran has not been implemented.
*
* Usage: Called as part of search processing before invoking the IR application
*---------------------------------------------------------------------------*/
int ap_zqtran ( Query* zquery,
db_tuple* db,
AP_QUERY* ap_query_p,
int protocol_version,
AP_ERROR_DATA* error_info )
/*-----------------------------------------------------------------------------
* The following interface makes special use of the Z39.50 Search service
* interface and a non-Z39.50 convention on query content and is intended to
* help applications support feedback.
*
* This function need not be implemented.
*
* Usage: Called when the query, as translated by the supplied translator,
* is made up of a single operand (no operators) beginning with the
* string "NLfeedback".
*
* Given a list of indices into the current result set, add the corresponding
* documents to the list of relvant documents and use the rest of the
* user's query string as a query against the given database and return a
* result set and/or error information.
*
*----------------------------------------------------------------------------*/
int ap_feedback (db_tuple* db,
AP_FEEDBACK* feedback_query,
AP_RESULT_SET* result_set,
AP_ERROR_DATA* error_info);
/*-----------------------------------------------------------------------------
* The following interface makes special use of the Z39.50 Search service
* interface and a non-Z39.50 convention on query content and is intended to
* help applications support help.
*
* This function need not be implemented.
*
* Usage: Called when the query, as translated by the supplied translator,
* is made up of a single operand (no operators) beginning with the
* string "NLhelp".
*
* Given a buffer containing a request (input query operand after "NLhelp")
* and a database, return help information in the answer buffer. The server
* displays the answer buffer as a simple unstructured document.
*
*----------------------------------------------------------------------------*/
int ap_help (db_tuple* db,
STR_BUF* help_request,
STR_BUF* help_answer,
AP_ERROR_DATA* error_info);
/*-----------------------------------------------------------------------------
* The following interface makes special use of the Z39.50 Search service
* interface and a non-Z39.50 convention on query content and is intended to
* help applications support generic commands.
*
* This function need not be implemented.
*
* Usage: Called when the query, as translated by the supplied translator,
* is made up of a single operand (no operators) beginning with the
* string "NLgeneric".
*
* Given a buffer containing a generic request (input query operand after
* "NLgeneric") and a database, return the results of filling the request
* in the response buffer. The server displays the answer buffer as a simple
* unstructured document.
*----------------------------------------------------------------------------*/
int ap_generic (db_tuple* db,
STR_BUF* command,
STR_BUF* response,
AP_ERROR_DATA* error_info);
/*----------------------------------------------------------------------------*
* D a t a S t r u c t u r e s
*----------------------------------------------------------------------------*/
typedef struct {
int num_wanted;
enum ap_query_type_id {
AP_QUERY_TYPE_TEXT,
AP_QUERY_TYPE_BOOLEAN,
AP_QUERY_TYPE_LIMIT /* The number of query types. */
} query_type;
union ap_query_type_union {
char* text;
void* boolean; /* Not defined, yet. Not implemented, yet. */
} u;
} AP_QUERY;
/*----------------------------------------------------------------------------*/
typedef struct {
char* name; /* The name of this result set. */
int size; /* The number of records in this result set. */
void* result; /* The result set. */
/* The structure and content of this data is */
/* known only to the application. */
db_tuple* db; /* Information about the database this result */
/* set is from. */
} AP_RESULT_SET;
/*----------------------------------------------------------------------------*/
typedef struct _db_tuple
{
char *name; /* The name of the database, known to both the */
/* origin and target. */
char *path; /* The directory where this database resides. */
char *ap_name; /* Name of the search application to be used when*/
/* searching this database. Only 1 for now. */
void *info; /* Information about this database required by */
/* the search and retrieval application. */
/* The structure and content of this data is */
/* known only to the application. */
} db_tuple;
/*----------------------------------------------------------------------------*/
typedef struct
{
int condition; /* ZServer does not react to these; just passes */
char * addinfo; /* them on to the client, which displays both. */
} AP_ERROR_DATA;
/*----------------------------------------------------------------------------*/
typedef struct
{
AP_QUERY * query;
int num_rel;
long * rel_internal_docid;
int num_nonrel;
long * nonrel_internal_docid;
int num_seen;
long * seen_internal_docid;
} AP_FEEDBACK;
/*----------------------------------------------------------------------------*/
typedef struct
{
int len;
char * str;
} STR_BUF;