ZServer Design Notes

Table of Contents

• Layered organization
• Static calling structure
• Notes on error handling and trace/error logging
• Use of standard input/output/error files
• Memory management

ZServer's Organization (layers, directories, source files)

The ZServer accepts requests for information retrieval (IR) services encoded according to the Z39.50 protocol (and Basic Encoding Rules - BER). It decodes these requests and passes them on to an IR application for execution, encodes the IR application's response, and returns it to the client which made the request.

The ZServer is designed in 4 layers described in more detail below:

• Main-ZServer
• Z39.50 services
• Application services
• IR application

The ZServer design is based on the assumption that a new instantiation of the server will be started for each client by the inet demon when contacted by a client at the agreed-upon port.

Main-ZServer

• Source: DISTRIBUTION_ROOT/zprise_2/zserver/src/bin/zserver

Main function knows nothing about Z39.50 or any IR application. It invokes ZServer functions:

• init_zserver(): reads table of databases and set default pdus;
• zserver(): loops on incoming msgs from the client (via socket) until terminate
• close_zserver(): release resources

Source files:

• main.c
• Source: DISTRIBUTION_ROOT/zprise_2/zserver/src/lib/zserver

IR application-independent server code which:

• initializes database table and defaults
• loops
• reads incoming msg in BER-format from socket
• translates incoming msg to incoming PDU
• invokes zservices level (process_PDU())
• translates outgoing PDU to BER-format msg
• writes outgoing msg to socket
• releases resources when server closes down

Source files:

• zserver.c

Z39.50 services

• Source: DISTRIBUTION_ROOT/zprise_2/zserver/src/lib/zservices

  IR application-independent code to process PDUs and invoke the application-specific functions (e.g. those in /zprise) that in turn invoke the IR application functions proper.

  Based on the PDU choice id, process_PDU() invokes the routines (init, process, close) defined for the operation in op_table.c

  Source files:

  • databases.c
  • default_pdus.c
  • zservices.c - #includes the following:
    • access.c
    • close.c - implemented
    • delete.c
    • extended.c
    • init.c - implemented
    • present.c - implemented
    • search.c - implemented
    • scan.c
    • segment.c
    • sort.c
    • resource.c
    • op_table.c
      Table of pointers to Z3950 operation functions (e.g., init_search, search,...) indexed by PDU id.

Application services (for PRISE)

• Source: DISTRIBUTION_ROOT/zprise_2/zserver/src/lib/zprise

This layer bridges any gap between the layer (zservices) above it, which knows about the Z39.50 protocol, and the particular IR application layer below it (e.g. PRISE). This is the layer that may require adjustment when a new IR application is inserted.

Source files

• ap_services.c - #includes the following:
  • ap_closedb.c - implemented for PRISE
  • ap_initdb.c - implemented for PRISE
  • ap_zqtran.c - implemented for PRISE
  • ap_search.c - implemented for PRISE
  • ap_present.c - implemented for PRISE
  • ap_help.c - Z39.50 extension - implemented for PRISE
  • ap_generic.c - Z39.50 extension
  • ap_feedback.c - Z39.50 extension

IR application

Source: DISTRIBUTION_ROOT/zprise_2/prise-search

This is the IR application proper.

See "Adding/substituting your own search engine" for more detailed information on how the ZServer interfaces to an IR application.

ZServer's Static Calling Structure

main() invokes:

1. init_zserver()
2. zserver() - Loop awaiting/processing incoming msgs

   sets timeout interval (60 mins)

   process_msg() handles single message from socket

   • ber2pdu() - Translate BER-encoded msg into PDU
   • process_PDU() - Take a request PDU; return a response PDU
     1. ap_table_entry.init - Initialization by operation
        • init_search()
        • init_present()
     2. ap_table_entry.proc - Main processing by operation
        • init()
          • init_default_pdus()
          • get_db_list()
        • search()
          • MakeSearchResponse()
          • ap_link() - Find ap_service_entry for IR app. given db. name
          • ap_service_entry.closedb - Release database
          • ap_service_entry.initdb - Init. database
          • ap_service_entry.delete - Release result set resources
          • Perform search (or search extension NL...)
            • ap_service_entry.help - Perform NLhelp
            • ap_service_entry.feedback - Perform NLfeedback
            • ap_service_entry.generic - Perform NLgeneric
            • ap_service_entry.search - Perform search
          • get_elementSetType() - Get some format info
          • loop
            • ap_service_entry.present - Get a database record and turn it into a retrieval recd.
            • InsertResponseRecord() - Add retrieval record or surrogate to response
          • ap_service_entry.close_search
        • present()
          • MakePresentResponse()
          • ap_service_entry.init_present
          • get_elementSetType()
          • loop
            • ap_service_entry.present - Get a database record and turn it into a retrieval recd.
            • InsertResponseRecord() - Add retrieval record or surrogate to response
          • ap_service_entry.close_present
        • close()
     3. ap_table_entry.close - Close processing by operation
        • close_search()
        • close_present()
   • pdu2ber() - Translate out-going PDU to BER-encoded msg.
   • FreePDU()s
3. close_zserver()
   • free_dbs()

Notes on Error Handling and Trace/Error Logging

In general the ZServer has been written to be tolerant of invalid requests. So, for example, the ZServer looks for an element set name of F or B but finding G instead or none, it uses its default. If the result set contains 3 records and the client asks for 4 starting with the third, the ZServer just returns as many as it can (1).

When the ZServer comes up it opens a file named according to it's PID

     zserver.RELEVANT-PID.log

When ZServer encounters a processing error. It attempts to communicate the situation to the client via the PDU and stay up. However, in the following circumstances the ZServer will log a message and exit:

- Errors encountered before the msg-read/write loop in process_msg() is entered

- Errors encountered down in the PRISE search engine (still working on this)

- Memory allocation errors

ZServer`s Use of Standard Input/Output/Error Files

• Standard input (0) - reserved for use by the socket
• Standard out (1) - closed by the ZServer
• Standard error (2) is closed and is then redirected to the error log file (err_fp) opened by the ZServer.

Memory Management

The ZServer manages memory directly via calls to the C library routines malloc, calloc, and free as well as indirectly for the encoding and decoding of the Z39.50 protocol data (PDUs) via routines generated by the SNACC ASN.1 compiler. A SNACC routine allocates an initial memory buffer (so-called "nibble memory") when the ZServer begins execution. Later, the PDU decoding and encoding code calls other SNACC routines to parcel out pieces of the nibble memory buffer. If the request for a piece can't be filled in the current buffer, a new one is allocated and added to the buffer chain.

The ZServer contains calls to SNACC-generated Free... routines to free the pieces of nibble memory it uses, but these routines do not currently do anything. They are there to support the option of changing from the use of nibble memory management to direct calls to C library routines. The ZServer frees nibble memory by reseting the memory buffer chain each time it sends a PDU back to the the client. When the chain is reset, all the nibble memory buffers except the first are freed. The first buffer contains default PDU information which we preserve for the life of the ZServer. See ..../zserver/src/lib/zserver/zserver.c for the calls to the nibble memory intialization and reset routines.