Z39.50 Initialization

During initialization, the server will negotiate to version 3 of the Z39.50 protocol, and the option bits for Search, Present, Scan, NamedResultSets, and concurrentOperations will be set, if requested by the client. The maximum PDU size is negotiated down to a maximum of 1 MB by default.

Z39.50 Search

The supported query type are 1 and 101. All operators are currently supported with the restriction that only proximity units of type "word" are supported for the proximity operator. Queries can be arbitrarily complex. Named result sets are supported, and result sets can be used as operands without limitations. Searches may span multiple databases.

The server has full support for piggy-backed retrieval (see also the following section).

Z39.50 Present

The present facility is supported in a standard fashion. The requested record syntax is matched against the ones supported by the profile of each record retrieved. If no record syntax is given, SUTRS is the default. The requested element set name, again, is matched against any provided by the relevant record profiles.

Z39.50 Scan

The attribute combinations provided with the termListAndStartPoint are processed in the same way as operands in a query (see above). Currently, only the term and the globalOccurrences are returned with the termInfo structure.

Z39.50 Sort

Z39.50 specifies three different types of sort criteria. Of these Zebra supports the attribute specification type in which case the use attribute specifies the "Sort register". Sort registers are created for those fields that are of type "sort" in the default.idx file. The corresponding character mapping file in default.idx specifies the ordinal of each character used in the actual sort.

Z39.50 allows the client to specify sorting on one or more input result sets and one output result set. Zebra supports sorting on one result set only which may or may not be the same as the output result set.

Z39.50 Close

If a Close PDU is received, the server will respond with a Close PDU with reason=FINISHED, no matter which protocol version was negotiated during initialization. If the protocol version is 3 or more, the server will generate a Close PDU under certain circumstances, including a session timeout (60 minutes by default), and certain kinds of protocol errors. Once a Close PDU has been sent, the protocol association is considered broken, and the transport connection will be closed immediately upon receipt of further data, or following a short timeout.

Z39.50 Explain

Zebra maintains a "classic" Z39.50 Explain database on the side. This database is called IR-Explain-1 and can be searched using the attribute set exp-1.

The records in the explain database are of type grs.sgml. The root element for the Explain grs.sgml records is explain, thus explain.abs is used for indexing.

Running zebrasrv as an SRU Server

Because Zebra supports all protocols on one port, it would seem to follow that the SRU server is run in the same way as the Z39.50 server, as described above. This is true, but only in an uninterestingly vacuous way: a Zebra server run in this manner will indeed recognise and accept SRU requests; but since it doesn't know how to handle the CQL queries that these protocols use, all it can do is send failure responses.

     http://localhost:9999/Default?version=1.1
     &operation=searchRetrieve
     &x-pquery=mineral
     &startRecord=1
     &maximumRecords=1
    

In order to turn on Zebra's support for CQL queries, it's necessary to have the YAZ generic front-end (which Zebra uses) translate them into the Z39.50 Type-1 query format that is used internally. And to do this, the generic front-end's own configuration file must be used. See the section called “YAZ server virtual hosts”; the salient point for SRU support is that zebrasrv must be started with the -f frontendConfigFile option rather than the -c zebraConfigFile option, and that the front-end configuration file must include both a reference to the Zebra configuration file and the CQL-to-PQF translator configuration file.

A minimal front-end configuration file that does this would read as follows:

    
    <yazgfs>
    <server>
    <config>zebra.cfg</config>
    <cql2rpn>../../tab/pqf.properties</cql2rpn>
   </server>
   </yazgfs>
    

The <config> element contains the name of the Zebra configuration file that was previously specified by the -c command-line argument, and the <cql2rpn> element contains the name of the CQL properties file specifying how various CQL indexes, relations, etc. are translated into Type-1 queries.

A zebra server running with such a configuration can then be queried using proper, conformant SRU URLs with CQL queries:

    http://localhost:9999/Default?version=1.1
    &operation=searchRetrieve
    &query=title=utah and description=epicent*
    &startRecord=1
    &maximumRecords=1
   

SRU Search and Retrieval

Zebra supports the searchRetrieve operation.

One of the great strengths of SRU is that it mandates a standard query language, CQL, and that all conforming implementations can therefore be trusted to correctly interpret the same queries. It is with some shame, then, that we admit that Zebra also supports an additional query language, our own Prefix Query Format (PQF). A PQF query is submitted by using the extension parameter x-pquery, in which case the query parameter must be omitted, which makes the request not valid SRU. Please feel free to use this facility within your own applications; but be aware that it is not only non-standard SRU but not even syntactically valid, since it omits the mandatory query parameter.

SRU Scan

Zebra supports scan operation. Scanning using CQL syntax is the default, where the standard scanClause parameter is used.

In addition, a mutant form of SRU scan is supported, using the non-standard x-pScanClause parameter in place of the standard scanClause to scan on a PQF query clause.

SRU Explain

Zebra supports explain.

The ZeeRex record explaining a database may be requested either with a fully fledged SRU request (with operation=explain and version-number specified) or with a simple HTTP GET at the server's basename. The ZeeRex record returned in response is the one embedded in the YAZ Frontend Server configuration file that is described in the the section called “YAZ server virtual hosts”.

Unfortunately, the data found in the CQL-to-PQF text file must be added by hand-craft into the explain section of the YAZ Frontend Server configuration file to be able to provide a suitable explain record. Too bad, but this is all extreme new alpha stuff, and a lot of work has yet to be done ..

There is no linkage whatsoever between the Z39.50 explain model and the SRU explain response (well, at least not implemented in Zebra, that is ..). Zebra does not provide a means using Z39.50 to obtain the ZeeRex record.

Other SRU operations

In the Z39.50 protocol, Initialization, Present, Sort and Close are separate operations. In SRU, however, these operations do not exist.

It can be seen, then, that while Zebra operating as an SRU server does not provide the same set of operations as when operating as a Z39.50 server, it does provide equivalent functionality.