Objectivity/DB Administration : Administration Tasks : Objectivity/DB Basics
1 
Objectivity/DB Basics
This chapter describes the basic elements in an Objectivity/DB system and briefly discusses the Objectivity/DB tools you use to perform administration tasks.
Objectivity/DB System
An Objectivity/DB system consists of multiple processes and files that can be distributed across multiple host machines on a network.
Figure 1‑1 Example Objectivity/DB System
Federated Database
The federated database is the highest level in the Objectivity/DB logical storage hierarchy. Logically, a federated database contains application-created data in one or more databases; see Databases and Containers. Physically, each federated database exists as a file containing a system database, which stores:
The schema for the federated database.
The placement model for the federated database.
The main storage group (MSG) and the global catalog for the federated database.
Every federated database also has a boot file, which is used by applications and tools to refer to the federated database. The simple name of the boot file serves as the federated database’s system name. In addition, each federated database also has a unique integer identifier.
Every federated database coordinates a particular set of Objectivity/DB system resources that collectively manage access to the data in its databases. Among these resources are the system-database file, the boot file, a directory for journal files, and a lock server.
As an administrator, you may need to set or change a federated database’s properties, or you may need to determine a federated database’s memory and disk requirements. See Chapter 3, “Federated Database Tasks.”
Schema
A schema is a language-independent data model that describes all types and classes used in a particular federated database. The class descriptions in a schema allow Objectivity/DB to store and manage the federated database’s persistent objects. The schema is stored in the system database of the federated database.
Different Objectivity products and Objectivity/DB programming interfaces use different mechanisms for creating a schema.
Once created, a schema can be changed—for example, to add members or fields to a class description in response to new application requirements. Changing a schema is called schema evolution, and can be accomplished through a variety of mechanisms. The results of a schema-evolution operation are typically deployed to existing federated databases using administration tools described in this book.
For more information, see Chapter 13, “Objectivity/DB Schema.”
Placement Model
A placement model specifies where Objectivity/DB should put persistent data within the federated database. A federated database with an installed placement model is called a placement-managed federated database. When new persistent objects are added to the federated database, Objectivity/DB places them automatically.
Note:Some older federated databases do not use placement models. To find out more about administering such non-placement-managed federated databases, you must consult older versions of Objectivity/DB Administration, available from the Objectivity Developer Network.
Main Storage Group and Global Catalog
A main storage group (MSG) is a federated database’s registry of the storage locations (data-server hosts and paths) in which files of application-created data can be placed. This registry is part of the federated database’s placement system. You can think of the MSG as an inventory of the potential storage locations in which files for new databases could be created.
Whenever a new database is added to a federated database, the placement system selects a storage location for it from the MSG. The new database and its storage location are recorded in the federation’s global catalog, which lists every existing database in the federation and the storage locations in which they were created.
When a federated database is created, its MSG is empty. If you never register any storage locations for a federated database, the default behavior is for member databases to be placed in the directory containing the federated database’s system-database file.
For an overview of MSG management, see Managing the Registry of Storage Locations. For complete details about placing new files of data in storage locations, see Chapter 4, “Specifying File Storage.”
Databases and Containers
A database is the second highest level in the Objectivity/DB logical storage hierarchy. Each database stores an application’s persistent data in structures called containers, which constitute the third level in the Objectivity/DB logical storage hierarchy. Within a container, persistent data is stored in fundamental units called persistent objects.
Together, databases and containers serve as mechanisms for organizing persistent objects to suit the needs of an application—for example, to subdivide large datasets for more efficient queries. Containers additionally serve as mechanisms for optimizing efficient access to objects that are used in the same transaction and for optimizing concurrent access to objects that are used independently.
A database is physically represented by a database file. The containers belonging to a database are normally stored (or embedded) within the database’s file. Database files are typically used to distribute related containers and their persistent objects to different physical locations in your network.
Containers can optionally be stored in their own separate container files, typically to keep the size of database files within manageable limits. Such containers are called external containers. A database can logically contain any combination of embedded and external containers. Because all persistent data physically resides in a database file or a container file, these files are collectively called the data files of a federated database.
A federated database’s placement model automatically manages the creation and placement of databases and containers. As an administrator, you may need to register the available storage locations in which database files may be placed; see Chapter 4, “Specifying File Storage.”
For more details about databases and containers, see Chapter 7, “Database Tasks,” and Chapter 8, “Container Tasks.”
Journal Files
Whenever a transaction starts, it records update information in a journal file, which is used to return the federated database to its previously committed state if the transaction is aborted or terminated abnormally. Journal files enable Objectivity/DB to roll back changes made by incomplete transactions; they differ from relational-database transaction logs, which usually contain before and after images of the data and allow forward recovery up to the last commit. (Objectivity/DB supports forward recovery through its backup and restore tools.)
Journal files are written in a federated database’s journal directory. Every single-threaded application that updates the federated database creates a journal file in the journal directory. This journal file is automatically reinitialized at the end of each committed transaction and is reused by the application’s next transaction. A multithreaded application normally creates multiple journal files in the journal directory—one for each thread that executes a separate series of update transactions. As an administrator, you may need to set or change a federated database’s journal directory. See Chapter 3, “Federated Database Tasks.”
Objectivity/DB deletes journal files automatically when a process completes or when automatic recovery is performed after a process or system failure. In some cases, you should perform manual recovery when a journal file persists after a process has ended. See Chapter 12, “Automatic and Manual Recovery.”
Warning:Never delete a journal file, because data corruption may result.
Boot File
A boot file contains information used by an application or tool to locate and open a federated database. A boot file is created automatically when you create a new federated database and contains entries specifying the various federated-database properties. As an administrator, you may need to view or change these properties; see Chapter 3, “Federated Database Tasks.” You use administration tools to change a boot file; you never edit a boot file directly.
Most administration tools require that you identify the federated database of interest by specifying a bootFilePath (the path to its boot file); see Specifying Remote and Local Files.
Lock Server
Objectivity/DB supports simultaneous multiuser access to data. To ensure that data remains consistent, database access is controlled through locks administered by a lock server. In a standard configuration, the lock server runs as a separate process from the applications that consult it. An alternative configuration is for a particular application to run the lock server internally (within the same process). Such an application must use a separate feature called an in-process lock server (IPLS). In either configuration, the lock server can run on any of the workstations in a network.
A lock server can service multiple federated databases; each federated database must be serviced by a single lock server.
As an administrator, you may need to start, stop, or re-host a lock server. For more information on lock servers, see Chapter 9, “Using a Lock Server.”
Application Processes
Objectivity/DB applications are programs that store persistent data in Objectivity/DB databases. Objectivity/DB applications may be written by your development team in a supported programming language interface, or they may be components of certain Objectivity servers or products.
Objectivity/DB applications invoke database operations from the Objectivity/DB runtime library, or kernel. When an Objectivity/DB application starts a transaction to access persistent data, the Objectivity/DB kernel:
Locates and opens the appropriate data files.
Requests an appropriate lock from the lock server.
Reads the requested object from disk into memory.
Writes updates to disk if requested.
Records any updates in the appropriate journal file.
The kernel runs in the same process as the application.
Pages and the Objectivity/DB Cache
Objectivity/DB stores persistent objects on storage pages. A storage page is the minimum unit of:
File growth. When Objectivity/DB creates a new container in a database or extends a container to accommodate new persistent objects, the space is added as a whole number of storage pages.
Physical transfer to and from disk and across networks. When an application reads data from a file, one or more whole storage pages are transferred into virtual memory. Conversely, when an application commits modifications to data, one or more whole storage pages are transferred back to disk.
The size of a storage page is configurable for each data file and is set when a database or external container is created; once set, the page size cannot be changed.
Storage pages are usually sized so that one or more typical persistent objects will fit within a single storage page; each such small object occupies a slot on the page. A large object spans multiple storage pages, where one of these pages (the header page) contains overhead information and links to other pages containing data. A storage page containing a small object or the beginning of a large object is also called a logical page. Logical pages (and their slots) have integer identifiers that are used in the identifiers of persistent objects; see Referencing Objects in a Federated Database. In a data file containing only small objects, every used storage page is also a logical page. In a data file containing many large objects, the logical pages are a subset of the used storage pages.
When Objectivity/DB reads a persistent object from disk, it places the storage page(s) containing the object into the Objectivity/DB cache. The cache is memory allocated and managed by Objectivity/DB to provide fast access to persistent objects. The cache consists of buffer pages, which are sized to match the storage pages being accessed. Figure 1‑2 shows a simplified view of the cache in the virtual address space of an application process.
In a multithreaded application, each thread that executes a separate series of transactions has its own Objectivity/DB cache in the process’s address space.
Figure 1‑2 Objectivity/DB Cache
For detailed information about the structure and behavior of an Objectivity/DB cache, see the cache-management chapter in the appropriate programming-interface documentation.
Automatic Recovery
Objectivity/DB provides automatic recovery from most failures. Specifically, you can set up Objectivity/DB to automatically roll back incomplete transactions resulting from application-process failures, client-host failures, lock-server failures, and lock-server host failures. As an administrator, you need to know how to set up automatic recovery and how to perform manual recovery when necessary. See Chapter 12, “Automatic and Manual Recovery.”
Distributed Objectivity/DB Systems
You can distribute an Objectivity/DB system across a TCP/IP network by placing the various Objectivity/DB files and processes on different host machines. Appropriate distribution can improve performance, usually by shortening the network path between an application and the files or processes it uses, or by reducing the number of requests to be handled by any single network path, processor, or storage device.
Some important nodes in a distributed Objectivity/DB system are:
Client host
Network node that runs an Objectivity/DB application; sometimes called an application host
Data-server host
Network node that stores Objectivity/DB data files and journal files
Lock-server host
Network node that runs an Objectivity/DB lock server
In a distributed Objectivity/DB system, an application running on a client host may request data that is either local (the data server and client are the same host) or remote (the data-server host is different than the client host).
In general, when servicing a request for data, the Objectivity/DB kernel finds:
Local data files by directly accessing the local (client) file system.
Remote data files by contacting the specified host and contacting whichever data-server software is available:
Objectivity/DB’s Advanced Multithreaded Server (AMS).
Network File System (NFS) server.
Windows Network, if all client and data-server hosts are Windows computers, and the remote data files are specified by Universal Naming Convention (UNC) share names.
A distributed Objectivity/DB system may include hosts of different architectures, where a host’s architecture is a combination of hardware, operating system, and compiler. Objectivity/DB supports architectures on two main types of platforms—Windows and Linux. See the Objectivity Developer Network for the supported combinations of host and target architectures.
As an administrator, you may need to:
Know how to reference remote and local files. See Chapter 2, “Specifying Objectivity/DB Files.”
Register the available storage locations in which Objectivity/DB may create a federated database’s data files; see Chapter 4, “Specifying File Storage.”
Set up and run AMS, or choose between using AMS or another network file server (such as NFS) for remote data access. See Chapter 10, “Advanced Multithreaded Server.”
Understand the details of distributing an Objectivity/DB system. See Chapter 14, “Working With Distributed Systems.”
Administration Interface and Tools
Objectivity/DB provides a set of tools and scripts that support both administration and application development. An Objectivity/DB tool returns status information using the conventions of the host operating system.
See Tool and Script Summary for an overview of the kinds of tasks that you can perform using Objectivity/DB administration tools and scripts.
Mechanisms for Running Tools and Servers
You run Objectivity/DB tools and Objectivity servers as follows:
(Windows) From a command prompt or a batch script.
(Linux) From a command line or a shell script.
You can run selected Objectivity servers as services:
(Linux) See the installation and configuration documentation on the Objectivity Developer Network for information about configuring services.
Tool Runner
In most cases, you execute tools from a command line or command prompt using the tool runner, which follows the command-line conventions described in Tool Runner Syntax.
To use the tool runner to display a list of available tools:
At a command prompt, enter:
objy 
To use the tool runner to execute a particular tool such as the License command:
At a command prompt, enter:
objy License -fromDefault -bootFile myData
Note:You normally use the tool runner when running a tool from the command line, unless the documentation explicitly indicates that you should use the Classic Command-Line Syntax. Scripts are not run through the tool runner.