ExtLite: Extended Services Lite for Z39.50

20th November 2003

1. Introduction
2. ExtLite Requests
3. ExtLite Responses
        3.1. Self-Test Response (Request 1)
        3.2. Logging-Level Response (Requests 2, 3 and 6)
        3.3. Additional Logging Response (Requests 4 and 5)

1. Introduction

ExtLite (Extended Services Lite) is a new, lightweight way to invoke various services on a Z39.50 server, somewhat in the manner of the Extended Services facility described in section 3.2.9 of the Z39.50 standard.

ExtLite requests are submitted as searches using attributes from the ExtLite attribute set, described below. Servers should respond to ExtLite requests by returning a single record, in XML, conforming to the ExtLite DTD, also described below.

2. ExtLite Requests

The OID of the ExtLite attribute set is 1.2.840.10003.3.1000.81.3.

The following attribute types are defined within this attribute set:

Type Meaning
1 The specific service to request.
All others Additional information about the service requested by the type 1 attribute, defined differently for each such service as required.

The following services are defined by attributes of type 1:

Value Meaning
1 Test a module of the server. The particular module to test is named in the search-term associated with the attribute. For example, a query with an attribute of type 1, value 1 and term ``unicode'' would request that the server tests its Unicode module.
2 Increase the server's logging level by a single step. The associated search-term contains a password necessary to authenticate the request.
3 Decrease the server's logging level by a single step. The associated search-term contains a password necessary to authenticate the request.
4 Turn on ``additional server-side logging''. The associated search-term contains a password necessary to authenticate the request. The precise nature of the additional logging is server-defined and may cover anything not appropriate to be included in the ``logging levels'' manipulated by ExtLite requests 2 and 3. For example, a server that works by querying a relational database might dump a copy of all SELECTed records to a well-known file after each search.
5 Turn off ``additional server-side logging''. The associated search-term contains a password necessary to authenticate the request.
6 Set the server's logging level to a specific integer value in a single operation. The associated search-term contains the desired logging level followed by a space and then by password necessary to authenticate the request.

There are more requests to come, no doubt.

3. ExtLite Responses

Servers should respond to ExtLite reqeusts with a single XML record corresponding to the ExtLite DTD. The following versions of the DTD exist:

3.1. Self-Test Response (Request 1)

The <extLite> document element contains a <report> element, which in turn contains a <status> sub-element and optionally also a <comment> sub-element. The former contains a single integer indicating the result of the test, and the latter may contain additional human-readable information. The <status> integer must take one of the following values:

For example, the following response record describes a test that succeeded, but not perfectly:

<?xml version="1.0"?>
<!-- $Id: sample-report.xml,v 1.2 2003/11/19 16:56:09 mike Exp $ -->
<!DOCTYPE extLite SYSTEM "http://z3950.org/extlite/extlite-1.0.dtd">
<extLite>
  <report>
    <status>4</status>
    <comment>search OK but found 316 hits (expected 309)</comment>
  </report>
</extLite>

[download]

3.2. Logging-Level Response (Requests 2, 3 and 6)

The response uses the same <report> element as the self-test response. Its <status> sub-element contains the new logging level if it was successfully incremented, decremented or set, or -1 if the request was declined due to an unrecognised password.

3.3. Additional Logging Response (Requests 4 and 5)

The response uses the same <report> element as the self-test response. Its <status> sub-element contains a boolean indicating the new state of whether or not the server is performing ``additional logging'', or -1 if the request was declined due to an unrecognised password.

Feedback to <mike@indexdata.com> is welcome!

Valid HTML 4.0! Valid CSS!