cf-zserver — Z39.50 based connector
This manual documents the Z39.50 server functionality of the CF Metaproxy module.
Z39.50 functionality is enabled by using
<z39.50 enable="true"/>
in the configuration. Refer to the cf_webservice(8)
manual page for more information about configuration.
If Z39.50 is disabled, Z39.50 packages are ignored and passed though (to next module in chain).
Each Z39.50 Protocol Data Unit (operation) is handled as follows:
Connectors built with CF 2.8.0 may support a new feature, fullquery, which allows more advanced queries to be passed to a connector.
Operators AND, OR, NOT and proximity may be supported by a fullquery connector. For proximity the following limitations exist: exclusion must be false (0), any distance, any order, relation must be less-than-or-equal (2) unit code must be known (k) unit type must be word (2)
In PQF that's queries of the form
@prox 0 dist ord 2 k 2
When the server receives a Z39.50 Initialize Request the authentication parameters for the session are "saved".
If the environment variable CF_REPO_AUTH_URL
is defined, the username and password are passed to the
URL given. Only if the HTTP Response is OK (200), the
Z39.50 session is allowed.
If no authentication parameters are supplied in the Z39.50 Initialize
Request, the cf-zserver will inspect the variables
CF_REPO_ANON_USER and CF_REPO_ANON_PASSWORD
and use these as username and password respectively. If these
variables are unset, no HTTP authentication will be performed.
Note that in first versions of the cf-zserver, the Browser (CF_Engine) would already be instantiated during Init. This is no longer the case. It now happens when a search request is received.
When the server receives a Z39.50 Search Request, a number of operations takes place.
If the current database given is the same as previous search the browser session is kept alive and the CF_Engine is re-used.
If the browser session terminates or if a previous search terminates, the exit task is executed. The exit task is optional and is only invoked for CF version 2.7.13 and later.
The Z39.50 database is URL decoded and split into a cfdatabase component plus arguments. These arguments serves as local authentication parameters or other configuration for a specific connector. Refer to section 'DATABASE PARAMETERS'.
Otherwise, (database is different or this is first search), the CF_Engine is instantiated. The connector file must be retrieved.
If CF_CONNECTOR_PATH or CF_BASE_PATH
that gives a way for the cf-zserver to read a CF File locally.
The directory from these environment variables followed by slash,
followed by database, followed by .cf is the
resulting local file.
Otherwise (neither CF_CONNECTOR_PATH nor CF_BASE_PATH is defined),
the engine will try to fetch the CF file remotely via HTTP GET
provided that environment variable CF_REPO_FETCH_URL
is defined. If the HTTP fetch is successful, the tempoary
connector file is stored in /tmp/cfengine/user
where user the username given in Z39.50 init.
The connector file is finally read locally using
load_cf method for the CF_Engine.
method.
If the load_cf method was successful the
init task is executed with
authentication parameters from the Z39.50 database parameters.
Previous versions of cf-zserver passed Z39.50 Init auth parameters to the connector's init task. This is no longer the case. Only database parameters are passed to it.
If the init task was executed successfully, the server is now ready to actually prepare the search task. The search task takes the query converted from RPN/Type-1 and possibly a sub-database which the suffix following the slash for the Z39.50 database.
RPN/Type-1 Queries are supported by cf-zserver and CQL (which may be converted by the GFS system to RPN transparently).
The RPN Operator 'and' is supported. The other RPN operators 'or', 'and-not', 'prox' are unsupported.
The RPN Operand type 'AttributesPlusTerm' is supported. The other RPN Operands types 'ResultSetId' and 'ResultSetPlusAttributes' are unsupported.
The AttributesPlusTerm's Term of type 'general' and 'characterString' is supported. The other types, 'numeric', 'oid', 'dateTime', 'external', 'integerAndUnit', 'null' are unsupported.
Only the Bib-1 attribute set is supported. Use attributes may be either numeric or string based. For string based use attributes, the string is taken verbatim as the field name in the conversion to the search Task. A few numeric use attributes are supported.
keyword
startyear / endyear / year
author
title
Z39.50 Present Requests will result in one or more invocations of the parse task. To the extend that a page needs loading, the next task is invoked as well.
Z39.50 Search Requests with piggyback results may also invoke parse and next tasks.
SRU Explain and SRU SearchRetrieve Request are supported by the server. The SRU SearchRetrieve Request is equivalent to a search followed by zero or more present requests (Z39.50). Whether SRU or Z39.50 is in use, is transparent to the CF Engine itself.
The Z39.50 database is URL encoded and is the format
cfdatabase,parm1=value1&parm2=value2&....
The following parameters are defined for cf-zserver:
Passed to a Connector's Init method as argument
"username".
Passed to a Connector's Init method as argument
"group".
Passed to a Connector's Init method as argument
"password".
Specifies a HTTP Proxy for the connector.
The proxy is of the form host:port.
CF version 2.7.8 and earlier used a notation with prefix
http: and auto:. This
is no longer supported.
Filters a search with a sub database. The database is passed
as JSON value database with value of the
sub database.
A complete, yet small, full Metaproxy configuration may look as follows:
<metaproxy xmlns="http://indexdata.com/metaproxy" version="1.0">
<dlpath>.</dlpath>
<start route="start"/>
<routes>
<route id="start">
<filter type="frontend_net">
<port>localhost:9000</port>
</filter>
<filter type="cf">
<z39.50 enable="true"/>
</filter>
</route>
</routes>
</metaproxy>