-/* $Id: api.h,v 1.19 2005-04-26 08:11:22 adam Exp $
+/* $Id: api.h,v 1.22 2005-05-03 09:11:34 adam Exp $
Copyright (C) 1995-2005
Index Data ApS
\brief Zebra API
Return codes:
- Most functions return an int. Unix-like, 0 means OK,
- non-zero means an error. The error info should be available
- via zebra_errCode and friends.
+ Most functions return ZEBRA_RES, where ZEBRA_FAIL indicates
+ failure; ZEBRA_OK indicates success.
*/
#ifndef IDZEBRA_API_H
long stime;
} ZebraTransactionStatus;
-/* Retrieval Record Descriptor */
+/** Retrieval Record Descriptor */
typedef struct {
int errCode; /* non-zero if error when fetching this */
char *errString; /* error string */
int score;
} ZebraRetrievalRecord;
-/* Scan Term Descriptor */
+/** Scan Term Descriptor */
typedef struct {
int occurrences; /* scan term occurrences */
char *term; /* scan term string */
This function is a simplified version of zebra_start_res.
*/
-YAZ_EXPORT ZebraService zebra_start(const char *configName);
+YAZ_EXPORT
+ZebraService zebra_start(const char *configName);
-/** \fn ZebraService zebra_start_res(const char *configName,
- Res def_res, Res over_res)
+/** \fn ZebraService zebra_start_res(const char *configName, \
+ Res def_res, Res over_res)
\brief starts a Zebra service with resources.
\param configName name of configuration file
\param def_res default resources
YAZ_EXPORT
ZEBRA_RES zebra_stop(ZebraService zs);
-/** \fn void zebra_filter_info(ZebraService zs, void *cd,
- void(*cb)(void *cd, const char *name))
+/** \fn void zebra_filter_info(ZebraService zs, void *cd, \
+ void(*cb)(void *cd, const char *name))
\brief lists enabled Zebra filters
\param zs service handle
\param cd callback parameter (opaque)
with zebra, be that searching or indexing. In simple apps
one handle is sufficient
*/
-YAZ_EXPORT ZebraHandle zebra_open(ZebraService zs);
+YAZ_EXPORT
+ZebraHandle zebra_open(ZebraService zs);
/** \fn int zebra_close(ZebraHandle zh)
\brief destroys Zebra session handle.
\param zh zebra session handle.
*/
-YAZ_EXPORT ZEBRA_RES zebra_close(ZebraHandle zh);
+YAZ_EXPORT
+ZEBRA_RES zebra_close(ZebraHandle zh);
/** \fn int zebra_errCode(ZebraHandle zh)
\brief returns error code for last error
\param zh zebra session handle.
*/
-YAZ_EXPORT int zebra_errCode(ZebraHandle zh);
+YAZ_EXPORT
+int zebra_errCode(ZebraHandle zh);
/** \fn const char *zebra_errString(ZebraHandle zh)
\brief returns error string for last error
\param zh zebra session handle.
*/
-YAZ_EXPORT const char *zebra_errString(ZebraHandle zh);
+YAZ_EXPORT
+const char *zebra_errString(ZebraHandle zh);
/** \fn char *zebra_errAdd(ZebraHandle zh)
\brief returns additional info for last error
\param zh zebra session handle.
*/
-YAZ_EXPORT char *zebra_errAdd(ZebraHandle zh);
+YAZ_EXPORT
+char *zebra_errAdd(ZebraHandle zh);
/** \fn int zebra_result(ZebraHandle zh, int *code, char **addinfo)
\brief returns error code and additional info for last error
\param code pointer to returned error code
\param addinfo pointer to returned additional info
*/
-YAZ_EXPORT void zebra_result(ZebraHandle zh, int *code, char **addinfo);
+YAZ_EXPORT
+void zebra_result(ZebraHandle zh, int *code, char **addinfo);
/** \fn void zebra_clearError(ZebraHandle zh)
\brief clears last error.
\param zh zebra session handle.
*/
-YAZ_EXPORT void zebra_clearError(ZebraHandle zh);
+YAZ_EXPORT
+void zebra_clearError(ZebraHandle zh);
-/** \fn ZEBRA_RES zebra_search_PQF(ZebraHandle zh, const char *pqf_query,
- const char *setname, int *hits)
+/** \fn ZEBRA_RES zebra_search_PQF(ZebraHandle zh, const char *pqf_query, \
+ const char *setname, zint *hits)
\brief Search using PQF Query
\param zh session handle
\param pqf_query query
\param setname name of resultset
\param hits of hits is returned
*/
-YAZ_EXPORT ZEBRA_RES zebra_search_PQF(ZebraHandle zh, const char *pqf_query,
- const char *setname, zint *hits);
+YAZ_EXPORT
+ZEBRA_RES zebra_search_PQF(ZebraHandle zh, const char *pqf_query,
+ const char *setname, zint *hits);
-/** \fn ZEBRA_RES zebra_search_RPN(ZebraHandle zh, ODR o, Z_RPNQuery *query,
- const char *setname, zint *hits)
+/** \fn ZEBRA_RES zebra_search_RPN(ZebraHandle zh, ODR o, Z_RPNQuery *query, \
+ const char *setname, zint *hits)
\brief Search using RPN Query
\param zh session handle
\param o ODR handle
\param setname name of resultset
\param hits number of hits is returned
*/
-YAZ_EXPORT ZEBRA_RES zebra_search_RPN(ZebraHandle zh, ODR o, Z_RPNQuery *query,
- const char *setname, zint *hits);
+YAZ_EXPORT
+ZEBRA_RES zebra_search_RPN(ZebraHandle zh, ODR o, Z_RPNQuery *query,
+ const char *setname, zint *hits);
/**
- \fn ZEBRA_RES zebra_records_retrieve(ZebraHandle zh, ODR stream,
- const char *setname, Z_RecordComposition *comp, oid_value input_format,
- int num_recs, ZebraRetrievalRecord *recs)
+ \fn ZEBRA_RES zebra_records_retrieve(ZebraHandle zh, ODR stream, \
+ const char *setname, Z_RecordComposition *comp, \
+ oid_value input_format, int num_recs, \
+ ZebraRetrievalRecord *recs)
\brief retrieve records from result set (after search)
\param zh session handle
\param stream allocate records returned using this ODR
int num_recs,
ZebraRetrievalRecord *recs);
/**
- \fn int zebra_deleteResultSet(ZebraHandle zh, int function,
- int num_setnames, char **setnames, int *statuses)
+ \fn int zebra_deleteResultSet(ZebraHandle zh, int function, \
+ int num_setnames, char **setnames, int *statuses)
\brief delete one or more resultsets
\param zh session handle
\param function Z_DeleteResultSetRequest_{list,all}
int *statuses);
/**
- \fn ZEBRA_RES zebra_scan(ZebraHandle zh, ODR stream,
- Z_AttributesPlusTerm *zapt, oid_value attributeset,
- int *position, int *num_entries, ZebraScanEntry **list, int *is_partial)
+ \fn ZEBRA_RES zebra_scan(ZebraHandle zh, ODR stream, \
+ Z_AttributesPlusTerm *zapt, oid_value attributeset, \
+ int *position, int *num_entries, ZebraScanEntry **list, \
+ int *is_partial)
\brief performs Scan (Z39.50 style)
\param zh session handle
\param stream ODR handle for result
int *is_partial);
/**
- \fn ZEBRA_RES zebra_scan_PQF(ZebraHandle zh, ODR stream,
- const char *query, int *position, int *num_entries, ZebraScanEntry **list, int *is_partial)
+ \fn ZEBRA_RES zebra_scan_PQF(ZebraHandle zh, ODR stream, \
+ const char *query, int *position, int *num_entries, \
+ ZebraScanEntry **list, int *is_partial)
\brief performs Scan (taking PQF string)
\param zh session handle
\param stream ODR handle for result
\param list list of resulting terms (ODR allocated)
\param is_partial upon return 1=partial, 0=complete
*/
-YAZ_EXPORT ZEBRA_RES zebra_scan_PQF(ZebraHandle zh, ODR stream,
- const char *query,
- int *position, int *num_entries,
- ZebraScanEntry **entries,
- int *is_partial);
+YAZ_EXPORT
+ZEBRA_RES zebra_scan_PQF(ZebraHandle zh, ODR stream, const char *query,
+ int *position, int *num_entries, ZebraScanEntry **entries,
+ int *is_partial);
/**
\fn ZEBRA_RES zebra_auth(ZebraHandle zh, const char *user, const char *pass)
\brief authenticate user. Returns 0 if OK, != 0 on failure
\param user user name
\param pass password
*/
-YAZ_EXPORT ZEBRA_RES zebra_auth(ZebraHandle zh,
- const char *user, const char *pass);
+YAZ_EXPORT
+ZEBRA_RES zebra_auth(ZebraHandle zh, const char *user, const char *pass);
/**
- \fn int zebra_string_norm(ZebraHandle zh, unsigned reg_id,
- const char *input_str, int input_len,
- char *output_str, int output_len)
+ \fn int zebra_string_norm(ZebraHandle zh, unsigned reg_id, \
+ const char *input_str, int input_len, \
+ char *output_str, int output_len)
\brief normalize zebra term for register (subject to change!)
\param zh session handle
\param reg_id register ID, 'w', 'p',..
\param output_str output string buffer
\param output_len output string length
*/
-YAZ_EXPORT int zebra_string_norm(ZebraHandle zh, unsigned reg_id,
- const char *input_str, int input_len,
- char *output_str, int output_len);
+YAZ_EXPORT
+int zebra_string_norm(ZebraHandle zh, unsigned reg_id, const char *input_str,
+ int input_len, char *output_str, int output_len);
/**
\fn ZEBRA_RES zebra_create_database(ZebraHandle zh, const char *db)
\param zh session handle
\param db database to be created
*/
-YAZ_EXPORT ZEBRA_RES zebra_create_database(ZebraHandle zh, const char *db);
+YAZ_EXPORT
+ZEBRA_RES zebra_create_database(ZebraHandle zh, const char *db);
/**
\fn int zebra_drop_database(ZebraHandle zh, const char *db)
YAZ_EXPORT
struct BFiles_struct *zebra_get_bfs(ZebraHandle zh);
+
+YAZ_EXPORT
+ZEBRA_RES zebra_set_limit(ZebraHandle zh, int exclude_flag, zint *ids);
+
YAZ_END_CDECL
+
+/** \mainpage Zebra
+ *
+ * \section intro_sec Introduction
+ *
+ * Zebra is a search engine for structure data, such as XML, MARC
+ * and others. The following chapters briefly describe each of
+ * Zebra major modules/components.
+ *
+ * \section util Base Utilities
+ *
+ * The Zebra utilities (util.h) defines fundamental types and a few
+ * utilites for Zebra.
+ *
+ * \section res Resources
+ *
+ * The resources system (res.h) is a manager of configuration
+ * resources. The resources can be viewed as a simple database.
+ * Resources can be read from a configurtion file, they can be
+ * read or written by an application. Resources can also be written,
+ * but that facility is not currently in use.
+ *
+ * \section bfile Bfiles
+ *
+ * The Bfiles (bfile.h) provides a portable interface to the
+ * local file system. It also provides a facility for safe updates
+ * (shadow updates). All file system access is handle by this module
+ * (except for trival reads of configuration files).
+ *
+ * \section dict Dictionary
+ *
+ * The Zebra dictionary (dict.h) maps a search term (key) to a value. The
+ * value is a reference to the list of records identifers in which
+ * the term occurs. Zebra uses an ISAM data structure for the list
+ * of term occurrences. The Dictionary uses \ref bfile.
+ *
+ * \section isam ISAM
+ *
+ * Zebra maintains an ISAM for each term where each ISAM is a list
+ * of record identifiers corresponding to the records in which the
+ * term occur. Unlike traditional ISAM systems, the Zebra ISAM
+ * is compressed. The ISAM system uses \ref bfile.
+ *
+ * Zebra has more than one ISAM system. The old and stable ISAM system
+ * is named isamc (see isamc.h). Another version isams is a write-once
+ * isam system that is quite compact - suitable for CD-ROMs (isams.h).
+ * The newest ISAM system, isamb, is implemented as a B-Tree (see isamb.h).
+ *
+ * \section data1 Data-1
+ *
+ * The data1 (data1.h) module deals with structured documents. The module can
+ * can read, modify and write documents. The document structure was
+ * originally based on GRS-1 - a Z39.50 v3 structure that predates
+ * DOM. These days the data1 structure may describe XML/SGML as well.
+ * The data1, like DOM, is a tree structure. Each node in the tree
+ * can be of type element, text (cdata), preprocessing instruction,
+ * comment. Element nodes can point to attribute nodes.
+ *
+ * \section recctrl Record Control
+ *
+ * The record control module (recctrl.h) is responsible for
+ * managing the various record types ("classes" or filters).
+ *
+ * \section rset Result-Set
+ *
+ * The Result-Set module (rset.h) defines an interface that all
+ * Zebra Search Results must implement. Each operation (AND, OR, ..)
+ * correspond to an implementation of that interface.
+ *
+ * \section dfa DFA
+ *
+ * DFA (dfa.h) Deterministic Finite Automa is a regular expression engine.
+ * The module compiles a regular expression to a DFA. The DFA can then
+ * be used in various application to perform fast match against the
+ * origianl expression. The \ref Dict uses DFA to perform lookup
+ * using regular expressions.
+ */
+
#endif