-<!-- $Id: frontend.xml,v 1.14 2002-09-16 14:16:31 adam Exp $ -->
+<!-- $Id: frontend.xml,v 1.17 2003-04-28 21:02:16 adam Exp $ -->
<chapter id="server"><title>Generic server</title>
<sect1><title>Introduction</title>
<para>
If you have a database system that you would like to make available by
- means of Z39.50, &yaz; basically offers your two options. You
+ means of Z39.50 or SRW, &yaz; basically offers your two options. You
can use the APIs provided by the &asn;, &odr;, and &comstack;
modules to
create and decode PDUs, and exchange them with a client.
too many structural changes in existing applications.
</para>
</note>
+
+ <note>
+ <para>
+ The &yaz; server does not support XCQL.
+ </para>
+ </note>
</sect1>
<sect1 id="server.frontend"><title>The Database Frontend</title>
<function>bend_init</function> handler is passed in the call to
<function>statserv_start</function>.
</para>
+
+ <para>
+ This handler is also called when operating in SRW/SRU mode - when
+ a connection has been made (even though SRW/SRU does not offer
+ this service).
+ </para>
+
<para>
Unlike previous versions of YAZ, the <function>bend_init</function> also
serves as a handler that defines the Z39.50 services that the backend
int (*bend_delete)(void *handle, bend_delete_rr *rr);
int (*bend_scan)(void *handle, bend_scan_rr *rr);
int (*bend_segment)(void *handle, bend_segment_rr *rr);
+
+ ODR decode; /* decoding stream */
+ /* character set and language negotiation - see include/yaz/z-charneg.h */
+ Z_CharSetandLanguageNegotiation *charneg_request;
+ Z_External *charneg_response;
} bend_initrequest;
typedef struct bend_initresult
int errcode; /* 0==OK */
char *errstring; /* system error string or NULL */
} bend_search_rr;
-
</synopsis>
<para>
The <function>bend_search</function> handler is a fairly close
- approximation of a protocol Search Request - and Response PDUs
+ approximation of a protocol Z39.50 Search Request - and Response PDUs
The <literal>setname</literal> is the resultSetName from the protocol.
You are required to establish a mapping between the set name and whatever
your backend database likes to use.
defined error codes, and the suggested uses of the addinfo field.
</para>
+ <para>
+ The <function>bend_search</function> handler is also called when
+ the frontend server receives a SRW/SRU SearchRetrieveRequest.
+ For SRW/SRU, a CQL query is usually provided by the client.
+ The CQL query is available as part of <literal>Z_Query</literal>
+ structure (note that CQL is now part of Z39.50 via an external).
+ To support CQL in existing implementations that only do Type-1,
+ we refer to the CQL-to-PQF tool described
+ <link linkend="tools.cql.pqf">here</link>.
+ </para>
+ <para>
+ To maintain backwards compatibility, the frontend server
+ of yaz always assume that error codes are BIB-1 diagnostics.
+ For SRW/SRU operation, a Bib-1 diagnostic code is mapped to
+ SRW/SRU diagnostic.
+ </para>
+
<synopsis>
int (*bend_fetch) (void *handle, bend_fetch_rr *rr);
int errcode; /* 0==success */
char *errstring; /* system error string or NULL */
int surrogate_flag; /* surrogate diagnostic */
+ char *schema; /* string record schema input/output */
} bend_fetch_rr;
</synopsis>
<para>
The frontend server calls the <function>bend_fetch</function> handler
- when it needs database records to fulfill a Search Request or a Present
- Request.
+ when it needs database records to fulfill a Z39.50 Search Request, a
+ Z39.50 Present Request or a SRW SearchRetrieveRequest.
The <literal>setname</literal> is simply the name of the result set
that holds the reference to the desired record.
The <literal>number</literal> is the offset into the set (with 1
</para>
<para>
+ If a SRW/SRU SearchRetrieveRequest is received by the frontend server,
+ the <literal>referenceId</literal> is NULL and the
+ <literal>request_format</literal> (transfer syntax) is XML (OID name
+ <literal>VAL_TEXT_XML</literal>).
+ The schema for SRW/SRU is stored in both the
+ <literal>Z_RecordComposition</literal>
+ structure and <literal>schema</literal> (simple string).
+ </para>
+
+ <para>
In the structure, the <literal>basename</literal> is the name of the
database that holds the
record. <literal>len</literal> is the length of the record returned, in
bytes, and <literal>record</literal> is a pointer to the record.
- <literal>Last_in_set</literal> should be nonzero only if the record
+ <literal>last_in_set</literal> should be nonzero only if the record
returned is the last one in the given result set.
<literal>errcode</literal> and <literal>errstring</literal>, if
given, will be interpreted as a global error pertaining to the
<para>
The <function>bend_present</function> handler is called when
- the server receives a Present Request. The <literal>setname</literal>,
+ the server receives a Z39.50 Present Request.
+ The <literal>setname</literal>,
<literal>start</literal> and <literal>number</literal> is the
name of the result set - start position - and number of records to
be retrieved respectively. <literal>format</literal> and
<sbr/>
<arg choice="opt"><option>-k <replaceable>kilobytes</replaceable></option></arg>
<arg choice="opt"><option>-d <replaceable>daemon</replaceable></option></arg>
- <arg choice="opt"><option>-ziST1</option></arg>
<arg choice="opt"><option>-w <replaceable>dir</replaceable></option></arg>
+ <arg choice="opt"><option>-ziST1</option></arg>
<arg choice="opt" rep="repeat">listener-spec</arg>
</cmdsynopsis>
<para>
For UNIX, the address is the filename of socket.
</para>
-
+
<para>
- Examples
+ For TCP/IP and SSL, the special hostname "@" is mapped to
+ the address <literal>INADDR_ANY</literal>, which causes the
+ server to listen on any local interface.
</para>
-
+
+ <para>
+ Examples:
<screen>
- tcp:dranet.dra.com
+ tcp:@:210
- ssl:ssl.enterprise.com:3000
+ ssl:@:3000
unix:/tmp/yaz
</screen>
-
- <para>
- For TCP/IP and SSL, the special hostname "@" is mapped to
- the address <literal>INADDR_ANY</literal>, which causes the
- server to listen on any local interface.
</para>
</sect1>
projects / yaz-moved-to-github.git / blobdiff