An Overview of the Shore Online Documentation, Version 1.1
The Shore distribution comes with a collection of documentation, including
design documents, tutorials, reference manuals, and manual pages.
Although there is a large amount of information available, it can sometimes
be hard to find. This document provides a set of entry points for navigating
the online information. All of the documents here are also available in
printed form.
This document gives a brief overview of the contents of the Shore distribution
package. It specifies the hardware and software requirements for installing and
running Shore, lists the major packages distributed (including another overview
of the major documents), and points to information to tell you how to retrieve
the software, install it, start it running, write your own applications,
and even extend the Shore server.
This document describes in detail how to install Shore.
Shore is distributed in three forms:
a documentation release, a binary release, and a source
release.
The Installation Manual explains how to install the documentation and the
binary version of Shore, and how to build a new copy of Shore from the source
release.
This document describes how to submit a problem report if you find a problem
with the Shore software or documentation.
Please take a moment to read it before reporting bugs or asking for help
in getting parts of Shore to work. Someday, this document should be extended
into a FAQ.
This is a version of a paper originally presented at the SIGMOD conference
on the management of data.
It describes the goals of the Shore project and a high-level overview of its
internal structure.
We have attempted to use technical terms in a consisten manner through out
these documents (and in the source code).
The Glossary is a concise lexicon of these terms.
When in doubt, please consult this list.
The installation manual
tells you how to run the Shore server with its default configuration and
options. This manual explains the configuration and startup process in
more detail, including advice on using raw disk devices to hold the
database rather than using Unix files.
It also explains how to use the feature that allows a Shore database to
be accessed as a file system by ``legacy applications'' through the
NFS interface.
This tutorial shows how to write Shore application programs by describing
the persistent data structures in a C++-like data-definition language
called the Shore Data Language (SDL) and manipulating them with C++
programs.
This reference manual describes SDL in considerably greater detail.
The DirScan class provides a convenient interface for scanning
directories. This document describes how to use the DirScan class. The
Shore release includes a simple example program called shls (``Shore
ls''), that illustrates the use of the DirScan class. Shls can be
found in the examples/shls directory of the Shore release.
The PoolScan class provides a convenient interface for scanning
through the objects in a pool. This document describes how to use
PoolScans, as well as known bugs and limitations of the PoolScan class.
The Shore release includes three example programs that illustrate pool
scans. The examples can be found in the examples/pscan directory of
the Shore release.
This document describes error handling facilities for Shore applications.
Shore application writers are encouraged to read
Getting Started with Shore
and look at the example applications before reading
this document. The SDL manual
and the example programs show the standard
ways of handling errors in Shore. This document is intended for
application writers interested in more details.
This document is a guided tour through the numerous directories of the
Shore releases.
It briefly describes the purpose of each directory and how the code in it
interacts with the rest of the system.
The Shore Storage Manager (SSM)
is a package of libraries
for building object repository servers and their clients.
The core library in the package,
libsm.a, is a multi-threaded system managing persistent
storage and caching of un-typed data and indexes. It provides disk and
buffer management, transactions, concurrency control and recovery.
A second library, libshorecommon.a, provides many common
utilities need for implementing both client and servers. The third
library, librpclib.a, is a slightly modified version (for use
in a multi-threaded environment) of the Sun RPC package.
(This library is not needed for Solaris systems).
We use the term value-added-server (VAS) to refer to systems
built with the SSM. A VAS relies on the SSM for the above capabilities
and extends it to provide more functionality. One example of a VAS is
the Shore server, which extends the SSM to provide typed objects with
permissions and ownership and organizes storage as a tree structured
name-space. The overall role of the SSM in Shore is further described in
An Overview of Shore .
This document provides an overview the SSM facilities and interface.
Details of the programming interfaces are presented in a set of manual
pages. Where each facility is discussed, references are made to the
appropriate manual pages.
A novel feature of Shore is that its server is designed to be easily extended
to support new applications.
This tutorial shows how to extend the server through a detailed example,
the Grid Server.
Shore comes with a large set of manual pages in the traditional Unix style.
This page lists them all.
The manual can also be accessed through hot links from the documents listed
above, from cross-references between the man pages, and from the introduction
pages listed at the beginning of each section of man pages.