Name

cf-zserver — Z39.50/SRU based connector

Synopsis

cf-zserver [GFS-options]

DESCRIPTION

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:

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
      

Init

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.

Search

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.

Note

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.

1016 1035

keyword

30 31

startyear / endyear / year

1 1003

author

4 5 6

title

Present

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.

DATABASE PARAMETERS

The Z39.50 database is URL encoded and is the format cfdatabase,parm1=value1&parm2=value2&.... The following parameters are defined for cf-zserver:

user

Passed to a Connector's Init method as argument "username".

group

Passed to a Connector's Init method as argument "group".

password

Passed to a Connector's Init method as argument "password".

proxy

Specifies a HTTP Proxy for the connector.

The proxy is of the form host:port.

Note

CF version 2.7.8 and earlier used a notation with prefix http: and auto:. This is no longer supported.

subdatabase

Filters a search with a sub database. The database is passed as JSON value database with value of the sub database.

EXAMPLE

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`
   

SRU

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).

SEE ALSO

yaz-ztest(7)