cf-zserver — Z39.50/SRU based connector
cf-zserver [GFS-options]
cf-zserver is a Z39.50/SRU server (target) with a Connector Framework back-end.
cf-zserver is based on YAZ' Generic Frontend Server (GFS) interface it supports exactly the same options. Refer to GFS Options for available options. The Z39.50 test server part of YAZ, yaz-ztest, supports the same options as well.
cf-zserver behaves like any other Z39.50 server. It invokes search-specific Connector Framework tasks.
Each Z39.50 Protocol Data Unit (operation) is handled as follows:
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, 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.
In most cases, when in production or when the user does not wish to display the output of the CF Engine running, the Xvfb program must be configured. This procedure usually goes as follows
echo localhost >hosts
Xvfb :1 -auth hosts
export DISPLAY=:1.0
The DISPLAY is now directs display to the
Xvfb instance and must be set when invoking
cf-zserver.
The following defines the three essential CF environment variables (bash notation), then starts cf-zserver on the any local address port 9100 and puts it in the background (-D), and writes PID file and appends to a log file.
export CF_CONNECTOR_PATH=/var/cf/connnectors
export CF_MODULE_PATH=/var/cf/builder/modules
export CF_APP_PATH=/var/cf/app
cd /var/cf/run
cf-zserver -D -l cf-zserver.log -p cf-zserver.pid @:9100
The server may be stopped again, with
kill `cat /var/cf/run/cf-zserver.pid`
cf-zserver, like the GFS, may also be accessed via SRU. For example:
http://localhost:9010/yahoo?operation=searchRetrieve (cont)
&x-pquery=water&version=1.2&maximumRecords=2
which will search for water in
connector yahoo. Up to two records are returned.
The value of x-pquery is a PQF string, so to search for "title=water",
one would use @attr 1=4 water for the value of x-pquery
-- which would be encoded as @attr+1%3D4+water.
Parameters x-username and x-password
may be passed and is equivalent to Z39.50 authentication (not to be confused
with authentication for the connector session itself).