This tutorial explains, through the use of an example client-server system, how to write a value-added server (VAS) and client programs using the Shore Storage Manager (SSM) programming interface.
This tutorial illustrates many aspects of writing a VAS, including
This type of information is in An Overview of Shore and The Shore Storage Manager Programming Interface. See The Shore Release for an index to the rest of the documentation.
It is assumed the reader is already familiar with RPC programming. If not we recommend the book Power Programming with RPC, by John Bloomer, published by O'Reilly & Associates, Inc.
The example used throughout this tutorial is a client-server system, called grid, that illustrates many aspects of building a value-added server and a corresponding client.
The grid example is a simple client-server database system for items located on a 2-dimensional grid. Items have a string name and coordinates on the grid. Multiple items can reside at any location, but each item has a unique name.
The server uses the SSM to manage the grid database. The server implements a number of update and query commands. Update commands on the grid include adding items, removing items and clearing the grid (removing all items). Query commands on the grid including printing the entire grid, looking up items by name, and locating all items within a rectangular region of the grid. There are also commands for committing and aborting transactions. The server accepts commands from standard input and processes remote procedure calls (RPCs) from multiple clients.
The client accepts commands from standard input and sends them to the server, via remote procedure calls (RPCs) for processing.
The grid data file and indexes are stored on a single volume as follows. Each item is stored in a record (containing item name and location) in an SSM file. A B+-tree index maps item names to the IDs of the corresponding item records. This index is used to lookup items by name. An R*-tree index maps location coordinates to item records. This index is used to locate all items within a rectangular region of the grid.
The grid server is a multi-threaded threaded program that manages connections from multiple clients and also monitors the terminal (standard input) for commands. The server starts a separate thread for each of these tasks to demonstrate how to use SSM's thread package. Shared state among the threads is protected using the synchronization mechanisms provided by the thread package.
The client and server use the SSM's configuration options package to read configuration information from configuration files and the program command line arguments.
This example does not demonstrate all of the features of the SSM. In particular:
Most of the unused features are used in the Shore VAS (see src/vas) and the Paradise database system (see http://www.cs.wisc.edu/paradise/). Almost every feature is also tested by the SSM testing program, ssh, located in src/sm/ssh.
This tutorial walks through the example program sources in detail. The sources, as well as associated test programs and data, may be found in the src/examples/vas/grid sub-directory of the distribution.
Throughout this tutorial, we will assume (as does the Shore Software Installation Manual) that the environment variable $SHROOT contains the absolute path name of the root directory of the installed Shore software.
The rest of this tutorial is organized as follows. First, there are two sections discussing storage structures and operations on them. Next are sections explaining how to implement servers and clients. Finally there are sections describing how to compile and run the example.