Objectivity/DB Administration

Objectivity/DB Administration

Release 8.0

Objectivity/DB Administration

Part Number: 80-DBA-0

Release 8.0, August 20, 2003

The information in this document is subject to change without notice. Objectivity, Inc. assumesno responsibility for any errors that may appear in this document.

Copyright 2003 by Objectivity, Inc. All rights reserved. This document may not be copied,photocopied, reproduced, translated, or converted to any electronic or machine-readable formin whole or in part without prior written approval of Objectivity, Inc.

Objectivity and Objectivity/DB are registered trademarks of Objectivity, Inc.Active Schema, Objectivity/DB Active Schema, Objectivity/DB ooAssistant, ooAssistant,Objectivity/DB Fault Tolerant Option, Objectivity/FTO, Objectivity/DB Data ReplicationOption, Objectivity/DRO, Objectivity/DB High Availability, Objectivity/HA, Objectivity/DBHot Failover, Objectivity/DB In-Process Lock Server, Objectivity/IPLS, Objectivity/DB OpenFile System, Objectivity/OFS, Objectivity/DB Secure Framework, Objectivity/Secure,Objectivity/C++, Objectivity/C++ Data Definition Language, Objectivity/DDL,Objectivity/C++ Active Schema, Objectivity/C++ Standard Template Library, Objectivity/C++STL, Objectivity/C++ Spatial Index Framework, Objectivity/Spatial, Objectivity for Java,Objectivity/Smalltalk, Objectivity/SQL++, Objectivity/SQL++ ODBC Driver,Objectivity/ODBC, and Objectivity Event Notification Services are trademarks of Objectivity,Inc. Standards<ToolKit> is a trademark of Recursion Software, Inc. Other trademarks andproducts are the property of their respective owners.

ODMG information in this document is based in whole or in part on material from The ObjectDatabase Standard: ODMG 2.0, edited by R.G.G. Cattell, and is reprinted with permission ofMorgan Kaufmann Publishers. Copyright 1997 by Morgan Kaufmann Publishers.

The software and information contained herein are proprietary to, and comprise valuable tradesecrets of, Objectivity, Inc., which intends to preserve as trade secrets such software andinformation. This software is furnished pursuant to a written license agreement and may beused, copied, transmitted, and stored only in accordance with the terms of such license andwith the inclusion of the above copyright notice. This software and information or any othercopies thereof may not be provided or otherwise made available to any other person.

U. S. Government Restricted Rights: Use, duplication or disclosure of the software or otherinformation by the U. S. Government or any unit or agency thereof is subject to restrictions asset forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Softwareclause at DFARS 252.227-7013 and the Government is acquiring only restricted rights in thesoftware and limited rights in any technical data provided (as such terms are defined in suchclause of the DFARS). If the software or other information is supplied to any unit or agency ofthe U. S. other than the Department of Defense, the Government’s rights will be as defined inclause 52.227-19(c)(2) of the FAR or, in the case of NASA, in clause 18-52.227-86 (d) of the NASASupplement to the FAR.

DRAFT

3

<6/11/2003, 12:40 PM; /wrld/mnt09/pubs/working/admin/administrationTOC.fm>

Contents

About This Book 13Audience 13

Organization 13

Conventions and Abbreviations 14

Getting Help 15

Part 1 GUIDE

Chapter 1 Objectivity/DB Basics 19Objectivity/DB System 19

System-Database File 20Database Files 20Autonomous Partitions and Replicated Databases 21Journal Files 22Boot File 22Lock Server 23Application Processes 23Pages and the Objectivity/DB Cache 23Automatic Recovery 25Distributed Objectivity/DB Systems 25

Administration Interface and Tools 26Overview of Administration Tools 26

Chapter 2 Specifying Objectivity/DB Files 31Filenames 31

System-Database Files 31

DRAFT

4 Objectivity/DB Administration


Database Files 32Journal Files 32Boot Files 33

File and Directory Access Permissions 33

Specifying Remote and Local Files 33Host and Path Formats 34Preserving Spaces in Pathnames 36Filename Case Sensitivity 37Setting a Boot File Environment Variable 37

Chapter 3 Federated Database Tasks 39About Federated Databases 40

Partitioned Federated Databases 41Federated-Database Licensing 41

Getting Federated-Database Information 42Listing Current Properties 42Listing All Associated Files 42Determining the File Type 42Summary of Tools That Display Properties 43

Creating a Federated Database 43Examples 45

Copying a Federated Database 47

Changing Federated-Database Properties 48Moving a Federated Database 48

Deleting a Federated Database 49

Managing a Federated Database’s License 49Setting Up a License File 49Updating a Federated Database’s License 50Verifying a Federated Database’s License 51

Installing a Federated Database 51

Exporting and Importing a Federated Database 52

Tidying a Federated Database 53Background 53How ootidy Works 53Guidelines for Using ootidy 54

Troubleshooting 54Checking Access Problems 54

DRAFT

Objectivity/DB Administration 5


Checking Consistency Problems 55

Getting Transaction Information 56

Referencing Objects in a Federated Database 57

Estimating Disk Space Requirements 59Estimating Initial Requirements 59Estimating Maximum Federated Database Size 59

Chapter 4 Browsing Objects and Types 63Information You Can Browse 64

Data Browser 64Type Browser 65Query Browser 66

Opening Browsers on Windows 67Starting and Using oobrowse 67Quitting oobrowse 67

Opening Browsers on UNIX 68Starting and Using ootoolmgr 68Quitting ootoolmgr 68

Chapter 5 Debugging a Federated Database 69Inspecting and Editing a Federated Database 69

Starting oodebug as a Separate Process 70Changing oodebug Modes 70Performing Transactions With oodebug 71Terminating oodebug 71

Running oodebug in a C++ Debugger 72Terminating oodebug Within a Debugger 73

Using ooprint in a C++ Debugger 73

Chapter 6 Database Tasks 75About Databases 76

Database Identifier Formats 76Read-Only and Read-Write Databases 77Replicated Databases 77

Getting Database Information 78Getting a System Name or Database Identifier 78Getting a Database’s File Host and Path 78

DRAFT



Getting a Database’s Page Size 78Getting a List of Read-Only Databases 78

Creating a Database 79

Moving a Database File 80

Copying a Database File 80

Attaching a Database to a Federated Database 81Moving a Database Between Federated Databases 81Duplicating a Database Within a Federated Database 82Guidelines for Attaching a Database 83Consequences of Changing a Database Identifier 83Attaching Multiple Databases 83

Changing Database Properties 85Changing the System Name or Database Identifier 85

Deleting a Database 86

Setting File Permissions on a Database 86

Tidying a Database 86

Troubleshooting Access Problems 87

Chapter 7 Using a Lock Server 89About Lock Servers 89

Locks 90Lock-Server Host 90Types of Lock Server 91Lock Servers on the Network 92Required File and Directory 92

Deciding Whether to Use a Lock Server 92

Checking Whether a Lock Server is Running 93

Starting a Lock Server 93Standard Lock Server 93In-Process Lock Server 94

Stopping a Lock Server 95Standard Lock Server 95In-Process Lock Server 96

Changing Lock-Server Hosts 96

Listing Current Locks 97

Changing the TCP/IP Port for the Lock Server 97

DRAFT



Troubleshooting Problems With the Lock Server 99

Chapter 8 Advanced Multithreaded Server 103About AMS 103

Deciding Whether to Use AMS 104Guidelines for Choosing AMS 104

Checking Whether AMS is Running 104

Starting AMS 105

Stopping AMS 106

Setting AMS Usage in an Application 106

Changing the TCP/IP Port for AMS 106

Troubleshooting Problems With AMS 108

Chapter 9 Backup and Restore 109About Backup and Restore 109

Basic Backups 110Point of Restore 111Full Restore 111Backup Diary 111User Access During Backup and Restore 112Backup Boot File 112

Developing a Backup Strategy 113Estimating the Disk Space Required for Backups 113Defining a Backup Schedule 114

Performing a Backup 115If a Backup Fails 116

Restoring From a Backup 116Specifying the Point of Restore 116Restoring Files to Their Original Locations 117Restoring Files to a Single New Location 118Restoring Files to Multiple New Locations 119If a Restore Fails 121

Managing Backup History 122Displaying Backup History 122Deleting Unwanted Backups 122

Processing Backup Files 123Processing Backup Files During a Backup 123

DRAFT



Processing Backup Files During a Restore 123

Backing Up to and Restoring From Tape 124Configuring ootapebackup and ootaperestore 124Backing Up to Tape 125Restoring From Tape 125

Customized Backups 126Backup Structures 126Backup Levels 128Full Restore 129Defining a Backup Schedule For 10 Backup Levels 129Creating Backup Sets 131Performing a Customized Backup 131Restoring a Customized Backup 132

Chapter 10 Automatic and Manual Recovery 135About Recovery 135

Automatic Recovery From Application Failures 136

Automatic Recovery From Client-Host Failures 137Enabling the Lock Server’s Recovery Monitor 138Configuring a Client Host to Perform Recovery 139

Automatic Recovery From Lock-Server Failures 140Performing Recovery at Lock-Server Startup 141Performing Recovery When Locks are Requested 141Guidelines for Lock-Server Setup 142

Performing Manual Recovery 143Manual Recovery With oocleanup 144Manual Recovery From Application Failures 144Manual Recovery From Client-Host Failures 145Manual Recovery From Lock-Server Host Failures 146Manual Recovery From oocleanup Failures 146

Chapter 11 Exporting and Importing 147About Exporting 147

Objectivity/DB Structures You Can Export 147XML Elements Representing Exported Structures 148Control Over Readability 150XML Files 151Install File 151

DRAFT



About Importing 152What You Can Import 152Destination Federated Database 153What Import Operations Can Create 153Schema Compatibility 155Control Over Imported Catalogs 156Containment Hierarchy and Clustering 156Data Packing 157Identifiers 157Reference Attributes and Relationships 158Multiple Passes 158

Copying a Development Federated Database 159

Merging Federated Databases 160

Importing a Group of Databases 161

Transferring a Global Catalog 162Duplicating Database Structure 162

Modifying an Imported Global Catalog 162Filtering Out a Database 163Renaming an Imported Database 163Specifying an Imported Database’s Identifier 164Specifying Filenames and Locations 164Configuring Partitions and Replicated Data 165

Synchronizing Schemas 166Duplicating a Schema 166Checking for Identical Schemas 166Adding Classes to a Populated Schema 167

Transferring Data 168

Chapter 12 Working With Distributed Databases 169Elements of a Distributed Environment 169

Using Windows Hosts 170Windows Data-Server Hosts 170Windows Client Hosts 171Lock-Server Hosts 171Boot-File Location 172

Mixed Environments: Summary 172

DRAFT



Chapter 13 Deploying to End Users 173Building C++ Applications for End Users 173

Distributing Objectivity Executables 174Executables You May Distribute 174Executables You May Not Distribute 174

Distributing Libraries (Windows) 175For Deployed Applications 175For Redistributed Objectivity Executables 175

Distributing Libraries (UNIX) 176For Deployed Applications 176For Redistributed Objectivity Executables 176

Setting Up the End-User Site 177Hardware Requirements 177Software Requirements 177Objectivity/DB Setup (Windows) 177Objectivity/DB Setup (UNIX) 177

Installing a Federated Database 178

Part 2 REFERENCE

Chapter 14 Tools 181

Chapter 15 oodebug Commands 281

Appendix A Running Objectivity Servers on Windows 297Starting and Stopping an Objectivity Server 297

Configuring an Objectivity Server 298Specifying a Service’s Logon Account 298

Installing and Uninstalling an Objectivity Server 299

Appendix B Third-Party Software Used by Objectivity/DB301XML Export and Import Tools 301

DRAFT



Index 303

DRAFT



13

<6/11/2003, 12:40 PM; /wrld/mnt09/pubs/working/admin/admPreface.fm>

DRAFT

About This Book

This book, Objectivity/DB Administration, describes how to administerObjectivity/DB in development and end-user environments. It discusses how toensure optimum system performance and maintain the smooth, ongoingoperation of Objectivity/DB.

Objectivity/DB provides tools and programming interfaces to help performadministration tasks. The tasks and tools are similar on all platforms; minordifferences in usage, behavior, and naming that exist between different platformsare noted. The tools are described in this book; programming interfaces aredescribed in the Objectivity/C++, Objectivity for Java, and Objectivity/Smalltalkdocumentation.

Audience

This book is intended for administrators who set up and maintainObjectivity/DB federated databases in either single- or mixed-platformenvironments.

Organization

■ Part 1 is a guide to administering Objectivity/DB. Chapter 1 describesObjectivity/DB files and processes and gives an overview of theadministration tools. Subsequent chapters describe the tasks involved inmaintaining Objectivity/DB.

■ Part 2 contains reference descriptions of the Objectivity/DB administrationtools.

■ Appendix A provides protocols for using the Objectivity Network Servicestool to run Objectivity servers on Windows platforms.

DRAFTAbout This Book



Conventions and Abbreviations

Navigation

In the online version of this book, table of contents entries, index entries,cross-references, and underlined text are hypertext links.

Typographical Conventions

Abbreviations

Command Syntax Symbols

oobackup Command, literal parameter, code sample, filename, pathname,output on your screen, or Objectivity-defined identifier

installDir Variable element (such as a filename or a parameter) for which youmust substitute a value

Browse FD Graphical user-interface label for a menu item or button

lock server New term, book title, or emphasized word

(administration) Feature intended for database administration tasks

(HA) Feature of the Objectivity/DB High Availability product

(IPLS) Feature of the Objectivity/DB In-Process Lock Server product

(ODMG) Feature conforming to the Object Database Management Groupinterface

[...] Optional item. You may either enter or omit the enclosed item.

{…} Item that can be repeated.

...|... Alternative items. You should enter only one of the items separatedby this symbol.

(…) Logical group of items. The parentheses themselves are not part ofthe command syntax; do not type them.

DRAFT Command and Code Conventions



Command and Code Conventions

In code examples or commands, the continuation of a long line is indented.Omitted code is indicated with the ellipsis (…) symbol. “Enter” refers to thestandard key (labeled either Enter or Return) for terminating a line of input.

Getting Help

We have done our best to make sure all the information you need to install andoperate Objectivity products is provided in the product documentation.However, we also realize problems requiring special attention sometimes occur.

Technical Support Web Site

You can find answers to frequently asked questions, supported platforms, knownbugs, and bug fixes on the Objectivity Technical Support web site. Sendelectronic mail or call Objectivity Customer Support to gain access to the site.

How to Reach Objectivity Customer Support

You can contact Objectivity Customer Support by:■ Telephone: Call 1.650.254.7100 or 1.800.SOS.OBJY (1.800.767.6259) Monday

through Friday between 6:00 A.M. and 6:00 P.M. Pacific Time, and ask forCustomer Support.The toll-free 800 number can be dialed only within the 48 contiguous states ofthe United States and Canada.

■ Fax: Send a fax to Objectivity at 1.650.254.7171.■ Electronic Mail: Send electronic mail to [email protected].

Before You Call

Please be ready to submit the following to Objectivity Customer Support:■ Your name, company name, address, telephone number, fax number, and

email address■ Detailed description of the problem you have encountered■ Information about your workstation environment, including the type of

workstation, its operating system version, and compiler or interpreter■ Information about your Objectivity products, including the version of the

Objectivity/DB libraries

You can use the Objectivity/DB oosupportinfo tool to obtain informationabout your workstation environment and your Objectivity products.

DRAFTAbout This Book



17

<6/10/2003, 4:20 PM; /wrld/mnt09/pubs/working/admin/admPart1.fm>

DRAFT

Part 1 GUIDE

DRAFT



19

<7/9/2003, 1:57 PM; /wrld/mnt09/pubs/working/admin/admBasics.fm>

DRAFT

1Objectivity/DB Basics

This chapter describes the basic elements in an Objectivity/DB system andprovides an overview of the Objectivity/DB tools you use to performadministration tasks.

Objectivity/DB System

An Objectivity/DB system consists of multiple processes and files that can bedistributed across multiple host machines on a network (see Figure 1-1).

Figure 1-1 Example Objectivity/DB Configuration

Application

ObjectivityKernel

Lock Server

Local File

Host 1Host 2

Network

Data Server(AMS/NFS)

SystemDatabase File

Boot File

Journal File 1

Database File 1Lock-Server Host= Data transfer

= Lock requests

System

Process

Database File nHost 3

DRAFTObjectivity/DB Basics System-Database File



System-Database File

The federated database is the highest level in the Objectivity/DB logical storagehierarchy. Physically, each federated database exists as a file containing a systemdatabase, which stores the schema for the federated database, as well as a globalcatalog of the additional databases that make up the federation. Each federateddatabase is assigned a unique integer that identifies it to Objectivity/DBprocesses such as the lock server.

Every federated database has a boot file. Database applications and tools refer to afederated database using its boot-file name. The simple name of a boot file issometimes called the federated database’s system name.

As an administrator, you may need to change a federated database’s propertiesor location, or you may need to determine a federated database’s memory anddisk requirements; see Chapter 2, “Specifying Objectivity/DB Files,” andChapter 3, “Federated Database Tasks.”

Schemas

A schema is a language-independent data model that describes all types andclasses used in a particular federated database. The descriptions in a schemaallow Objectivity/DB to store and manage the federated database’s persistentobjects. The schema is stored in the system database of the federated database.

Schema creation depends on the programming interface:■ For Objectivity/C++, a schema is created by defining classes using the

Objectivity/C++ Data Definition Language (DDL) and processing them withthe DDL processor.

■ For Objectivity for Java and Objectivity/Smalltalk, a schema is createdautomatically when persistent objects are created.

■ For Objectivity/SQL++, a schema is created automatically when tables arecreated.

Once created, a schema can be changed—for example, to add members or fieldsto a class description in response to new application requirements. Changing aschema, called schema evolution, can be accomplished through a programminginterface or through one of the Objectivity/DB Active Schema products. Theresults of a schema-evolution operation are typically deployed to existingfederated databases using administrative tools described in this book.

Database Files

A database is the second highest level in the Objectivity/DB logical storagehierarchy and is where your application’s persistent data is stored. A databaseconsists of one or more logical structures called containers, which in turn contain

DRAFTObjectivity/DB Basics Autonomous Partitions and Replicated Databases



fundamental units of persistent data called basic objects. Containers determine thephysical clustering of basic objects in memory and on disk. Each databasecontains a default container for any basic object not assigned to a user-createdcontainer.

A database is physically represented by a database file, which contains thedatabase and all of its containers and basic objects. Each database is attached toexactly one federated database and is listed in that federated database’s globalcatalog. Database files may reside on different machines than the file for thefederated database to which they are attached.

Every database has a unique integer identifier within its federated database. Inaddition to having a physical filename, a database also has a user-specifiedsystem name, which is its logical name within the federated database. Thefederated database’s system database is a special database with the reservedidentifier 1.

As an administrator, you may need to change a database’s properties or location;see Chapter 2, “Specifying Objectivity/DB Files,” and Chapter 6, “DatabaseTasks.”

Autonomous Partitions and Replicated Databases

Autonomous partitions are a mechanism for organizing a federated database intoindependently managed groups of databases. Although data physically residesin database files, each autonomous partition controls access to the databases thatbelong to it. When a network or machine failure prevents access to data in onepartition, users can continue to access the data controlled by the remainingpartitions. This capability is available through the separately licensedObjectivity/DB High Availability product (Objectivity/HA).

An autonomous partition is physically represented by a system-database file.This file contains a copy of the federation’s system database, which stores theschema and a global catalog of all autonomous partitions and databases. Everyautonomous partition has a unique integer identifier, a system name and a bootfile. At creation, a federated database serves as a single implicit autonomouspartition.

Autonomous partitions are the foundation for data replication—that is, forcreating and managing multiple copies of a database, called database images.Database applications automatically access the closest image, reducing networktraffic; if an image becomes inaccessible due to network or system problems,work may continue with an accessible image.

As an administrator, you may need to perform the partition- and image-specifictasks described in Objectivity/DB High Availability, and you may need to considerpartitions and images for the administrative tasks in this book.

DRAFTObjectivity/DB Basics Journal Files



Journal Files

Whenever a transaction starts, it records update information in one or morejournal files, which are used to return the federated database to its previouslycommitted state if the transaction is aborted or terminated abnormally. Journalfiles enable Objectivity/DB to roll back changes made by incompletetransactions; they differ from relational-database transaction logs, which usuallycontain before and after images of the data and allow forward recovery up to thelast commit. (Objectivity/DB supports forward recovery through its backup andrestore tools.)

Journal files are written in a federated database’s journal directory. In a partitionedfederated database, each autonomous partition has a unique journal directory. Atransaction that updates data in multiple partitions writes to multiple journalfiles, one in each journal directory. As an administrator, you may need to specifyor change journal directories; see Chapter 3, “Federated Database Tasks.”

Every single-threaded application normally creates one journal file perautonomous partition that will be updated by the transaction. This journal file isautomatically reinitialized at the end of each committed transaction and is reusedby the application’s next transaction. Multithreaded applications normally createmultiple journal files per autonomous partition, one for each thread that executesa separate series of transactions.

Objectivity/DB deletes journal files automatically when a process completes orwhen automatic recovery is performed after a process or system failure. In somecases, you should perform manual recovery when a journal file persists after aprocess has ended; see Chapter 10, “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 opena federated database. A boot file is created automatically when you create a newfederated database and contains entries specifying the variousfederated-database properties. As an administrator, you may need to view orchange these properties; see Chapter 3, “Federated Database Tasks.” You useObjectivity/DB tools to change a boot file; you never edit a boot file directly.

Most administration tools require that you refer to a federated database byspecifying the path to its boot file; see “Specifying Remote and Local Files” onpage 33. You can do this explicitly, or you can set the pathname in anenvironment variable; “Setting a Boot File Environment Variable” on page 37.

DRAFTObjectivity/DB Basics Lock Server



In a partitioned federated database, every autonomous partition has its own bootfile, which is created automatically when the partition is created. Most toolsallow you to refer to a partitioned federated database by specifying the boot filefrom any partition.

Lock Server

Objectivity/DB provides simultaneous multiuser access to data. To ensure thatdata remains consistent, database access is controlled through locks administeredby a lock server. In a standard configuration, the lock server runs as a separateprocess from the applications that consult it. An alternative configuration is for aparticular application to run the lock server internally (within the same process).Such an application must use a separately purchased option to Objectivity/DB,namely, Objectivity/DB In-Process Lock Server (Objectivity/IPLS). In eitherconfiguration, the lock server can run on any of the workstations in a network.

A lock server can service multiple federated databases; each federated database(or each autonomous partition in a federated database) must be serviced by asingle lock server.

For more information on lock servers, see Chapter 7, “Using a Lock Server.”

Application Processes

Objectivity/DB applications are C++, Java, or Smalltalk applications that storepersistent data in Objectivity/DB databases. Such applications invoke databaseoperations from the Objectivity/DB runtime library, or kernel. When yourapplication starts a transaction to access persistent data, the Objectivity/DBkernel:■ Locates and opens the appropriate federated-database and database files.■ Requests an appropriate lock from the lock server.■ Reads the requested object from disk into memory.■ Writes updates to disk if requested.■ Records the transaction in the appropriate journal file.

Because the kernel runs in the same process as your application, there is no needfor a separate database server process.

Pages and the Objectivity/DB Cache

Objectivity/DB stores persistent objects in storage pages. A storage page is theminimum unit of transfer to and from disk and across networks. The size of apage is configurable for each federated database and is set when the federateddatabase is created; once set, the page size cannot be changed. See oonewfd

DRAFTObjectivity/DB Basics Pages and the Objectivity/DB Cache



(page 263) for information about setting the storage-page size for a federateddatabase.

A federated database’s storage pages are usually sized so that one or moretypical persistent objects will fit within a single storage page; each such smallobject occupies a slot on the page. A large object spans multiple storage pages,where one of these pages (the header page) has a slot containing overheadinformation and links to other pages containing data. Large-object header pagesand the storage pages for small objects are sometimes called logical pages; thesepages (and their slots) are assigned numbers that help identify persistent objects(see “Referencing Objects in a Federated Database” on page 57).

When Objectivity/DB reads a persistent object from disk, it places the storagepage(s) containing the object into the Objectivity/DB cache. The cache is memoryallocated and managed by Objectivity/DB to provide fast access to persistentobjects. The cache consists of buffer pages, which are the same size as the storagepages in the federated database. Figure 1-2 shows the role of the cache in thevirtual address space of an application process.

In a multithreaded application, each thread that executes a separate series oftransactions has its own Objectivity/DB cache in the process’s address space.

Figure 1-2 Objectivity/DB Cache in a Single-Threaded Process

Objectivity/DB

Disk

Application ProcessVirtual Address Space

Application Code

Objectivity/DBKernel

= Buffer page in Objectivity/DB cache; storage page on disk

Cache

DRAFTObjectivity/DB Basics Automatic Recovery



Automatic Recovery

Objectivity/DB provides automatic recovery from most failures. Specifically, youcan set up Objectivity/DB to automatically roll back incomplete transactionsresulting from application-process failures, client-host failures, lock-serverfailures, and lock-server host failures. As an administrator, you need to knowhow to set up automatic recovery and how to perform manual recovery whennecessary; see Chapter 10, “Automatic and Manual Recovery.”

Distributed Objectivity/DB Systems

You can distribute an Objectivity/DB system across a network by placing thevarious Objectivity/DB files and processes on different hosts. Some importantnodes in a distributed Objectivity/DB system are:

In a distributed Objectivity/DB system, an application running on a client hostmay 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). Note that adistributed system may, but need not, be partitioned (Objectivity/HA).

In general, when servicing a request for data, the Objectivity/DB kernel finds:■ Local databases by directly accessing the local (client) file system■ Remote databases 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

However:■ If you use replicated databases (Objectivity/HA), the kernel contacts only

AMS to find those databases. Even if a replicated database is local to theclient host, the kernel contacts AMS instead of the local file system.

■ If all client and data-server hosts are Windows workstations, the kernel cancontact Windows Network to find remote database, provided that all hostsuse a common set of Universal Naming Convention (UNC) share names.

Accessing a database or federated database across a network may add significantamounts of I/O time and CPU time due to network overhead and contention. Anapplication’s speed is likely to improve significantly if it accesses local databases.

Client host Network node that runs an Objectivity/DB application;sometimes called an application host

Data-server host Network node that provides data storage; location offederated database, database, partition, and journal files

Lock-server host Network node that runs an Objectivity/DB lock server

DRAFTObjectivity/DB Basics Administration Interface and Tools



As an administrator, you may need to set up and run AMS, or help to choosebetween using AMS or another network file server (such as NFS) for remote dataaccess; see Chapter 8, “Advanced Multithreaded Server.” You may also need todecide where to locate the various elements of an Objectivity/DB system in adistributed, heterogeneous environment; see Chapter 12, “Working WithDistributed Databases.” You may also need to know how to reference remote andlocal files; see Chapter 2, “Specifying Objectivity/DB Files.”

Administration Interface and Tools

Objectivity/DB provides a set of tools that support both administration andapplication development. Each Objectivity/DB tool returns status informationusing the conventions of the host operating system. For reference information onthese tools, see Chapter 14, “Tools.”

On UNIX, you run Objectivity/DB tools from a command line or a shell script.

On Windows:■ You can run tools either from a command prompt or from the objytool

graphical interface.■ You run Objectivity servers (such as the lock server and AMS) from the

graphical interface of the Objectivity Network Services tool.

You can create your own tools for administration tasks using theObjectivity/C++, Objectivity for Java, or Objectivity/Smalltalk interfaces. Formore information, see the documentation for these programming interfaces.

NOTE As an alternative to using command-line tools for various tasks, you can use theObjectivity/Assist graphical tool; see Objectivity/Assist (page 185).

Overview of Administration Tools

Table 1-1 gives an overview of the kinds of tasks that you can perform usingObjectivity/DB administration tools. (Tools specific to autonomous partitionsand replicated data are described in Objectivity/DB High Availability.)

DRAFTObjectivity/DB Basics Overview of Administration Tools



Table 1-1: Overview of Administration Tools

Creating and ModifyingFederated Databases

Objectivity/Assist Creates a federated database, itsschema, and persistent objects.

oochange Displays or changes the properties ofa federated database or autonomouspartition.

oocopyfd Copies a federated database.

oodeletefd Deletes a federated database.

ooexportcatalog Writes a federated database’s globalcatalog to an XML file.

ooexportdata Writes a federated database’spersistent objects to an XML file.

ooexportfd Writes an entire federated databaseto an XML file.

ooexportschema Writes a federated database’sschema to an XML file.

ooimport Imports the contents of an XML file toa federated database.

ooinstallfd Installs a remote federated database.

oolicense Displays or updates the license in afederated database.

oonewfd Creates a federated database.

ooschemadump Writes a federated database’sevolved schema to a file.

ooschemaupgrade Applies an evolved schema to afederated database.




Creating and ModifyingDatabases

ooattachdb Attaches a database to a federateddatabase.

oochangedb Displays or changes the properties ofa database or database image.

oocopydb Copies a database.

oodeletedb Deletes a database from a federateddatabase.

oonewdb Creates a new database.

Getting Information Objectivity/Assist Browses objects and types; displaysthe physical and logical componentsof a federated database.

oobrowse Browses objects and types, andmakes queries (on Windows).

oochange Displays or changes the properties ofa federated database or autonomouspartition.

oochangedb Displays or changes the properties ofa database or database image.

oodumpcatalog Lists all the files in a federateddatabase.

oofile Displays information about adatabase or federated database.

oolockmon Lists all processes and lockscurrently managed by a lock server.

oolistwait Lists waiting transactions.

oosupportinfo Displays information needed byObjectivity Technical Support.

ootoolmgr Browses objects and types, andmakes queries (on UNIX).

Table 1-1: Overview of Administration Tools (Continued)




Backup and Restore oobackup Archives a federated database.

oocreateset Creates a backup set for a federateddatabase.

oodeleteset Deletes a backup set.

ooqueryset Queries a federated database forexisting backup sets.

oorestore Restores an archived federateddatabase.

Managing ObjectivityServers

ObjectivityNetwork Services

Starts Objectivity servers(on Windows).

oocheckams Checks whether AMS is running on asystem.

oocheckls Checks whether a lock server isrunning on a system.

ookillls Kills a lock server.

oolockmon Lists all processes and lockscurrently managed by a lock server.

oolockserver Starts a lock-server process for afederated database.

oostartams Starts AMS.

oostopams Terminates AMS.

Maintenance andRecovery

oocheck Checks the consistency of afederated database.

oocleanup Rolls back transactions that haveterminated abnormally.

ootidy Consolidates a fragmented federateddatabase or database.

oogc Deletes unreferenced objects in afederated database (Objectivity forJava and Objectivity/Smalltalk only).





Miscellaneous objytool Graphical interface for startingadministration tools (on Windows).

ooconfig Creates a DDL processor for yourcompiler (Objectivity/DDL on UNIXonly).

oodebug Provides commands for inspectingand editing a federated database.


31

<6/11/2003, 12:40 PM; /wrld/mnt09/pubs/working/admin/admFileNames.fm>

DRAFT

2Specifying Objectivity/DB Files

Many administrative tasks involve creating or referencing Objectivity/DB files(system-database, database, journal, and boot files). This chapter providesimportant information about:■ Filenames■ Access permissions■ Pathnames for local and remote files

Filenames

System-Database Files

Federated Database

You specify the name of a federated database’s system-database file when youcreate it or rename it (see Chapter 3, “Federated Database Tasks”).

By convention, you construct the name of the system-database file from thefederated database’s system name plus an extension, typically .fdb, .FDB, or.FDDB:

fdSysName.FDB

A federated database’s system name is the name of the associated boot file; see“Boot Files” on page 33.

Autonomous Partition

(HA) You specify the name of the partition’s system-database file when youcreate the partition; see Objectivity/DB High Availability.

DRAFTSpecifying Objectivity/DB Files Database Files



By convention, you construct this filename from the partition’s system name plusan extension, typically .AP:

apSysName.AP

Because the first autonomous partition is created automatically when you createthe federated database, the initial partition’s system name and filename are thoseof the federated database.

Database Files

You can specify the name of a database file when you create the database (seeChapter 6, “Database Tasks”). Alternatively, you can let the filename begenerated automatically. Generated filenames are of the form:

dbSysName.fdSysName.DB

where dbSysName is the system name of the database and fdSysName is thesystem name of the federated database.

(HA) You can specify the name of a database image file when you create thedatabase image. Alternatively, you can let the filename be generatedautomatically. Generated filenames are of the form:

dbSysName.apId.fdSysName.DB

where apId is the autonomous-partition identifier.

Journal Files

You specify the location (host and directory) for journal files when you create afederated database or change its properties.

(HA) You specify a unique journal-directory host and path for an autonomouspartition when you create the partition (see Objectivity/DB High Availability) orchange its properties.

The names of journal files are always generated. They are of the form:

oo_fdSysName_apId_hostName_processId_userName_sessionID.JNL

where

fdSysName System name of the federated database.

apId Autonomous-partition identifier. For single-partition federateddatabases, this identifier is 65535.

hostName Name of the host on which the transaction is running.

processId Process ID (pid) of the process in which the transaction occurs.

DRAFTSpecifying Objectivity/DB Files Boot Files



For example: oo_testfd_6_machine12_12345_joe_1.JNL

Boot Files

You specify the name of a boot file when you create a federated database(page 43). A boot file does not require a filename extension. The simple name ofthe boot file is the system name for the federated database.

(HA) When you create an autonomous partition, you may specify the name of itsboot file, but you need not do so. If you do not specify a filename, the defaultfilename is derived by appending the .boot extension to the system name of theautonomous partition. (See Objectivity/DB High Availability for information aboutcreating an autonomous partition.)

File and Directory Access Permissions

Access permissions are set on system-database files, database files, journal files,and boot files when they are created by Objectivity/DB tools or applications. Youshould ensure that every user account that runs such tools and applications setspermissions as appropriate to give other accounts the access they require. Inparticular, the accounts that run AMS or the lock server must be able to read andupdate all Objectivity/DB files. When an application uses AMS, any files createdby the application are owned by the user account under which AMS was started.You typically create a special account for running AMS and always start AMSunder that account.

Specifying Remote and Local Files

Many administration tools and programming interfaces require that you specifythe names of Objectivity/DB files:■ Administration tools that create or relocate system-database, database, or

journal files allow you to specify the desired locations for these files. Thespecified locations are generally stored in boot files and the federateddatabase’s global catalog.

■ Administration tools that operate on a federated database require you tospecify a boot file for that federated database.

userName Name of the user who started the process.

sessionID Session ID of the thread in which the transaction occurs; sometimesfollowed by one or more letters.

DRAFTSpecifying Objectivity/DB Files Host and Path Formats



■ In programming interfaces, functions that open a federated database requirethat you specify a boot file for that federated database.

Host and Path Formats

When your Objectivity/DB system is distributed among multiple hosts, you mayneed to specify remote files (files located on remote data-server hosts) in additionto local files (files located on host where you are running the tool or application).Objectivity/DB tools and functions use the following conventions for obtaininghost and pathname information:■ Boot-file names are usually specified through a single argument or

parameter value. Each such name can be specified in host format, where youexplicitly specify the boot-file host separated from the pathname by twocolons:host::path

■ Names of system-database files, database files, and journal files are usuallyspecified as a pair of options specifying host and path values. Thisinformation is presented in host format when you display the contents of theboot file or global catalog in which it is stored.

The following subsections describe how to specify host and path values (inhost-format names or as separate options) to reference files that reside on thedifferent kinds of data-server hosts.

Files on the Local Host

To designate a file that resides on the local host (the host where you are runningthe tool or application), you can omit the host value and specify a relative orabsolute pathname in the format accepted by the local operating system. Whenyou specify a local path, omitting the host value is the same as specifying thename of the local host. Note, however, that you must include a host value (evenfor a local host) when specifying a boot file path to the oolockserver tool(page 259).

Names that are stored in a boot file or the global catalog must be usable by everyapplication that will consult that boot file or catalog, including applicationsrunning on remote client hosts. Take this into account when specifying files onWindows hosts, which allow files to have both local names (for example,c:\project\myFD) and network-visible names (for example,\\mach33\c\project\myFD). To make a local file visible to remote Windowsclients, you must specify host and path values as described in “Files onWindows Network Data-Server Hosts” on page 36.

DRAFTSpecifying Objectivity/DB Files Host and Path Formats



Files on AMS Data-Server Hosts

To designate a file on a remote data-server host running AMS, you specify hostand pathnames as follows:

When specifying a file on a Windows host running AMS, you must use thelocally understood pathname; do not use a UNC share name.

Files on AMS data-server hosts are available to database applications running onWindows and UNIX client hosts.

Files on NFS Data-Server Hosts

To designate a file on a remote data-server host running NFS, you specify hostand pathnames as follows:

Alternatively, you can omit the host value and specify a locally understood NFSmount name for the file (for example, /net/machine33/usr/project1/myFD).When you specify an NFS mount name, Objectivity/DB uses the mount table totranslate the mount name into a host-format name whose host is the remote hostand whose path is the file’s name on that host.

Files on NFS data-server hosts are available to database applications running onWindows and UNIX client hosts.

host The data-server host’s TCP/IP network node name.

path The fully qualified path of the file on the specified host. The path is passedto AMS on that host. Because AMS passes the path to the specified host’sfile system, you use pathnames that are local to that host—for example, onWindows:c:\project\myFD

host The data-server host’s TCP/IP network node name.

path The fully qualified path of the file on the specified host. The path is passedto the NFS server on that host. The path must start with the name of theNFS-exported file system that contains the file—for example, on a UNIXplatform where /usr is exported:/usr/project1/myFD

The name format may vary among NFS products on Windows hosts.

DRAFTSpecifying Objectivity/DB Files Preserving Spaces in Pathnames



Files on Windows Network Data-Server Hosts

To designate a file on a remote Windows Network data-server host, where thatfile is shared through a common Universal Naming Convention (UNC) sharename, you specify host and pathnames (from a Windows client host) as follows:

All Windows client hosts and data-server hosts must have the same UNC sharename definitions (see also “Using Windows Hosts” on page 170).

When specifying names to be entered in the global catalog (for example,system-database names, database names, or journal-directory names), youshould not mix UNC share names with other host and path formats. If any suchname is specified as a UNC share name, you must specify all names that way,even if you are running AMS or NFS in addition to Windows Network.

Files on Windows Network data-server hosts are available only to databaseapplications running on Windows client hosts.

WARNING Do not use UNC share names (for example, when creating a federated database)if the resulting files will be accessed by applications running on a UNIX clienthost. You must use AMS or NFS (and the corresponding naming conventions) tomake files available to applications on UNIX client hosts.

Preserving Spaces in Pathnames

Avoid using spaces in the names of files and directories. If you do specify nameswith spaces in them, the names will be double-quoted in the boot file byoonewfd, oochange, and ooinstallfd. For example:

oonewfd -fdfilehost mach33 -fdfilepath"/test dir/test.fdb" -lock mach33 test

results in a boot file entry for the ooFDDBFileName that looks like:

ooFDDBFileName="/test dir/test.fdb"

host The literal string oo_local_host. This string causes the tool or applicationto use the local client host operating system to resolve the path. If youspecify any other string for host, it will be converted to oo_local_hostautomatically.

path The fully qualified network path to the file—that is, a UNC share name for thefile such as \\mach33\c\project\myFD.

DRAFTSpecifying Objectivity/DB Files Filename Case Sensitivity



WARNING When Objectivity/DB reads the boot file, it will ignore spaces in strings that arenot surrounded by double quotes, with unpredictable results.

Filename Case Sensitivity

Objectivity/DB is sensitive to case when verifying filenames for certainoperations. Therefore, when specifying the name of a file to Objectivity/DB, youmust be careful to use the case that was used when the file was created.

You must specify Objectivity/DB files using the original case even on Windows,which otherwise allows you to access files using any case combination. Forexample, Windows allows you to access a file created as HELLO using HELLO,Hello, or hello. However, if this is an Objectivity/DB file, you may only useHELLO.

Setting a Boot File Environment Variable

If you will need to reference the same boot file many times or from many tools,you can specify its path as the value of the OO_FD_BOOT environment variable.You can then run many Objectivity/DB tools without specifying the boot filepath on the command line (some tools, such as ooinstallfd, require an explicitboot file path). You can specify the path as a locally understood path or using thehost format host::path.

Windows

To set the boot file environment variable in Windows, use the set command. Forexample:

set OO_FD_BOOT=c:\john\etc\infoNet

UNIX

To set the boot file environment variable in UNIX, use the appropriate commandfor your shell. For example, in the C shell:

setenv OO_FD_BOOT sys22::/usr/john/etc/infoNet

DRAFTSpecifying Objectivity/DB Files Setting a Boot File Environment Variable



39

<7/21/2003, 12:20 PM; /wrld/mnt09/pubs/working/admin/admFDTasks.fm>

DRAFT

3Federated Database Tasks

A federated database is the highest level in the Objectivity/DB storage hierarchy.It is the unit of administrative control for a “federation” of associated databasesand contains the data model, or schema, that describes all classes of objectsstored in these databases. Administering a federated database involves physicaland logical restructuring, maintenance, and troubleshooting that affects the entireset of associated databases.

This chapter describes:■ Background information about federated databases■ Getting information about a federated database■ Creating, copying, restructuring, and deleting a federated database■ Managing a federated database’s license■ Installing a federated database in a new operating environment■ Exporting and importing a federated database■ Tidying a federated database■ Troubleshooting access and consistency problems■ Getting transaction information■ Referencing objects in a federated database■ Estimating disk space requirements

Tasks that involve changing the number and distribution of databases anddatabase files within a federated database are discussed in Chapter 6, “DatabaseTasks.”

You can write applications to perform many routine federated databaseadministration tasks. See Objectivity’s language-specific programming interfacedocumentation for more information.

DRAFTFederated Database Tasks About Federated Databases



About Federated Databases

Physically, a federated database consists of two files:■ The system-database file. This file stores the schema for the federated

database and contains a global catalog of the member databases and theirlocations.

■ The boot file. This file contains the configuration information used byapplications and tools to locate and open the federated database.

A federated database has a number of properties. Two properties specify thefederated database’s identity:■ Federated-database identifier (sometimes called the reference number)—the

unique positive integer that identifies the federated database to the lockserver.

■ Federated-database system name—the unique name that identifies thefederated database to Objectivity/DB. The system name is the same as theboot file name.

The following properties specify the locations of the Objectivity/DB systemresources associated with the federated database:■ System-database file host and file path—the host system and full directory

path (including the filename) of the federated database’s system-databasefile.

■ Journal-directory host and path—the host system and directory path for thejournal files, which store information for Objectivity/DB to use when rollingback incomplete transactions for all member databases.

■ Lock-server host—the host system on which the lock server for the federateddatabase is running.

■ Boot-file host and path—the host system and directory path for the boot fileof the federated database.

The following property specifies the federated database’s:■ Storage page size—the size (in bytes) of the unit of transfer to and from

memory and across the network for the entire federated database.

The values for these properties are set when a federated database is created. Youcan modify various properties later using Objectivity/DB administration tools toaccommodate system or network changes or to improve applicationperformance; see “Changing Federated-Database Properties” on page 48.

NOTE You cannot change the storage-page size or system name of a federated database.

DRAFTFederated Database Tasks Partitioned Federated Databases



Partitioned Federated Databases

A partitioned federated database is a federated database that has two or moreautonomous partitions. At creation, a federated database is unpartitioned—that is,the federated database itself serves as a single implicit autonomous partition thatcontrols all of its databases. The first time you use Objectivity/HA to create anautonomous partition explicitly, Objectivity/DB adds a second partition to thefederated database, and the initial (original) partition automatically acquires thefederated database’s properties and system resources (system name, identifier,lock-server host, journal directory, system-database file, boot file, and so on).

The tasks in this chapter apply to entire federated databases, regardless of thenumber of partitions. The exception is listing or changing properties, whichaffects only one partition at a time. Most Objectivity/DB tools allow you tospecify a partitioned federated database using the boot file from any partition.

Federated-Database Licensing

Every federated database you create maintains a persistent object that representsyour license for using Objectivity products. The license object in each federateddatabase contains encrypted data summarizing the terms and conditions of yourlicensing agreement—for example, the Objectivity products you are authorizedto use, the usernames of any other authorized users, the platform(s) on whichdevelopment will take place, and so on.

Whenever a tool or database application attempts to open a federated database,the federated database’s license is checked to verify that such access is permitted.If access is denied—for example, because the license has expired or is invalid forthe Objectivity product you are attempting to use—the tool or application willreport an error and terminate.

You initialize a federated database with your current license when the federateddatabase is created. You must update the federated database’s license wheneveryou receive new a license from Objectivity—for example, after purchasing a newproduct or licensing new users. A new license is typically delivered to youelectronically as an encrypted text file. See “Managing a Federated Database’sLicense” on page 49.

DRAFTFederated Database Tasks Getting Federated-Database Information



Getting Federated-Database Information

Objectivity/DB provides various tools that list information about a federateddatabase. As summarized in Table 3-1, these tools provide the current values forsome or all federated-database properties, and are therefore useful for obtainingthe values necessary to run other federated database administration tools.

NOTE Federated-database properties and file information are displayed inObjectivity/Assist; see Objectivity/Assist (page 185).

Listing Current Properties

You use oochange (page 194) with a boot-file name to list the current values offederated-database properties. (HA) You include the -ap option to list theproperties for a specific autonomous partition.

You can also inspect the boot file to view the current values for most properties.However, you must never edit this file directly.

Listing All Associated Files

You use oodumpcatalog (page 223) with a boot-file name to list the fullpathnames of all files associated with a federated database:■ The system-database file■ The boot file■ The journal directory■ All database files■ (HA) All system-database files, boot files, and journal directories of the

autonomous partitions in a partitioned federated database■ (HA) All database image files

In addition, oodumpcatalog lists all identifiers and system names.

Determining the File Type

You use oofile (page 241) with the name of an Objectivity/DB file to determinethe file type and other associated information about that file. When you run thistool with a system-database filename, it lists the file type (federated database)and the properties shown in Table 3-1. This tool also reports the architecture(platform and operating system) on which the file was created and indicates theObjectivity/DB release with which the database format is compatible.

DRAFTFederated Database Tasks Summary of Tools That Display Properties



Summary of Tools That Display Properties

Table 3-1 compares the federated-database or autonomous-partition propertiesthat are displayed by oochange, oodumpcatalog, and oofile.

Creating a Federated Database

To create a federated database, you:

1. Plan how your Objectivity/DB system will be configured around the newfederated database. In particular, you should identify the data-server hosts,client hosts, and lock-server host, and answer the following questions:■ Will your Objectivity/DB system be on a single host or distributed

across multiple hosts?■ In a distributed system, which type of platform (Windows or UNIX) will

you use for each host?■ In a distributed system, what data-server software will you run on each

data-server host?The answers to these questions determine the format you will use to specifyfile locations when you create the federated database. To help you answerthese questions, see “Distributed Objectivity/DB Systems” on page 25 andChapter 12, “Working With Distributed Databases.”

2. Identify the specific locations of system-database file, journal directory, andboot file of the new federated database. These locations can be on the samedata-server host or on different data-server hosts.

Table 3-1: Properties Displayed By Tools

Property oochange oodumpcatalog oofile

Identifier ✓ ✓ ✓

System name ✓ ✓ ✓

File host and path ✓ ✓—

Boot-file host and path ✓ ✓ —

Journal-directory hostand path

✓ ✓ ✓

Lock-server host ✓ ✓ ✓

Page size ✓ — ✓

DRAFTFederated Database Tasks Creating a Federated Database



For best performance, the journal directory should not contain thesystem-database file and should not be the journal directory of any otherfederated database.

3. Decide how you want to identify the new federated database:■ Choose the boot-file name to be used. The simple name of this file will be

used as the federated database’s system name.■ Optionally choose a integer identifier for the federated database.

4. Choose the storage-page size for the new federated database. Normally, youuse the disk’s page size as the storage-page size, although you might want toadjust the storage-page size according to the estimated size of the averageobject to be stored.For information about choosing an optimal page size, see the chapter onperformance in the documentation for your Objectivity programminginterface.

5. Verify that a lock server is running on the intended lock-server host for thenew federated database; start it, if necessary (see “Starting a Lock Server” onpage 93).

6. Verify that your license file is set up; set it up, if necessary (see “Setting Up aLicense File” on page 49).

7. Run oonewfd (page 263) with appropriate options. At a minimum, you mustspecify the system-database file path, the lock-server host, and a boot filename; the other properties have default values. You must specify your licensefile only if it is in a nondefault location.The naming format you use to specify the system-database file (and,optionally, the journal directory) depends on the data-server software youchose in step 1 for the relevant data-server hosts. For complete details, see“Host and Path Formats” on page 34 and Table 12-1 on page 172.

8. For Objectivity/C++ application development, you must explicitly load aschema into the newly created federated database—for example, by runningooddlx (see Objectivity/C++ Data Definition Language) or by importing aschema from another federated database (see “Duplicating a Schema” onpage 166). The schema is loaded automatically for Objectivity for Java andObjectivity/Smalltalk applications.

NOTE On selected platforms, you can use Objectivity/Assist to perform steps 7 and 8(creating a federated database and its schema); see Objectivity/Assist (page 185).

(HA) At creation, a federated database serves as a single implicit autonomouspartition; the first time you create an autonomous partition explicitly,Objectivity/DB adds a second partition to the federated database.

DRAFTFederated Database Tasks Examples



Examples

The following subsections give examples of creating a federated database on aWindows data-server host and on a UNIX data-server host.

Windows

Assume you want to create a federated database on a Windows data-server hostcalled machine33. Because the new federated database is to be accessed byapplications and tools running on Windows and UNIX client hosts, machine33is running AMS as its data-server software. Furthermore, assume that:■ The lock-server host for the new federated database is machine95.■ The journal directory is to be created in the same directory as the

system-database file on machine33.■ The boot file is to be created in the current directory on the host on which

oonewfd is executed.■ The name of the boot file, projectFD, will also be the system name for the

new federated database.■ The chosen federated-database identifier is 10, and the chosen page size is

the default.

Because the system-database file is to be created on a Windows host runningAMS, you must specify the file’s location using the host and path formatdescribed in “Files on AMS Data-Server Hosts” on page 35.

EXAMPLE After the lock server is started on machine95, the oonewfd command is enteredas shown. Because AMS is the data-server software, oonewfd specifies thehostname (machine33) and a fully qualified pathname that is local to that host.

oonewfd -fdfilehost machine33 -fdfilepathc:\project1\data\develop.fdb -lockserverhost machine95-fdnumber 10 projectFD

Now consider a variant of the previous example. Assume you want to create afederated database on machine33 with the same properties as the previousexample, but because all the client hosts are Windows, the chosen data-serversoftware is Windows Network. The decision is made to refer to files using acommon set of UNC share names. Consequently, the command shown belowspecifies the system-database file and the journal directory using the host andpath format described in “Files on Windows Network Data-Server Hosts” onpage 36.

DRAFTFederated Database Tasks Examples



EXAMPLE After the lock server is started on machine95, the oonewfd command is enteredas shown. Because a UNC share name is specified, the hostname can be omitted(the host value is automatically set to the special string oo_local_host, as isrequired for resolving UNC names).

oonewfd -fdfilepath \\project1\data\develop.fdb-lockserverhost machine95 -fdnumber 10 projectFD

UNIX

Assume you want to create a federated database on a UNIX data-server hostcalled machine55. The new federated database will be accessed by applicationsand tools running on Windows and UNIX client hosts, so machine33 is runningAMS as its data-server software. Furthermore:■ The lock-server host for the new federated database is machine95.■ The journal directory is to be created in its own directory on machine33.■ The boot file is to be created in the current directory on the host on which

oonewfd is executed.■ The name of the boot file, projectFD, will also be the system name for the

new federated database.■ The chosen federated-database identifier is 10, and the chosen page size is

4096.

Because the system-database file and the journal directory are to be created on aUNIX host running AMS, the oonewfd command specifies their locations usingthe host and path format described in “Files on AMS Data-Server Hosts” onpage 35.

EXAMPLE After the lock server is started on machine95, the oonewfd command is enteredas shown. Because AMS is the data-server software, oonewfd specifies thehostname (machine55) and fully qualified pathnames that are local to that host.

oonewfd -fdfilehost machine55 -fdfilepath/project1/data/development.FDB -lockserverhost machine95-jnldirhost machine55 -jnldirpath /project1/journalfiles-fdnumber 10 -pagesize 4096 projectFD

The same command could be used if NFS is used as the data-server software,provided that /project1 is the name of an NFS-exported file system.

DRAFTFederated Database Tasks Copying a Federated Database



Copying a Federated Database

You can copy a federated database—for example, to prepare it for end users orfor archiving purposes. To do so, you run oocopyfd (page 213), specifying a newfederated-database identifier that is different from the current identifier, and thepath to the directory that will hold all of the copied files. You can optionallychoose a new federated-database system name and lock-server host.

The copy operation is a convenient way to collect all of a federated database’sfiles into a single directory. The copy is fully operational because its propertiesand global catalog are updated to reflect the new file locations.

(HA) Before using this tool on a partitioned federated database, you must firstdelete the autonomous partitions.

NOTE An alternative way to copy a federated database during development is to useexport and import operations; see “Copying a Development FederatedDatabase” on page 159.

If you only want to move the system-database file from one location to another ina networked file system, without making a copy, it is simpler to use oochange.See “Moving a Federated Database” on page 48.

EXAMPLE The following UNIX command copies a federated database named myFd todirectory /test on host system machine55, sets the federated-databaseidentifier to 4, and changes the federated-database properties to use the new lockserver on host system machine56. After the federated database is copied, thelock server must be started on host system machine56.

oocopyfd -fdnumber 4 -host machine55 -dirpath /test-lockserverhost machine56 myFd

# rlogin to machine56 at this pointoolockserver

DRAFTFederated Database Tasks Changing Federated-Database Properties



Changing Federated-Database Properties

You can use oochange (page 194) to change the following federated-databaseproperties:■ The system-database file host and path (to move the federated database)■ The lock-server host.■ The journal-directory host and path. You must make sure that no other

federated database shares the same journal directory.■ The federated-database identifier.■ The boot file path. The oochange tool does not delete the old boot file. If you

change the boot file location, you should delete the old boot file using theappropriate operating system commands.

You cannot change the storage-page size or system name of a federated database.

WARNING You can change only a fully operational federated database. If necessary, installthe federated database with ooinstallfd (page 249) before changingproperties.

(HA) When a federated database is partitioned, you use oochange (with the -apor -id option) to change the properties of the specified autonomous partition.You cannot change the system name of an autonomous partition.

Moving a Federated Database

When you change the directory or host system of a federated database’ssystem-database file (for example, to accommodate network or systemconfiguration changes), oochange (page 194) registers the move logically (that is,within the federated database’s global catalog), but does not physically move thefile. To move the system-database file physically, you use the appropriateoperating system command. For example, on UNIX you use mv.

EXAMPLE The following commands move the system-database file myFd.FDB to anotherhost system (mach77) and directory (/data2):

oochange -sysfilehost mach77 -sysfilepath /data2/myFd.FDB myFdmv myFd.FDB /net/machine77/data2/myFd.FDB

DRAFTFederated Database Tasks Deleting a Federated Database



The following command changes the lock-server host name to sys10 and thefederated-database identifier to 4 for the federated database named rdFD:

oochange -lockserverhost sys10 -fdnumber 4 rdFD

Deleting a Federated Database

To delete an entire federated database, including all its files, you useoodeletefd (page 218).

Managing a Federated Database’s License

Every federated database is initialized at creation with an Objectivity license thatauthorizes access to it. Whenever your Objectivity license changes—for example,because you have purchased new Objectivity products or upgraded your currentproducts to a new release—you must update the license in each federateddatabase that will be accessed under the new terms.

This section describes various tasks for managing licenses:■ Setting up a license file (see below)■ Updating a federated database’s license (page 50)■ Verifying a federated database’s license (page 51)

For more information about licenses, see “Federated-Database Licensing” onpage 41.

Setting Up a License File

A license file is a text file containing an encrypted Objectivity license. You set up alicense file each time you receive a new encrypted license. Setting up a license filemakes your license available to the Objectivity/DB tools that initialize or updatefederated databases.

To set up a license file for a new Objectivity license:

1. Create a new default license file:a. Check whether a file called oolicense.txt already exists in your

Objectivity/DB installation directory installDir. If so, move orrename that file.

b. Save your new Objectivity license as a text file called oolicense.txt inyour Objectivity/DB installation directory installDir.

DRAFTFederated Database Tasks Updating a Federated Database’s License



Note: If you received your encrypted license by electronic mail, you cansave the attached file from your mail reader, or you can create an emptytext file and paste the license text into it.

2. (UNIX only) If you have a personal Objectivity license that is different from theone shared by your entire installation, create a new personal default license file:a. Check whether your home directory already contains a file called

oolicense.txt; if so, move or replace that file.b. Save your new personal Objectivity license to a text file oolicense.txt

in your home directory.3. Make a backup copy of the new license file in another directory for

safekeeping. A useful convention is to include the license’s identifier in thefilename. (The identifier is included in the electronic mail message or other fileaccompanying the encrypted license.)

The default license files created in steps 1 and 2 enable you to create newfederated databases or update their licenses without explicitly specifying alicense file. (On UNIX, a personal default license file overrides any generaldefault license file in installDir.) If your site conventions require it, you canchoose a nondefault name and location for your license file; you must thenspecify the license file explicitly whenever you create a federated database.

NOTE If you are authorized to use multiple Objectivity products, all authorization iscombined in a single license. Thus, you need to set up only one license file foryour current combination of products (rather than setting up a separate licensefile for each product).

Once a federated database is initialized or updated from a particular license file,the file can be moved or renamed without affecting the license in the federateddatabase. For convenience, the current license file can be copied to multiplelocations.

Updating a Federated Database’s License

Whenever you set up a new license file containing a new encrypted license, youmust explicitly update each federated database that will be accessed under theterms of the new license.

To do so, you use oolicense (page 253) with options specifying the new licensefile and the boot-file name. Updating a license replaces the federated database’sprevious license with the new one. Your old license file is your only backup.

DRAFTFederated Database Tasks Verifying a Federated Database’s License



Verifying a Federated Database’s License

Occasionally, you may need to verify the validity of a particular federateddatabase’s license—for example, to make sure the federated database has themost up-to-date license.

To do so, you use oolicense (page 253) with a boot-file name and no otheroptions to display a federated database’s license in plain (unencrypted) text. Youcan check whether the displayed license’s identifier matches that of your latestlicense.

Installing a Federated Database

Installing a federated database sets it up after its files have been placed in a newoperating environment. You normally install a federated database if you are anend user who has received the files of a deployed production federated database(see “Installing a Federated Database” on page 178) or if you are atechnical-support engineer who has received federated-database files from anend-user for troubleshooting.

The new operating environment may be a host in the original network or in adifferent network. Consequently, the relocated federated database usually needsnew host and path information for its system-database and database files, adifferent journal directory, or possibly a different lock-server host. Indeployment or support scenarios, however, the federated-database files arenormally transferred using network or operating-system commands, whichpreserve the federated database’s original properties and global-cataloginformation. Installing the federated database allows you to adjust the propertiesand global-catalog information in the transferred files to reflect the hosts andpaths of the new operating environment.

To install a federated database in a new operating environment:

1. Place the system-database file and boot file in the desired location.2. Place all database files in a single directory (required by the install operation).3. Run ooinstallfd (page 249), specifying the boot file, lock-server host, and

locations of the system-database file, database-file directory, and journaldirectory. You can optionally change the federated database’s system name,identifier, and license.

4. If desired, distribute the database files to their final locations withoochangedb (page 197).

NOTE Installing a federated database differs from copying it (see page 47) or changingits properties (see page 48), because Objectivity/DB copy and change operations

DRAFTFederated Database Tasks Exporting and Importing a Federated Database



can be performed only on a federated database whose properties and globalcatalog are already consistent with the current operating environment.

(HA) You may not install a partitioned federated database. You must either deletethe autonomous partitions first or specify the tool’s -purgeAps option to removeany partitions from the global catalog.

Exporting and Importing a Federated Database

You can export the contents of an entire federated database to a textual XMLdocument and then import the XML file into another new or existing federateddatabase. For example, during development, you can use export and importoperations to create federated-database copies with different storage-page sizes.

NOTE You can combine various export and import operations to accomplish a varietyof administrative and development tasks. For a complete description of exportand import operations, read Chapter 11, “Exporting and Importing.”

To export the contents of an entire federated database to one or more XML files,you run ooexportfd (page 233), with options specifying the the name of theoutput file and the federated database to be exported.

To import the XML representation of a federated database into another federateddatabase, you run ooimport (page 243) with options specifying the desiredXML file(s) and the destination federated database.

By default, the schema of the imported federated database must be identical to(or a subset of) the schema of the destination federated database, or else thedestination schema must be empty (have no application-defined classes). You canspecify the -addnewclasses option to allow classes to be imported into anonempty destination schema.

(HA) You can export and import a partitioned federated database, optionallyreconfiguring the imported partitions in the destination federated database; see“Configuring Partitions and Replicated Data” on page 165.

DRAFTFederated Database Tasks Tidying a Federated Database



Tidying a Federated Database

Tidying a federated database consolidates data that has become fragmented overtime and removes old container versions.

To tidy a federated database, you use ootidy (page 278). To tidy a specificdatabase in a federated database, you run ootidy with the -db or -id option.

NOTE Tidying “repacks” logical Objectivity/DB pages onto physical disk pages. Youcan also repack objects onto logical Objectivity/DB pages using export andimport operations; see “Data Packing” on page 157.

Knowing when and when not to use ootidy is important. The followingsubsections provide guidelines for using ootidy and the background necessaryto understand these guidelines.

Background

Objectivity/DB does not normally return freed disk space to the file system.Instead, it maintains per-database and per-container free lists. If you delete anobject and there are no other objects on the same logical page, Objectivity/DBplaces the page on the appropriate container’s free list. If you delete a container,Objectivity/DB places the container’s pages on the appropriate database’s freelist.

When you create a persistent object, Objectivity/DB first checks the container’sfree list. If it finds a page there, Objectivity/DB stores the new object on thatpage. If it does not find a page there, Objectivity/DB checks the appropriatedatabase’s free list. If the database’s free list has no pages either, only then doesObjectivity/DB go to the file system to obtain the space required to store theobject.

This algorithm for recycling pages makes creating, deleting, and modifyingobjects much more efficient. An optimally efficient federated database willalways have pages on the free lists of fast-evolving containers and databases.

How ootidy Works

When you tidy a federated database, ootidy tries to obtain an exclusive lock oneach database in the federated database. An exclusive lock prevents all users,even multiple readers, one writer (MROW) readers, from concurrently accessingthat database. If ootidy fails to obtain a lock for a particular database, it skipsthat database and continues on to the next. It does not return to a skippeddatabase for the duration of that tidy operation.

DRAFTFederated Database Tasks Guidelines for Using ootidy



After ootidy obtains an exclusive lock on a particular database in a federateddatabase, it copies the database’s objects one by one to a temporary file. It thendeletes the original file and renames the temporary file, which becomes the newdatabase file. Because ootidy creates temporary files and fills them with objectsfrom the current database before deleting the old files, it requires free disk spaceapproximately equal to the size of the largest database in the federation.

Within each rewritten database file, space for the empty free-list pages iseliminated, and the nonempty logical pages are remapped to blocks ofcontiguous disk pages, wherever possible. (Thus, tidying is more effective afteryou have used an operating-system utility to defragment the disk.)

Guidelines for Using ootidy

In general, you should use ootidy in the following cases:■ Before distributing a copy of a federated database to an end user. ootidy

minimizes the disk space required to store the federated database.■ Following a massive update—for example, if you have just deleted a large

portion of a container and do not plan to enlarge the container in the nearfuture. If you do not use ootidy on the container’s database, the pages willsit unused on the container’s free list.

■ On a periodic basis if space is at a premium.

Warning: You should not use ootidy in the following cases:■ While any other process is accessing the federated database, because

database corruption could occur. One way to guarantee that no otherprocesses can access the database is to kill the lock server and to run ootidyin standalone mode.You should especially avoid running ootidy during a backup becauseootidy might delete objects that oobackup references.

■ If you suspect that the federated database has been corrupted. In those cases,ootidy can make the problem significantly worse.

Troubleshooting

Checking Access Problems

If an Objectivity/DB tool or application cannot access a federated database, firstverify that these conditions are true.■ The federated database boot file is readable at the pathname specified or

through the OO_FD_BOOT environment variable.

DRAFTFederated Database Tasks Checking Consistency Problems



■ A lock server is running on the specified host system and is compatible withthe system-database file (unless the tool is running in standalone mode,which does not require a lock server).

■ The system-database file specified in the boot file is visible on the network.■ The journal directory is visible on the network.■ The federated database identifier is correct.■ Appropriate access permissions (page 33) are set.■ The federated database’s license (page 51) is valid for the accessing tool or

application.

If these conditions are all true, it is likely that a tool or application failed torelease a lock on the federated database. To locate unexpected locks, you useoolockmon (page 258). To release them and roll back the transactions thatstarted them, you then use oocleanup (page 206). For more about cleanup andrecovery, see also “Performing Manual Recovery” on page 143.

Checking Consistency Problems

You can check the consistency of an entire federated database or its componentsby using oocheck (page 201). You can specify the -outfile option to save thegenerated report to a file. If problems with particular objects are found, you canspecify the -xml option to export those objects to an XML document.

By default, the entire storage hierarchy is checked, including all basic objects andtheir relationships (associations), on all logical pages, in all containers, in alldatabases. To check a specific portion of the federated database’s storagehierarchy, you can:■ Include the -id, -db, or -ap option to select one or more branches of the

federated database’s storage hierarchy for oocheck to traverse.■ Include the -fd, -databases, -containers, -pages, -objects, or

-relationships option to indicate how far oocheck is to traverse alongthe selected branch(es). Checking starts at the federated-database level andproceeds to the specified level. (For details about what gets checked, see thedescriptions of these options in the reference for oocheck.)

EXAMPLE The following sample commands check some or all of the storage hierarchy in afederated database called myFD. Output is directed to stdout.

The following sample command implicitly selects all databases and allowschecking at all levels. Consequently, the relevant checks are performed for thefederated database and for every database, container, and logical page, basicobject, and relationship in it.

oocheck myFD

DRAFTFederated Database Tasks Getting Transaction Information



The following sample command selects the database myDB (and its contents) andallows checking at all levels. Consequently, the relevant checks are performed forthe federated database, for myDB, and for all of the containers, logical pages, basicobjects, and relationships in myDB.

oocheck -db myDB myFD

The following sample command selects the database myDB (and its contents) andlimits checking to just the container level. Consequently, the relevant checks areperformed for the federated database, for the database myDB, and for all of myDB’scontainers, but not for the logical pages, basic objects, or relationships in thosecontainers.

oocheck -db myDB -containers myFD

The following sample command selects the container Archive in the databasemyDB, and limits checking to the container level. Consequently, the relevantchecks are performed for the federated database, for the database myDB, and forArchive, but not for the logical pages, basic objects, or relationships in Archive.

oocheck -db myDB -cont Archive -containers myFD

The following sample command selects the branch of the storage hierarchycontaining the basic object with the object identifer 78-4-670-7, and allowschecking at all levels. Consequently, the relevant checks are performed for thebasic object and its relationships, and for the logical page, container, database,and federated database containing the basic object.

oocheck -id 78-4-670-7 myFD

See “Referencing Objects in a Federated Database” on page 57 for informationabout object identifiers.

You can also check structures other than those in the storage hierarchy:■ To check the federated database’s schema, you specify the -schema option.■ To check a particular journal file, you specify the -jnl option.

Getting Transaction Information

You can list all active transactions that have locks on data in a federateddatabase. To do so, you use oocleanup (page 206) with only the bootFilePathargument.

DRAFTFederated Database Tasks Referencing Objects in a Federated Database



You can use oolistwait (page 254) to list transactions that are waiting on anylockable Objectivity/DB object (federated database, database, or container). Thistool also finds out whether a specified transaction is waiting for a lockable object,and if so, which transactions currently hold the lock on that object. Table 3-2summarizes the options for filtering oolistwait information.

NOTE The oolistwait tool lists transactions in the order in which they are retrieved,not in the order in which they will run (that is, not in a sequenced queue).

Referencing Objects in a Federated Database

Every object in a federated database can be referenced through a uniqueidentifier that distinguishes it from other objects of the same type. A federateddatabase’s identifier (sometimes called a reference number) distinguishes it fromthe other federated databases using the same lock server; a database’s identifierdistinguishes it from the other databases in the same federated database; acontainer’s identifier distinguishes it from the other containers in the samedatabase; and so on.

For most types of Objectivity/DB objects, the identifier is a single integer thatserves as a key for locating each object relative to the storage object that containsit. For example, within a federated database’s global catalog, each databaseidentifier is mapped to a particular database file; within a database’s catalog ofcontainers, each container identifier is mapped to a particular container withinthe database file.

The identifier of a basic object, called an object identifier or OID, contains enoughinformation to distinguish it from every other basic object within the entire

Table 3-2: Listing Transactions Using oolistwait

To See Use This Option

All waiting transactions (no options)

Waiting transactions started on a specific host system -host

Waiting transactions started by a specific user -user

Waiting transactions started by a specific user on a specific hostsystem

-host and -user

A specific transaction’s status, and any transactions that areusing resources that it needs

-transaction

DRAFTFederated Database Tasks Referencing Objects in a Federated Database



federated database, not just within the object’s container. An object identifier is64 bits long and is composed of four 16-bit fields in the following string format:

D-C-P-S

where

For example, 78-112-8-3 identifies the basic object stored in slot 3 of page 8 incontainer 112 of the database whose identifier is 78. Objectivity/DB identifiesobjects using object identifiers instead of memory addresses because objectidentifiers provide interoperability across platforms, access to more objects thandirect memory addresses permit, and runtime access to objects located anywherein a network.

For uniformity, integer identifiers can be expressed in the D-C-P-S string format(that is, as a four-part object identifier):■ A database identifier D can be expressed as D-0-0-0. For example, the

database identifier 78 can be expressed as 78-0-0-0.■ A container identifier C within a database D is expressed as D-C-P-1, where

the page number P is 1 or a low integer.

NOTE The identifier of a federated database or an autonomous partition is normallyexpressed as an integer, not a four-part object identifier.

Object identifiers are reported in some errors to identify particular objects. If abasic object is moved, its object identifier changes; if a basic object is moved ordeleted, its (old) object identifier will be reused for any new basic objectsubsequently created in the same location. Similarly, the integer identifiers ofpreviously deleted databases, partitions or containers will be reused as needed.

D Database identifier.

C Container identifier.

P Logical page number in the container. A logical page is a storage page containingone or more small objects or the header information for a large object.

S Slot number on the page. A slot is the portion of a storage page occupied by a singlesmall object or the header information for a large object.

DRAFTFederated Database Tasks Estimating Disk Space Requirements



Estimating Disk Space Requirements

The following subsections describe how to estimate the initial and maximumdisk space requirements for an Objectivity/DB federated database.

Estimating Initial Requirements

Objectivity/DB requires a certain amount of overhead disk space in addition tothe disk space required by actual objects. Use the following formulas to estimatethe initial amount of disk space required (before objects are created):

diskSpace ≈ fdOverhead + (numberOfDbs * dbOverhead)

where

dbOverhead ≈ numberOfConts * initPages

where

Estimating Maximum Federated Database Size

You can use the information in the following subsections to estimate themaximum size (in bytes) of a fully populated federated database and theapproximate number of accessible objects it contains. The subsections describe:■ Values used in size estimates■ Formula for estimating database file size■ Formula for estimating required disk space■ Formula for estimating number of objects

Values Used in Size Estimates

Table 3-3 lists various values you will need for estimating federated-databasesize. Several of these values—the maximum number of databases, containers,and pages—are determined by the field sizes in an object identifier. Each 16-bitfield can have up to 216 values. This field size determines the addressing

fdOverhead Approximately 100 kilobytes to 1 megabyte.

numberOfDbs Number of databases in the federated database.

numberOfConts Number of containers in a database.

initPages Initial number of pages allocated for a container (see thelanguage-specific documentation for information about creatingcontainers).

DRAFTFederated Database Tasks Estimating Maximum Federated Database Size



capability at each level of the storage hierarchy; some of these addresses arereserved for Objectivity/DB overhead.

Table 3-3: Values Required for Calculating Federated Database Size

Item Value

Maximum number of databases ina federated database

216 – 1 databases (65,535 databases).

Maximum number of containers ina database

215 – 1 containers (32,767 containers).As containers get large, the number of containers is limited by themaximum database file size (in bytes), divided by the averagecontainer size:(db size) / (average pages per cont x page size).

Objectivity/DB reserves the high-order bit for overhead. WhenObjectivity for Java or Objectivity/Smalltalk applications createpersistent objects, an additional container is reserved for the rootscontainer.

Maximum number of logical pagesin a container

216 – 1 logical pages (65,535 logical pages).A logical page is a storage page containing one or more smallobjects or the header information for a large object.

Minimum number of logical pagesin a container

2 pages per container and4 pages of overhead per hashed container.

Maximum page size 216 bytes (65,536 bytes).

Minimum page size 512 bytes.

Average number of objects (slots)per logical page

(Page size - 32) / (Average object size + 14).Objectivity/DB reserves 32 bytes per page and 14 bytes per objectfor overhead. The available space for objects on a page is thuspage size - 32 and the average slot size is average object size + 14.The larger the objects, the fewer slots per page.




Formula for Estimating Maximum Database-File Size

The following formula calculates the size limit on a database file in terms of theaddressing capability of object identifiers. This estimate uses the maximum pagesize (216 bytes).

Maximum number of bytes in a database file ≈215 cont/db X 216 page/cont X 216 bytes/page ≈247 bytes/db

This formula takes into account only the logical pages in a database (the pagescontaining small objects and the header information for large objects). Databasescontaining large objects could be significantly larger due to the additional storagepages for large-object data.

NOTE Smaller files may be preferable (for effective file management) or even necessary(due to limitations of physical media capacity).

Formula for Estimating Maximum Overall Size

The following formula expresses the approximate maximum number of bytes ina federated database. This estimate uses the maximum page size (216 bytes) andthe estimate for database size given in the previous section.

Maximum number of bytes ≈216 db/fd X 247 bytes/db ≈263 (or approximately 1019) bytes/fd

Formula for Estimating Number of Objects

The following formula expresses the approximate number of accessible objects ina fully populated federated database. In this estimate, N represents the averagenumber of objects per logical page, which is calculated as shown in Table 3-3.

Number of objects ≈216 db/fd X 215 cont/db X 216 pages/cont X N objects/page ≈(247x N) objects/fd

This formula does not take into account the space used for container overhead,which varies depending on how full the container is.




63

<6/11/2003, 12:40 PM; /wrld/mnt09/pubs/working/admin/admNativeBrowser.fm>

DRAFT

4Browsing Objects and Types

Objectivity/DB provides a tool for browsing objects and types in a federateddatabase. You can also use this tool to make queries for objects in a federateddatabase.

This chapter describes:■ Information you can browse■ How to use the Objectivity/DB browser tool (oobrowse) on Windows■ How to use the Objectivity/DB browser tool from the Tool Manager

(ootoolmgr) on UNIX

NOTE If Objectivity/Assist is supported on your platform, you should use it to browsea federated database instead of using the tools in this chapter. SeeObjectivity/Assist (page 185).

DRAFTBrowsing Objects and Types Information You Can Browse



Information You Can Browse

The Objectivity/DB browser tool provides three browsers—a data browser, atype browser, and a query browser.

Data Browser

Using the data browser, you can view objects in a federated database.

Figure 4-1 Objectivity/DB Data Browser

DatabaseRegion

ContainerRegion

ObjectRegion

AssociationButtonScope

Button

ObjectContentRegion

DRAFTBrowsing Objects and Types Type Browser



Type Browser

Using the type browser, you can view class definitions in a federated databaseschema.

Figure 4-2 Objectivity/DB Type Browser

TypesRegion Derived Types

Region

Type ContentRegion

TypeButtons

DRAFTBrowsing Objects and Types Query Browser



Query Browser

Using the query browser, you can perform ad hoc queries for objects in afederated database. When making queries, you can use regular expressionssupported by the Objectivity/DB predicate query language. For informationabout using the predicate query language in a particular programming interface,see the documentation for that interface.

Figure 4-3 Objectivity/DB Query Browser

QueryRegion

Query ResultRegion

ObjectSelectRegion

DRAFTBrowsing Objects and Types Opening Browsers on Windows



Opening Browsers on Windows

The Objectivity/DB browser tool on Windows platforms is oobrowse(page 193).

Starting and Using oobrowse

To start a browser on Windows:

1. Run oobrowse from a command prompt.2. From the main browser panel, open a data browser on a specific federated

database. To do this, choose Open from the File menu and select a boot file.3. Choose what the data browser displays by selecting from the Options menu:

4. If desired, start a type browser by choosing Types from the View menu.5. Choose what the type browser displays by selecting from the Options menu:

6. If desired, start a query browser:a. Visit the data browser by choosing FD from the View menu.b. Click Query.

Quitting oobrowse

To quit from oobrowse, choose Exit from the File menu.

Types Information Type names of displayed objects

System-defined Fields Attributes defined by Objectivity/DB

User-defined Fields User-defined attributes

Inherited Fields Attributes inherited from other classes

Empty Fields Attributes containing no values

Object Names (not IDs) Names or identifiers of displayed objects

System-defined Fields Attributes defined by Objectivity/DB

User-defined Fields User-defined attributes

Inherited Fields Attributes inherited from other classes

Persistent Types Persistence-capable classes

Non-persistent Types Non-persistence-capable classes

DRAFTBrowsing Objects and Types Opening Browsers on UNIX



Opening Browsers on UNIX

The Objectivity/DB browser tool on UNIX platforms is ootoolmgr.

Starting and Using ootoolmgr

To start a browser on UNIX:

1. Start a Tool Manager by executing the ootoolmgr command:ootoolmgr [bootFilePath]

where

2. If you omitted the boot file path in step 1 and the OO_FD_BOOT environmentvariable is not set, open a specific federated database by choosing OpenFDfrom the File menu.

3. Start the desired browser:■ To open a data browser, choose Browse FD from the Tools menu.■ To open a type browser, choose Browse Types from the Tools menu.■ To open a query browser, open a data browser and then use the Search

menu or click Query.

Quitting ootoolmgr

To quit from ootoolmgr, choose Exit from the File menu of the Tool Manager.

bootFilePath Path to the boot file of the federated database. You can omit thisparameter if you set the OO_FD_BOOT environment variable tothe correct path.

69

<6/11/2003, 12:40 PM; /wrld/mnt09/pubs/working/admin/admFDdebugTasks.fm>

DRAFT

5Debugging a Federated Database

When a database application produces incorrect results, you can inspect theobjects in a federated database and change various aspects of their structure andcontents.

This chapter provides information about:■ Inspecting and editing a federated database (all platforms)■ Inspecting and editing a federated database from within a C++ debugger

(UNIX only)■ Viewing objects in a federated database from within a C++ debugger

(Windows and UNIX)

If you just want to view objects in a federated database without modifying them,you should use the Objectivity/DB browser tool for your platform (seeChapter 4, “Browsing Objects and Types”).

Inspecting and Editing a Federated Database

You use the oodebug (page 216) tool on any platform to inspect and edit afederated database. The oodebug tool provides a set of commands forperforming limited transactions on a federated database. You use thesecommands in one of two modes:■ In read mode, you can use the oodebug commands for printing an object’s

contents and iterating through an object’s relationships (associations).■ In update mode, you can use the full set of oodebug commands to create or

delete objects, change values in object attributes, form or drop relationships(associations) between objects, and so on.

WARNING Update mode is dangerous—use it with care. Update operations do not have thebuilt-in safeguards that your programming language provides. For example,oodebug commands for changing attribute values can access private data

DRAFTDebugging a Federated Database Starting oodebug as a Separate Process



directly, without going through access methods. Furthermore, oodebugcommands for creating and deleting objects do not call object constructors anddestructors; you must perform equivalent operations explicitly using appropriateoodebug commands.

Starting oodebug as a Separate Process

You can start oodebug as a separate process on any platform and use it tointeract with a federated database that is not currently locked by otherapplications. Starting oodebug opens the specified federated database in readmode and initiates a transaction.

To start oodebug from a command line:

➤ Enter the following command:oodebug bootFilePath

where

Changing oodebug Modes

The oodebug tool starts in read mode, which is indicated by the (read)command-line prompt. Read mode lets you safely view the structure andcontents of a federated database without being able to edit it. In read mode, youare restricted to a subset of the oodebug commands.

If you want to edit a federated database, you can turn on update mode, whichchanges the oodebug command-line prompt to (update). Update mode allowsyou to perform all oodebug commands, including commands to change thestructure and contents of a federated database.

NOTE Update mode is intended for use by database administrators and advanced usersonly.

You can switch between modes at any time while oodebug is running:■ To switch from read mode to update mode, you specify update at the

oodebug command line.■ To switch from update mode to read mode, you specify read at the oodebug

command line.

bootFilePath Path to the boot file of the federated database. You can omit thisparameter if you set the OO_FD_BOOT environment variable to thecorrect path. (HA) You can specify any autonomous partition bootfile.

DRAFTDebugging a Federated Database Performing Transactions With oodebug



Performing Transactions With oodebug

When you start oodebug as a separate process, you can start, commit, or abortdatabase transactions. Each transaction can comprise a single oodebug commandor a series of logically related commands. When you enter a command thatchanges the structure or contents of the federated database, oodebug displayssubsequent command prompts with a leading asterisk—for example, (*read) or(*update).

A new transaction is started whenever you start oodebug as a separate processand enter either the commit command or the abort command.

When you enter the commit command, oodebug:■ Ends the current transaction.■ Makes the transaction’s changes permanent in the federated database.■ Frees any locks.■ Starts a new transaction.■ Displays subsequent command prompts without a leading asterisk (*).

When you enter the abort command, oodebug:■ Ends the current transaction.■ Cancels any changes and maintains the structure and contents of the

federated database in its state prior to the beginning of the currenttransaction.

■ Frees any locks.■ Starts a new transaction.■ Displays subsequent command prompts without a leading asterisk (*).

Terminating oodebug

To terminate oodebug:

➤ Enter the following command:quit

Terminating oodebug closes the federated database, and if no changes arepending, aborts the transaction that you started when you invoked oodebug orissued a previous commit or abort command.

If, however, changes are pending in the oodebug transaction, you must explicitlysave or ignore these changes with the commit or abort commands. Pendingchanges are indicated by an asterisk in your command prompt: (*read) or(*update).

If you enter quit without explicitly saving or ignoring changes, oodebugdisplays an error message.

DRAFTDebugging a Federated Database Running oodebug in a C++ Debugger



EXAMPLE This example shows how to terminate oodebug if changes are pending.

(*update) quitpending updates, please commit or abort(*update) committransaction committed(update) quit%

Running oodebug in a C++ Debugger

On UNIX, you can run oodebug from your operating system’s or compiler’s C++debugger (dbx and dbx variants). This allows you to view and alter a federateddatabase while you are debugging a running C++ application, even if thefederated database is locked by that application.

When you start oodebug from a debugger, you specify the handle of a persistentobject that you want to view or change. Consequently, you must start oodebugafter your application has started a transaction.

Once you start oodebug, the debugger’s commands are not available until youterminate oodebug. While oodebug is running, its prompt replaces thedebugger’s prompt. oodebug is started in read mode.

You run oodebug from dbx using the oodebug convenience function. To do this:

1. Link your application with the debug-compatible Objectivity/DB libraryliboo_dbx.a. For more information on linking, see the Installation andPlatform Notes for UNIX.

2. Define the oodebug convenience function to dbx using either of the followingmethods:■ In your .dbxinit file, include the Objectivity/DB debugger convenience

functions that are provided in installDir/arch/etc/oo.dbxinit.■ From the dbx command line, enter the source command to load the

convenience functions from installDir/arch/etc/oo.dbxinit,where

installDir Installation directory for Objectivity/DB

arch Subdirectory for your architecture

DRAFTDebugging a Federated Database Terminating oodebug Within a Debugger



3. In the debugger, run your application until it starts the desired transaction.4. Run oodebug by entering:

oodebug ref_or_handle

where

Terminating oodebug Within a Debugger

To terminate oodebug:

➤ Enter the following command:quit

Quitting oodebug returns you to the debugger.

Using ooprint in a C++ Debugger

On Windows and UNIX, you can use the ooprint (page 291) conveniencefunction to view the contents of a persistent object while you are debugging aC++ database application.

You can run ooprint from the debugger without having to start the oodebug(page 216) tool (ooprint is functionally equivalent to oodebug’s printcommand). The contents are displayed in the format shown by theObjectivity/DB data browser (page 64). When you start ooprint from adebugger, you specify the handle of a persistent object that you want to view.Consequently, you must start ooprint after your application has started atransaction.

Windows

To use the ooprint convenience function to view a persistent object whiledebugging a process with the Microsoft Visual C++ debugger:

1. Link your application with the appropriate debug-compatibleObjectivity/DB library. For more information on linking, see the Installationand Platform Notes for Windows.

2. In the debugger, run your application until it starts the desired transaction.

ref_or_handle Object reference or handle within the program you aredebugging that identifies the object you want to view or change.ref_or_handle indicates the name of an active variable ofthe class ooRef(className) or ooHandle(className).

DRAFTDebugging a Federated Database Using ooprint in a C++ Debugger



3. Invoke ooprint:a. Select View > Output to display the debugger output window.b. Select Debug > QuickWatch.c. In the Expression field, enter the following and click OK:

ooprint(&ref_or_handle)

where

The debugger output window displays the object that is referenced by thehandle variable.

UNIX

To use ooprint to view a persistent object while debugging a process with dbx:

1. Link your application with the debug-compatible Objectivity/DB libraryliboo_dbx.a. For more information on linking, see the Installation andPlatform Notes for UNIX.

2. Define the ooprint convenience function to dbx using either of the followingmethods:■ In your .dbxinit file, include the Objectivity/DB debugger convenience

functions that are provided in installDir/arch/etc/oo.dbxinit.■ From the dbx command line, enter the source command to load the

convenience functions from installDir/arch/etc/oo.dbxinit,

where

3. Invoke ooprint by entering:ooprint ref_or_handle

where

ref_or_handle Object reference or handle within the program you aredebugging that identifies the object you want to view.ref_or_handle indicates the name of an active variable ofthe class ooRef(className) or ooHandle(className).

installDir Installation directory for Objectivity/DB

arch Subdirectory for your architecture

ref_or_handle Object reference or handle within the program you aredebugging that identifies the object you want to view.ref_or_handle indicates the name of an active variable ofthe class ooRef(className) or ooHandle(className).

75

<6/11/2003, 12:40 PM; /wrld/mnt09/pubs/working/admin/admDBTasks.fm>

DRAFT

6Database Tasks

A database is the second highest level in the Objectivity/DB logical storagehierarchy, existing as a component of a federated database. Databases arelogically and physically where persistent data is actually stored. Because eachdatabase is physically a separate file, you can use databases to distribute dataacross your network. Administering a database mainly involves updating itsstorage characteristics to help you better utilize your disk and network resources.

This chapter describes:■ General information about databases■ Getting information about a database■ Creating a database■ Relocating a database file■ Copying a database file and attaching it to a federated database■ Changing database properties■ Deleting a database■ Setting access permissions on a database file■ Tidying a database■ Troubleshooting access problems

You can write applications to perform many routine administration tasks fordatabases. See Objectivity’s language-specific programming interfacedocumentation for more information.

DRAFTDatabase Tasks About Databases



About Databases

Like a federated database, a database has properties that specify its variousphysical and logical characteristics. Physically, a database is a file; the propertiesdescribing its physical location are:■ File host—the host machine on which the database file resides■ File path—the database file’s pathname and filename

Logically, a database has an identity within a federated database; the propertiesdescribing its identity are:■ Containing federated database—the federated database to which the

database is attached and that serves as the point of administration for thisdatabase

■ Database identifier—the unique integer identifier within the scope of thecontaining federated database

■ System name—the unique logical name of the database within the scope ofthe containing federated database

A database also has the following properties that identify:■ Whether a database is read-only or read-write (page 77)■ (HA) The controlling autonomous partition

Databases are normally created programmatically, so a database’s properties areusually set by the application that creates it. You can change any property,including the database identifier, using various Objectivity/DB administrationtools. See “Changing Database Properties” on page 85.

Database Identifier Formats

Many administration tools allow you to use a database identifier to specify adatabase. You find out a database’s identifier by listing file or propertyinformation for the database; see “Getting Database Information” on page 78.

A database identifier is usually a single, nonnegative integer—for example, 5.Sometimes, you will see database identifiers represented as object identifierswritten in D-C-P-S format. For example, a database identifier of 5 is equivalent toan object identifier of 5-0-0-0. You can use either format when specifying adatabase to a tool.

DRAFTDatabase Tasks Read-Only and Read-Write Databases



Read-Only and Read-Write Databases

A database is either read-only or read-write. At creation, every database isread-write, so that persistent objects can be created in it. At any time, a databasecan be changed to read-only, so that it can be opened only for read; any attemptto open the database for update will fail as if there were a lock conflict. Forexample, a database that contains only archival information could be maderead-only. Making a database read-only can improve the performance of anapplication that performs many read operations in the database; the applicationcan grant read locks and refuse update locks on containers in the databasewithout having to consult the lock server every time such containers are opened.

When a database is read-only, it can either be read or changed back to read-write.The database must be changed back to read-write before any other operationscan be performed on it. You toggle a database between read-only and read-writeby changing its properties; see “Changing Database Properties” on page 85.

Any number of databases can be read-only in a federated database. When amultiple read-only databases exist in a federated database, they are locked orunlocked as a group. Consequently, no read-only database can be changed backto read-write while any read-only database is being read by a tool or application.

Replicated Databases

You can use Objectivity/HA to replicate a database so that different images ofthe same database belong to different autonomous partitions. Physically, eachimage is a different database file. Logically, all images of a database share thesame database identifier and system name. Each image is controlled by adifferent partition.

Each image of a replicated database has an additional property specifying itsweight. The weights of images are used in quorum calculations for the database. Ingeneral, tasks affecting database images require that a representative subset, orquorum, of the database’s images be accessible. (An individual image is accessibleto a tool or application if that tool or application can access not only the image’sfile, but also the system-database file, lock server, and journal directory of thepartition controlling the image.)

The tasks in this chapter apply to entire databases, regardless of the number ofimages. The exception is listing or changing properties, which affects only onedatabase image at a time. A database is normally specified by its identifier orsystem name; a database image is normally specified by the identifier or systemname of the database, in combination with the system name of the controllingautonomous partition. If a database has multiple images, all images are eitherread-only or read-write. While a database is read-only, you cannot add, delete, orchange the properties of individual images.

Replicated databases are completely described in Objectivity/DB High Availability.

DRAFTDatabase Tasks Getting Database Information



Getting Database Information

You can use Objectivity/DB tools to obtain information about databases:■ To list a database’s current properties, you run oochangedb (page 197) with

the -db (or -id) and bootFilePath options. (HA) To list the properties of adatabase image, you must also specify the -ap option.

■ To list information about a particular database file, you run oofile(page 241) followed by the name of the file.

■ (HA) To obtain information about database images, weights, andtie-breakers, you run oodumpcatalog (page 223) followed by the boot-filename for any autonomous partition.

The following subsections describe how to find specific information about adatabase.

Getting a System Name or Database Identifier

A number of tools request a system name or database identifier:■ If you know only the name of a database file, you can use oofile to find the

database’s system name or identifier.■ If you know either the system name or database identifier, you can use

oochangedb to find the other property.

Getting a Database’s File Host and Path

A number of tools request a database file host or path:■ If you know the database system name or identifier, you can use

oochangedb to find the file host and path.

Getting a Database’s Page Size

For some tasks, you may need to find the size of the storage pages in a database.To do this:

1. Find the database’s file path.2. Using the database’s file path, run oofile to display the storage-page size.

Getting a List of Read-Only Databases

You can find out which databases are currently read-only or read-write byinvoking oodumpcatalog (page 223).

DRAFTDatabase Tasks Creating a Database



Creating a Database

You can use oonewdb (page 261) to create an empty database within a specifiedfederated database. Using a tool to create a database is an alternative to creatingdatabases from within an application, which is the normal practice. You mustspecify the new database’s file location and system name.

The host and path format you use when specifying the file location depends onthe type of host machine (Windows or UNIX) on which the new database iscreated, and the data-server software you are running on that host. For completedetails, see “Host and Path Formats” on page 34 and Table 12-1 on page 172.

EXAMPLE The command in each of the following examples creates the partsDb database ofthe federated database myFD.

Windows

The database file partsDb is called parts.DB and is placed in the folderc:\project1\data on the Windows host that executed the oonewdb tool. Thishost is running AMS, so the command uses a fully qualified pathname that islocal to that host.

oonewdb -db partsDb -filepath c:\project1\data\parts.DB myFD

UNIX

The database file partsDb is called parts.DB and is placed in the directory/project1/data on the UNIX host system machine33, which is running NFS:

oonewdb -db partsDb -host machine33-filepath /project1/data/parts.DB myFD

When you use oonewdb, you may optionally specify an identifier for the newdatabase, for a reason such as the following:■ Application development is split across several teams, and each team by

convention must assign database identifiers from within a certain range.■ You are recreating an existing federated database, and you need to make

sure that the database with a given system name has the same identifier inboth the original federated database and the new one.

(HA) The oonewdb tool creates only the initial database image; you useoonewdbimage to create each additional image (see Objectivity/DB HighAvailability).

You can create multiple empty databases by copying the database structure ofanother federated database; see “Duplicating Database Structure” on page 162.

DRAFTDatabase Tasks Moving a Database File



Moving a Database File

You can move a database file from one location to another in a networked filesystem—for example, to take advantage of the disk space on a new host machine.To do this, you run oochangedb (page 197) with options specifying the new hostand file path. This operation updates the global catalog and physically relocatesthe file, but makes no change to the database’s identity properties—that is, thedatabase keeps the same identifier and system name, and remains within thesame federated database.

EXAMPLE The command in each of the following examples moves the partsDb database ofthe federated database myFD.

Windows

The following command moves the file for the database partsDb to the local filec:\project2\data\parts.DB:

oochangedb -db partsDb -filepath c:\project2\data\parts.DB myFD

UNIX

The following command moves the file for the database partsDb to the file/project2/data/parts.DB on the host system sys12:

oochangedb -db partsDb -host sys12-filepath /project2/data/parts.DB myFD

If you want to update the global catalog without physically moving the file, yourun oochangedb with the -catalogonly option.

If the database you want to move is read-only, you must change it back toread-write before you can move it.

Copying a Database File

You can create a copy of a database file using oocopydb (page 211). Thisoperation copies the contents of the specified database into a new file, preservingthe same database identifier and system name. The resulting copy does notbelong to any federated database, so the copy cannot be used until you attach itto a federated database (page 81). The original database is not affected by theoperation.

DRAFTDatabase Tasks Attaching a Database to a Federated Database



(HA) Copying a database creates only a single copy, regardless of the number ofdatabase images. The resulting copy cannot be reattached as a database image.

The oocopydb tool locks the database to be copied, providing a safe alternativeto copying database files directly using operating system commands. Theoriginal database is inaccessible during the execution of oocopydb.

By default, the copy operation fails if objects within the database to be copiedhave relationships or associations to objects in another database. To copy adatabase with external relationships or associations, you specify the -externaloption.

EXAMPLE The command in each of the following examples copies the partsDb database ofthe federated database myFD. The unattached copy is stored in the stdparts.DBfile in the specified location on the host that executed the oocopydb tool.

Windowsoocopydb -db partsDb -filepath c:\project2\data\stdparts.DBmyFD

UNIXoocopydb -db partsDb -filepath /project2/data/stdparts.DB myFD

Attaching a Database to a Federated Database

When you copy a database using oocopydb (page 211), the resulting copy doesnot belong to any federated database. To attach the copy to a federated database,you use ooattachdb (page 186). Thus, you can combine oocopydb andooattachdb to:■ Move (or copy) a database to another federated database.■ Duplicate a database within a federated database.■ Change the system name or identifier of a database.

You can use ooattachdb to attach a group of databases to another federateddatabase.

Moving a Database Between Federated Databases

You can move a database from one federated database to another, subject to the“Guidelines for Attaching a Database” on page 83. To move a database:

1. Run oocopydb to create a copy of the database to be moved (page 80).2. (Optional) Run oodeletedb to delete the original database (page 86).

DRAFTDatabase Tasks Duplicating a Database Within a Federated Database



3. Run ooattachdb to attach the database copy to the destination federateddatabase. Note that:■ You can use the -db and -id options to specify a new a system name

and database identifier; see “Consequences of Changing a DatabaseIdentifier” on page 83. Omitting these options preserves the originalsystem name and database identifier.

■ You can specify the -readonly option to make the attached databaseread-only. By default, the database is attached as a read-write database.

4. (HA) Recreate database images as desired in the destination federateddatabase.

EXAMPLE The commands in the following examples:

■ Copy the partsDb database into a new file (stdparts.DB) in the specifiedlocation.

■ Delete the original database partsDb from the federated database myFD.■ Attach the copied database with the system name stdParts and a database

identifier of 15 to the destination federated database newFD.

Windowsoocopydb -db partsDb -host machine5

-filepath c:\project2\data\stdparts.DB myFDoodeletedb -db partsDb myFDooattachdb -db stdParts -id 15 -host machine5

-filepath c:\project2\data\stdparts.DB newFD

UNIXoocopydb -db partsDb -host machine33

-filepath /project2/data/stdparts.DB myFDoodeletedb -db partsDb myFDooattachdb -db stdParts -id 15 -host machine33

-filepath /project2/data/stdparts.DB newFD

Duplicating a Database Within a Federated Database

You can duplicate a database within the same federated database. To do this, youfollow the steps for moving a database, except that you attach the copy to thesame federated database. You must attach the copy with a different databaseidentifier and system name from the original database (see “Consequences ofChanging a Database Identifier” on page 83).

DRAFTDatabase Tasks Guidelines for Attaching a Database



(HA) Duplicating a database results in a database copy that can be updatedindependently from the original. In contrast, when a database is replicated,updates are propagated across its images to keep them identical.

Guidelines for Attaching a Database

You can execute ooattachdb successfully only if the following are all true:■ The database file exists in the specified location and is recognizable as an

Objectivity/DB database file. To check whether this condition holds, you canuse oofile (page 241).

■ No database with the specified system name, database identifier, or databasefilename already exists in the destination federated database.Note: If you omit the -id option to attach a database with its originalidentifier, and that database identifier is already used in the destinationfederated database, Objectivity/DB will generate a new identifier for thedatabase being attached.

■ The schema of the destination federated database is identical to (or asuperset of) the schema of the database being attached.Note: You can check the schemas and optionally add any necessary classes tothe destination federated database; see “Synchronizing Schemas” onpage 166.

Consequences of Changing a Database Identifier

When you attach a database with a changed identifier, Objectivity/DBautomatically adjusts:■ The object identifiers (OIDs) of the objects in the database■ Any relationships (associations) within the attached database■ Any relationships (associations) that exist among a group of databases

attached through the -dbmap option

However, Objectivity/DB does not attempt to adjust any references from objectsin the destination federated database to objects in the database being attached.

Attaching Multiple Databases

You can attach a group of databases to a federated database in a single operation.To do this, you run ooattachdb with the -dbmap option specifying the name ofan ASCII text mapping file.

DRAFTDatabase Tasks Attaching Multiple Databases



The mapping file specifies the file location of each database to be attached. Eachline in the mapping file has the following general format:

destDbID destDbSysName hostName filepath

where

If you omit the destDbID for a database, the identifier is obtained from thedatabase file. If a database with this identifier already exists in the federateddatabase, a new identifier is generated for the attached database.

If an error is detected in the line entry for any of the databases in the mappingfile, none of the databases are attached and ooattachdb terminates after issuingan error message.

EXAMPLE This command attaches three databases to the newFD federated database:

ooattachdb -dbmap /tmp/file.map newFD

The mapping file /tmp/file.map reads as follows:

3 parts machine33 /project1/parts/parts.DB4 newParts machine33 /project1/testData/newParts.DB5 oldParts machine33 /project1/oldParts/oldParts.DB

NOTE As an alternative using ooattachdb, you can use export and import to transfer agroup of databases from the same source federated database to a destinationfederated database; see “Importing a Group of Databases” on page 161.

Attaching a Large Number of Databases

Attaching a very large number of databases can be time-consuming because thecontents of every file are checked to see whether adjustments must be made toaccommodate changed database identifiers. If all the specified databases are to be

destDbID (Optional) Database identifier with which the database is to beattached.

destDbSysName System name with which the database is to be attached.

hostName Host system where the database file is located.

filepath Pathname (including the filename) where the database file islocated.

DRAFTDatabase Tasks Changing Database Properties



attached with their original identifiers, you can use the -catalogonly option toadd the databases to the global catalog without opening any database files.

When you use the -catalogonly option, you must specify each database’soriginal identifier explicitly as the destDbID in the mapping file entries.

WARNING Do not use the -catalogonly option if any database is being attached with anew identifier. Doing so will prevent Objectivity/DB from finding any objects inthe attached database.

Changing Database Properties

If a database is read-only, you must change it back to read-write before you canchange any other properties. You can change a read-only database back toread-write only if no other tool or application is currently reading either thatdatabase or any other read-only database in the same federated database.

You can use oochangedb (page 197) to change these database (ordatabase-image) properties:■ The file host and file path (this moves the database file)■ Whether the database is read-only or read-write■ (HA) The controlling autonomous partition■ (HA) The weight of a database image

Other tools are required to change a database’s system name or databaseidentifier as shown in the following subsection.

Changing the System Name or Database Identifier

Changing a database’s system name or database identifier is similar toduplicating a database. That is, you copy the database, delete the originaldatabase, and reattach the copy with the new identifier or system name. (HA) Ifthe database is replicated, you must recreate any desired images from thereattached copy.

A database identifier is a component of the object identifiers (OIDs) of objects inthe database. To see how such OIDs are affected, see “Consequences of Changinga Database Identifier” on page 83.

DRAFTDatabase Tasks Deleting a Database



Deleting a Database

You can delete a database from a federated database by using oodeletedb(page 216). Objectivity/DB deletes the database file, updates the federateddatabase’s global catalog, and removes all bidirectional relationships(associations) and all unidirectional relationships (associations) to objects in otherdatabases.

If the database you want to delete is read-only, you must change it back toread-write before you can delete it.

(HA) If the database is replicated, oodeletedb deletes all images; useoodeletedbimage to delete an individual image.

If the database file no longer exists, you delete the database from the federateddatabase’s global catalog by invoking oodeletedb with the -catalogonlyoption.

EXAMPLE This command deletes the database partsDb from the federated database myFD:

oodeletedb -db partsDb myFD

Setting File Permissions on a Database

You can prevent unauthorized users from writing to or deleting a database file byusing operating system commands to set appropriate permissions on that fileand, if necessary, the directory that contains it. Be sure to grant adequatepermissions to the account(s) that run AMS or the lock server so that theseservers can read and update all Objectivity/DB files.

Tidying a Database

To consolidate a database that has become fragmented over time, you runootidy (page 278) with the -db option. This tool transfers database objects to atemporary database file while it is running. Therefore it requires free disk spaceapproximately equal to the size of the database you are tidying. See “Tidying aFederated Database” on page 53 for a detailed discussion of ootidy operation.(HA) The ootidy tool tidies all images of a replicated database.

DRAFTDatabase Tasks Troubleshooting Access Problems



Warning: You should not use ootidy:■ While any other process is accessing the database, because database

corruption could occur. One way to guarantee that no other processes canaccess the database is to kill the lock server and to run ootidy in standalonemode.In particular, you should avoid running ootidy during a backup becauseootidy might delete objects that oobackup references.

■ If you suspect that the database has been corrupted. ootidy can make theproblem significantly worse.

Troubleshooting Access Problems

Any of the following conditions can prevent access to a single database within afederated database:■ The database file is missing or corrupted.■ The federated database’s global catalog is incorrect or corrupted.■ The database file protections are incorrect.■ The database host system is down.■ The database is read-only, and the federated database contains other

read-only databases that are currently being accessed. (A read-only databasecannot be changed back to read-write if any other read-only database in thefederation is currently being read.)

A workstation or network error can cause you to lose data. If you determine thatthe database file is missing or corrupted, restore the file from a backup.

For troubleshooting access to an entire federated database, see “Troubleshooting”on page 54.

DRAFTDatabase Tasks Troubleshooting Access Problems



89

<6/11/2003, 12:40 PM; /wrld/mnt09/pubs/working/admin/admLSTasks.fm>

DRAFT

7Using a Lock Server

Objectivity/DB provides concurrent multiuser access to data. To ensure that dataremains consistent, database access is controlled through locks granted by a lockserver.

This chapter describes:■ General information about lock servers■ Deciding whether to use a lock server■ Checking whether a lock server is running■ Starting and stopping a lock server■ Changing the lock-server host for a federated database or autonomous

partition■ Listing the locks that are currently managed by a lock server■ Changing the lock-server port■ Troubleshooting problems with the lock server

About Lock Servers

A lock server manages concurrent access to persistent objects by granting orrefusing locks to requesting transactions. When a transaction requests data froma federated database, Objectivity/DB locates the lock server that services thefederated database and then contacts the lock server to obtain a lock on therequested data. The lock is granted only if it is compatible with existing locks.Obtaining a lock prevents multiple concurrent transactions from performingincompatible operations on the same data, whether these transactions belong todifferent applications or to different threads of the same application.

DRAFTUsing a Lock Server Locks



Locks

A lock server grants locks to transactions requesting data from a federateddatabase or autonomous partition. Locks prevent multiple concurrenttransactions from performing incompatible operations on objects. Depending onthe request, the lock server may grant the transaction a read lock, an update lock,or an exclusive lock for a requested object.

Locking a basic object causes its container to be locked.

Read and update locks exist only while the lock server is running. If the lockserver or its host fails during a transaction, any locks held by the transactioncease to exist. For information about recovering transactions in this situation, see“Automatic Recovery From Lock-Server Failures” on page 140 and “ManualRecovery From Lock-Server Host Failures” on page 146.

Lock-Server Host

A lock server is identified by its location—that is, by the workstation, orlock-server host, on which it is running. Every federated database or autonomouspartition stores the name of a lock-server host as an property. When a transactionrequests data from a federation or partition, Objectivity/DB inspects thecorresponding boot file to identify the relevant lock-server host; the lock serverrunning on that host is then contacted.

A single lock server may service multiple federated databases and autonomouspartitions. In this situation, each federated database or partition specifies thesame workstation as the lock-server host.

Read lock When a transaction has a read lock for an object, othertransactions can concurrently obtain read locks for that object.If the read lock was obtained by a standard transaction, no othertransaction can obtain an update lock for the object. If the readlock was obtained by a transaction that uses the multiplereaders, one writer (MROW) concurrency mechanism, at mostone other transaction can obtain an update lock.

Update lock When a transaction has an update lock for an object, no othertransactions can concurrently obtain an update lock for thatobject, although transactions using MROW may obtain readlocks.

Exclusive lock When a transaction has an exclusive lock for an object, no othertransaction can concurrently obtain any kind of lock on theobject. Objectivity/DB obtains exclusive locks for operationssuch as creating or deleting a container.

DRAFTUsing a Lock Server Types of Lock Server



Because a federated database can have only one lock-server host, it can beserviced by only one lock server. (HA) When a federated database is partitioned,each autonomous partition may specify its own lock-server host, so differentpartitions can be serviced by different lock servers.

You can change the lock server that services a federated database or partition; see“Changing Lock-Server Hosts” on page 96.

Types of Lock Server

A standard lock server normally runs as a separate process on a lock-server host, asillustrated in Table 1-1 on page 27. A standard lock server is external to allapplications that consult it, even those running on the same host. MostObjectivity/DB installations are configured to use one or more standard lockservers. You normally run a standard lock server when you use administrationtools such as oonewfd or the Objectivity/DDL tool ooddlx.

An in-process lock server is just like a standard lock server, except that it runs aspart of an application process. This enables the application to request locksthrough simple function calls without having to send these requests to anexternal process. An in-process lock server can improve the runtime speed of theapplication that starts it, provided that most or all of the serviced lock requestsare from that application.

A C++, Java, or Smalltalk application starts an in-process lock server using theinterface provided with Objectivity/DB In-Process Lock Server(Objectivity/IPLS), which is a separately purchased option. An application thatstarts an in-process lock server is called an IPLS application. To find out moreinformation about IPLS applications, see the documentation for your Objectivityprogramming interface.

From an administration point of view, the main difference between a standardlock server and an IPLS application is the way they are started and stopped;otherwise, you can treat them the same way. When an in-process lock server isstarted, the IPLS application becomes the lock server for the workstation onwhich it is running. Consequently, if a federated database names this workstationas its lock-server host, all applications accessing that federated database willsend their lock requests to the IPLS application. The in-process lock server uses aseparate thread to service requests from external applications.

In this book, the term “lock server” refers to either a standard lock server or anin-process lock server. Unless specified otherwise, the lock-server tasks in thischapter apply both to standard lock servers and in-process lock servers.

DRAFTUsing a Lock Server Lock Servers on the Network



Lock Servers on the Network

You may run multiple lock servers on the same network, depending on thenumber of federated databases or autonomous partitions to be supported. A lockserver may, but need not, run on the same workstation as the federated databasesor partitions it serves.

You cannot run multiple lock servers from the same release of Objectivity/DB onthe same workstation. Although it is possible for the same workstation to runboth a current lock server and a lock server from certain older releases, this is notrecommended practice. If you want to run lock servers from differentObjectivity/DB releases (for example, because you are maintaining applicationsbuilt with different Objectivity/DB releases), you should arrange for the relevantfederated databases to use different lock-server hosts.

Required File and Directory

A lock server must have access to a file named ools-x.VPL, where x representsthe file’s current version number. You must not move, modify, or delete this file.

The required files are in the Objectivity server system directory on the lock-serverhost when the lock server is first accessed by an application. You must run thelock server under an account that has read and write access to the Objectivityserver system directory. The location of the directory depends on the platform:■ On Windows, the Objectivity server system folder is the Windows folder,

which is typically c:\winnt or c:\windows. The location of this folder,especially the drive name, may be different on your system.

■ On UNIX, the Objectivity server system directory is /usr/spool/objy. Younormally create this directory when you install Objectivity/DB.

On UNIX, the Objectivity server system directory also contains a file calledoolsrec.log, which records any errors from automatic recovery triggered bythe lock server. (Such errors are posted to the Application Log of the EventViewer on Windows.)

Deciding Whether to Use a Lock Server

Locking is required whenever multiple concurrent transactions (in multipleapplications or in multiple concurrent threads) can access the same federateddatabase. However, locking can be disabled for an application that has exclusiveaccess to a federated database and requires maximum performance—generally, asingle-user, single-threaded application run by a user with exclusive filepermissions. For information about disabling locking in an application, see thedocumentation for your Objectivity programming interface.

DRAFTUsing a Lock Server Checking Whether a Lock Server is Running



WARNING If an application disables locking, you must guarantee that only one thread hasaccess to the federated database at any time, or data corruption may occur.

Checking Whether a Lock Server is Running

You can check whether a lock server is running on a particular workstation. Todo this, use oocheckls (page 205).

Starting a Lock Server

Before you start a lock server, you must determine whether to start a standardlock server or an in-process lock server (“Types of Lock Server” on page 91). Astandard lock server is used during application development and with mostdeployed federated databases at end-user sites. An in-process lock server isnormally used only as necessary to improve the runtime speed of a particulardeployed application.

Standard Lock Server

When you install Objectivity/DB, you normally configure a workstation to starta standard lock server automatically every time the machine reboots. However,there may be situations that require you to start (or restart) a lock-server process.

You can start the lock server with or without arguments, depending on the kindof automatic recovery you want.

Windows

On Windows platforms, you start the lock server using the Objectivity NetworkServices tool that is provided with Objectivity/DB. This causes the lock server torun even when no user is logged on and to start automatically whenever thesystem boots. See “Starting and Stopping an Objectivity Server” on page 297.

You can optionally specify arguments to the lock server for automatic recovery.See “Configuring an Objectivity Server” on page 298.

DRAFTUsing a Lock Server In-Process Lock Server



You must start the lock server under a logon account that has the necessaryaccess permissions. See “Specifying a Service’s Logon Account” on page 298.

The logon account for starting the lock server must have:■ Read and write permissions to the Objectivity server system directory; see

“Required File and Directory” on page 92.■ Read permission to the boot file for each federated database or autonomous

partition to be serviced.■ Read and write permissions to all system-database, database, and journal

files to be serviced, and to the directories containing them.■ Permissions to use any required UNC network share names.

UNIX

On UNIX, you start a lock server using oolockserver (page 259), optionallyspecifying arguments for automatic recovery.

You must start the lock server under a user account that belongs to a group withread and write permissions to the Objectivity server system directory and to allsystem-database, database, and journal files to be serviced.

In-Process Lock Server

You start an in-process lock server by running an IPLS application—that is, byrunning an application in which Objectivity/IPLS functions are called.

An in-process lock server triggers automatic recovery as if it were a standard lockserver started without arguments—the recovery of each serviced federateddatabase is delayed until data is requested from it.

An in-process lock server cannot be started on a workstation that is alreadyrunning a standard lock server or an IPLS application.

Windows

On Windows, you start an in-process lock server on a workstation as follows:

1. If necessary, reconfigure the workstation so that rebooting it does notautomatically start a standard lock server. To do this, you use the ObjectivityNetwork Services tool to uninstall the standard lock server as a systemservice. See “Installing and Uninstalling an Objectivity Server” on page 299.

2. Start a single IPLS application on the workstation.

Make sure you start the application under a logon account that has:■ Read and write permissions to the Objectivity server system directory

DRAFTUsing a Lock Server Stopping a Lock Server



■ Read permission to the boot file for each federated database or autonomouspartition to be serviced

■ Read and write permissions to all system-database, database, and journalfiles to be serviced, and to the directories containing them

■ Permissions to use any required UNC network share names

UNIX

On UNIX, you start an in-process lock server on a workstation as follows:

1. If necessary, reconfigure the workstation so that rebooting it does notautomatically start a standard lock server. To do this, you remove theoolockserver command from the workstation’s startup script.

2. Start a single IPLS application on the workstation. You must start the IPLSapplication under a user account that belongs to a group with read and writepermissions to the Objectivity server system directory and to allsystem-database, database, and journal files to be serviced.

Stopping a Lock Server

The mechanism for stopping a lock server depends on whether it is a standardlock server or an in-process lock server.

Standard Lock Server

You can stop a standard lock server at any time, provided that it is not currentlyservicing any active transactions. An active transaction is any transaction thatholds a lock, even if the process that started it is no longer running. Thus, anactive transaction may be currently in progress or waiting for recovery.

NOTE If you stop a lock server while a database application is still running (forexample, while the application is between transactions), the application willencounter an error the next time it tries to start a transaction.

Windows

On Windows, you stop a standard lock server from the Objectivity NetworkServices tool.

Alternatively, you can enter ookillls.exe at a command prompt. OnWindows 98, do not choose End Task while the lock server is selected in the TaskManager.

DRAFTUsing a Lock Server In-Process Lock Server



UNIX

On UNIX, you stop a standard lock server using ookillls (page 252).

If You Cannot Stop a Standard Lock Server

A standard lock server cannot be stopped while servicing an active transaction. Ifan application is using a lock server that you want to stop, you:

1. Run oolockmon (page 258) to determine which transactions are currentlyusing the lock server.

2. If necessary, use oolistwait (page 254) to determine which processes areusing the lock server; notify the process owners to commit or abort theirtransactions.

3. If any locks belong to processes that are no longer running, use oocleanup(page 206) to recover the incomplete transactions.

4. When you are certain that no active transactions are using the lock server,terminate the lock-server process as you normally would on your platform.

In-Process Lock Server

An in-process lock server can only be stopped by the IPLS application thatstarted it.

WARNING Terminating an IPLS application before it stops its in-process lock server isequivalent to an abnormal lock-server failure, and any incomplete transactionswill require recovery.

Changing Lock-Server Hosts

You may need to change the lock server that services a federated database orautonomous partition. For example, if the current lock-server host for a federateddatabase has become permanently inaccessible, you must use a lock server on adifferent host. Or, to reduce the number of federated databases or partitionsserviced by a particular lock server, you can assign some of them to a differentlock server.

DRAFTUsing a Lock Server Listing Current Locks



To change the lock-server host for a federated database or autonomous partition:

1. Ensure that the new lock-server host can access the journal directory and allfiles associated with the federated database or partition, using the pathnamesregistered in the boot file and the global catalog. Use oochange (page 194)with just the boot-file name (and -ap option, if necessary) to view thesepathnames.

2. Use oochange to specify the new lock-server host as an property of thefederated database or autonomous partition. If the old lock server is notrunning, use the -standalone option.

You can now restart the lock server on the new lock-server host (see “Starting aLock Server” on page 93).

EXAMPLE UNIX

This example sets name of the lock-server host of the federated database myFD tomach44 (assuming that the old lock server is still running):

oochange -lockserverhost mach44 myFD

Listing Current Locks

You can list all locks and processes currently managed by the lock server. To dothis, use oolockmon (page 258). You can use this information to determine thelocking status on objects and to locate unexpected locks. If you find locks that areheld by transactions belonging to terminated application processes, you can useoocleanup (page 206) to release them.

Changing the TCP/IP Port for the Lock Server

The lock server is assigned a default TCP/IP port number by Objectivity/DB.This port is used by remote processes (such as Objectivity/DB applications orAMS) for communicating with the lock server.

On rare occasions, you may be prevented from starting the lock server becauseanother service is already using the default lock-server port. If possible, youshould assign the other service to a different TCP/IP port. If you cannot do this,you can assign the lock server to a nondefault port; however, you will have tomake this change on every host that runs a process that interacts with this lockserver.

DRAFTUsing a Lock Server Changing the TCP/IP Port for the Lock Server



Windows

If you cannot start the lock server, you can determine whether a port conflictexists:

1. Inspect the lock server output by using the Windows Event Viewer to checkthe Application Log.

2. If a port conflict exists, the message 10048 (WSAEADDRINUSE) is displayed.

To assign a different lock-server port:

1. Log on as administrator or as a user with equivalent privileges.2. Click Start and point to Programs. In the Objectivity submenu, select

Objectivity Network Services.3. Select the Objectivity Lock Server and click Stop.4. When the lock server has stopped, click Configure.5. In the TCP/IP Port Number field, enter the new port number and click OK. To

avoid conflicts, enter a number greater than 1035.6. Click Start to restart the lock server.

Note: You must make this change on every host that runs the lock server or aprocess that uses the lock server (an Objectivity/DB application or AMS).

UNIX

To assign a lock-server port on a UNIX platform:

1. Log in as root.2. Add the following entry to the TCP/IP services file (typically,

/etc/services):ools-xx portNumber/tcp # Objectivity/DB lock server

where

3. Send a hangup signal to your inetd process. For example, if inetdPid is theprocess identifier for the inetd process, enter:kill -HUP inetdPid

Note: You must make this change on every host that runs the lock server or aprocess that uses the lock server (an Objectivity/DB application or AMS).

xx The current version of the lock server. (For the current version,see the Objectivity Technical Support web site; call ObjectivityCustomer Support to get access to the site.)

portNumber TCP/IP port number (a number greater than 1024).

DRAFTUsing a Lock Server Troubleshooting Problems With the Lock Server



If you are using the Network Information Service (NIS), you should ask yoursystem administrator to perform the equivalent operation for your NISconfiguration.

Troubleshooting Problems With the Lock Server

Because lock servers control distributed systems, problems with lock servers maydiffer across operating systems.

Windows and UNIX

Lock-Server Timeout

By default, an application or tool waits 25 seconds for the lock server to respondto a request. However, a lock server running on a busy machine may need moretime to respond. If an application or tool consistently signals a lock-servertimeout error you can increase the network timeout period by setting theOO_RPC_TIMEOUT environment variable to the desired number of seconds—forexample:

set OO_RPC_TIMEOUT=50 # Windowssetenv OO_RPC_TIMEOUT 50 # UNIX

Alternatively, you can consider running the lock server on a less congested host.

The value of the OO_RPC_TIMEOUT environment variable overrides any networktimeout period set by an application. For information about setting a networktimeout period in an application, see the documentation for the appropriateObjectivity programming interface.

Lock-Server Connection Failure

If an application or tool signals a failure to connect to a lock server, and youknow the lock server is running, the connection failure may be due to a heavilyloaded network. You can increase the likelihood that at connection will be madeby increasing the number of attempted connections. To do this, you set theOO_CONNECT_RETRIES environment variable to be the desired number ofadditional attempts to be made after an unsuccessful initial attempt——forexample:

set OO_CONNECT_RETRIES=4 # Windowssetenv OO_CONNECT_RETRIES 2 # UNIX

The value of this environment variable overrides the system default, which is:■ 0 on UNIX; only a single attempt is made (the initial attempt and no retries).

DRAFTUsing a Lock Server Windows



■ 2 on Windows; a total of three attempts are made (an initial attempt, plustwo retries).

The value of the OO_CONNECT_RETRIES environment variable is overridden byany value set by an application. For information about setting the number ofconnect retries in an application, see the documentation for the appropriateObjectivity programming interface.

Windows

Consider the following information if you encounter problems with the lockserver on a Windows platform. You can use the Windows EventViewer to checkthe Application Log for any relevant messages.

If You Cannot Start a Lock Server

If you cannot start a lock server on a Windows platform, it may be due to one ofthe following reasons:■ You do not have read and write access to the Windows folder or the required

files in it.■ Required services have not initialized.

When Windows starts or reboots, many services required by the lock serverare initialized, including TCP/IP. It is possible for initialization to take time.If the lock server fails to start immediately after the system reboots, trystarting it again after a minute or so.

■ TCP/IP is not installed.The lock server requires that a Winsock-compatible TCP/IP stack is installedand correctly configured. See “TCP/IP Configuration Problems” below formore information.

■ A port conflict exists between the lock server and another running process.

If You Cannot Connect to the Lock Server

If your applications cannot connect to the lock server in a Windowsenvironment, it may be due to one of the following:■ Lock server is not running.

Make sure the lock server is running on the machine specified by your bootfile.

■ TCP/IP is not installed.Objectivity/DB applications require that a Winsock-compatible TCP/IP stackbe installed and correctly configured. See “TCP/IP Configuration Problems”below for more information.

■ Different hosts have different TCP/IP ports assigned to the lock server.

DRAFTUsing a Lock Server UNIX



TCP/IP Configuration Problems

Objectivity/DB applications require that a Winsock-compatible TCP/IP stack beinstalled and correctly configured. In particular:■ The TCP/IP hosts configuration file should contain entries for your

workstation and any other machines you wish to access, even if you areusing DNS. Entries should include the hostname and IP address.

■ If you are using DHCP, your system administrator should set up a DHCPreservation for your host to ensure that the same IP address will always beassigned to your host.

NOTE The TCP/IP hosts configuration file is typically%systemroot%\system32\drivers\etc\hosts.

Some common TCP/IP configuration problems are listed below. You shouldconsult your system administrator before changing your TCP/IP configuration:■ Incorrect IP address or hostname is specified.

Make sure that the IP addresses and hostnames of all the machines areconsistent on all hosts. This may involve checking each workstation’sTCP/IP hosts configuration file, verifying that DNS is configured properly,or verifying that DHCP is configured properly.

■ Hostname is missing.Make sure that an entry for your workstation is included in the TCP/IP hostsconfiguration file.

UNIX

Consider the following information if you encounter problems with the lockserver on a UNIX platform. You can check the system log file for any relevantmessages.

If You Cannot Start the Lock Server

A port conflict may exist between the lock server and another running process.

File Access Requirements

To start a lock server, you must have read and write access to the Objectivityserver system directory (/usr/spool/objy) or the required files in it.

Database Files Not Exported by NFS

The lock server requires that any user directories that contain, or will contain,Objectivity/DB files be exported by NFS. If they are not exported, refer to the

DRAFTUsing a Lock Server UNIX



documentation for your operating system to export these directories. To exportthese directories, place them in the /etc/exports file.

103

<6/11/2003, 12:40 PM; /wrld/mnt09/pubs/working/admin/admAMSTasks.fm>

DRAFT

8Advanced Multithreaded Server

In a distributed system, an Objectivity/DB application may request data that islocal (on the same host as the application) or remote (on a different host). Whenservicing a request for remote data, Objectivity/DB contacts data-server softwareto obtain that data. If you choose, you can use Objectivity’s AdvancedMultithreaded Server (AMS) as your data-server software.

This chapter describes:■ General information about AMS■ Deciding whether to use AMS■ Checking whether AMS is running■ Starting and stopping AMS■ Setting AMS usage in an application■ Changing the AMS port■ Troubleshooting problems with AMS

About AMS

AMS is data-server software that is provided with Objectivity/DB. You can runAMS on remote data-server hosts to make the system-database, database, orjournal files on those hosts available to Objectivity/DB applications. AMS is anoptional alternative to native file servers (commonly, NFS or Microsoft WindowsNetwork), which means you can use AMS on any or all remote data-server hostsin a distributed Objectivity/DB system. You must run AMS on each data-serverhost that is to contain a replicated database.

When you use AMS, you refer to each Objectivity/DB file by specifying thedata-server host on which the file resides and the pathname of the file on thathost (for more information, see “Files on AMS Data-Server Hosts” on page 35).You do not need to export any file systems or use special network share names ormount names.

DRAFTAdvanced Multithreaded Server Deciding Whether to Use AMS



You can run AMS on multiple hosts in a network. On a single workstation,however, you may run only one AMS process per version of AMS.

Deciding Whether to Use AMS

In most cases, AMS is recommended over NFS or Microsoft Windows Networkbecause of performance advantages, flexibility, and ease of use. AMS is requiredif you are using data replication (Objectivity/HA).

Guidelines for Choosing AMS

You must run AMS on data-server hosts if:■ You are using data replication (Objectivity/HA). Specifically, you must run

AMS on every data-server host that stores a database image. AMS need notbe running when you first create a database; however, you must start AMSbefore you can create additional database images.

You should run AMS on a data-server host if:■ Your Objectivity/DB application performs many update transactions, or

modifies or creates many objects per update transaction.■ Your Objectivity/DB application performs a moderate number of update

transactions and is connected to the server host via a WAN or large LAN.■ NFS is not already in use on the data-server host.■ You prefer not to export complete NFS file systems to all users.■ You prefer not to run NFS.■ You need interoperability between Windows and UNIX platforms. Although

you can use other networking software, AMS offers a simpler solution.■ You want a simpler alternative to setting up common UNC network share

names in a Windows environment.

Checking Whether AMS is Running

You can check whether AMS is running on a particular workstation. To do this,use oocheckams (page 205).

DRAFTAdvanced Multithreaded Server Starting AMS



Starting AMS

You can start AMS on a Windows or UNIX data-server host. On a given host, youcan run only one AMS process per version of AMS.

Windows

On Windows platforms, you start AMS using the Objectivity Network Servicestool that is provided with Objectivity/DB. This causes AMS to run even when nouser is logged on and to start automatically whenever the system boots. See“Starting and Stopping an Objectivity Server” on page 297.

You should start AMS under a special-purpose logon account; see “Specifying aService’s Logon Account” on page 298. For security reasons, you should set upthe AMS logon account to have just the minimum necessary access permissions.The AMS logon account must have read and write access to:■ All system-database, database, and journal files to be accessed, and the

directories containing them■ The Objectivity server system directory; see “Required File and Directory”

on page 92.

UNIX

On UNIX, you start AMS using oostartams (page 275).

For security reasons, you should start AMS under a special-purpose user accountthat has just the minimum necessary access permissions. The AMS user accountmust belong to a group with read and write permissions to:■ All system-database, database, and journal files to be accessed, and the

directories containing them■ All directories in which new system-database, database, and journal files will

be created■ The Objectivity server system directory (/usr/spool/objy)

It is strongly recommended that you not run AMS under the root account.

DRAFTAdvanced Multithreaded Server Stopping AMS



Stopping AMS

You can stop AMS if no database applications are currently using it. An errormessage is displayed if you try to stop AMS while database applications areusing it.

Windows

On Windows, you stop AMS from the Objectivity Network Services tool.

Alternatively, you can run oostopams.exe (page 276) from a command prompt.

UNIX

On UNIX, you stop AMS using oostopams.

Setting AMS Usage in an Application

By default, Objectivity/DB applications use AMS whenever possible. You canoverride the default behavior either to prevent or to require AMS usage. For adiscussion of setting AMS usage in an application, see the documentation for theappropriate Objectivity programming interface.

Changing the TCP/IP Port for AMS

AMS is assigned a default TCP/IP port number by Objectivity/DB. This port isused by remote processes (such as Objectivity/DB applications) forcommunicating with AMS.

On rare occasions, you may be prevented from starting AMS because anotherservice is already using the default AMS port. If possible, you should assign theother service to a different TCP/IP port. If you cannot do this, you can assignAMS to a nondefault port; however, you will have to make this change on everyhost that runs a process that interacts with AMS.

DRAFTAdvanced Multithreaded Server Changing the TCP/IP Port for AMS



Windows

If you cannot start AMS, you can determine whether a port conflict exists:

1. Inspect AMS output by using the Windows Event Viewer to check theApplication Log.

2. If a port conflict exists, the message 10048 (WSAEADDRINUSE) is displayed.

To assign a TCP/IP port for AMS on a Windows platform:


Objectivity Network Services.3. Select AMS and click Stop.4. When AMS has stopped, click Configure.5. In the TCP/IP Port Number field, enter the new port number and click OK. To

avoid conflicts, enter a number greater than 1035.6. Click Start to restart AMS.

Note: You must make this change on every host that runs either AMS or a processthat uses it (an Objectivity/DB application, a lock server, or Objectivity/DBtools).

UNIX

To assign a TCP/IP port for AMS on a UNIX platform:

1. Log in as root.2. Add the following entry to the TCP/IP services file (typically,

/etc/services):ooams-xx portNumber/tcp # Objectivity/DB AMS

where

3. Send a hangup signal to your inetd process. For example, if inetdPid is theprocess identifier for the inetd process, enter:kill -HUP inetdPid

Note: You must make this change on every host that runs either AMS or a processthat uses it (an Objectivity/DB application, a lock server, or Objectivity/DBtools).

xx The current version of AMS. (For the current version, see theObjectivity Technical Support Web site; call Objectivity CustomerSupport to get access to the site.)

portNumber TCP/IP port number (a number greater than 1024).

DRAFTAdvanced Multithreaded Server Troubleshooting Problems With AMS



If you are using the Network Information Service (NIS), ask your systemadministrator to perform the equivalent operation for your NIS configuration.

Troubleshooting Problems With AMS

Windows and UNIX

AMS Timeout

By default, an application or tool waits 25 seconds for AMS to respond to arequest. However, when running on a busy machine, AMS may need more timeto respond. If an application or tool consistently signals an AMS timeout error,you can increase the network timeout period by setting the OO_RPC_TIMEOUTenvironment variable to the desired number of seconds—for example:

set OO_RPC_TIMEOUT=50 # Windowssetenv OO_RPC_TIMEOUT 50 # UNIX

The value of the OO_RPC_TIMEOUT environment variable overrides any networktimeout period set by an application. For information about setting a networktimeout period in an application, see the documentation for the appropriateObjectivity programming interface.

AMS Connection Failure

If an application or tool signals a failure to connect to AMS, and you know AMSis running, the connection failure may be due to a heavily loaded network. Youcan increase the likelihood that at connection will be made by increasing thenumber of attempted connections. To do this, you set the OO_CONNECT_RETRIESenvironment variable to be the desired number of additional attempts to be madeafter an unsuccessful initial attempt——for example:

set OO_CONNECT_RETRIES=4 # Windowssetenv OO_CONNECT_RETRIES 2 # UNIX

The value of this environment variable overrides the system default, which is:■ 0 on UNIX; only a single attempt is made (the initial attempt and no retries).■ 2 on Windows; a total of three attempts are made (an initial attempt, plus

two retries).

The value of the OO_CONNECT_RETRIES environment variable is overridden byany value set by an application. For information about setting the number ofconnect retries in an application, see the documentation for the appropriateObjectivity programming interface.

109

<6/11/2003, 12:40 PM; /wrld/mnt09/pubs/working/admin/admBackupTasks.fm>

DRAFT

9Backup and Restore

This chapter describes how to use Objectivity/DB administration tools to backup and restore a federated database. You can run these tools either from thecommand line or within a shell script, and they include options that allow you tocustomize backup and restore tasks for special needs. Objectivity/DB alsosupports full user access (read and update) during backup.

This chapter describes:■ General information about backup and restore■ Developing a backup strategy■ Backing up data and restoring from a backup■ Managing backup history■ Processing data during backup and restore■ Backing up to and restoring from tape■ Customizing your backup scheme for greater administrative control

About Backup and Restore

You need to back up critical user data so it can be restored if the original databecomes unusable. Possible scenarios include:■ A catastrophic event (such as an accidental erasure or a disk crash) destroys

part or all of the federated database.■ The logical state of the federated database is corrupted. Data in the federated

database is incorrect and the transaction that created the problem has alreadycommitted.

■ The physical state of the federated database is corrupted, making user datainaccessible.

■ You want to go back to using a previous version of Objectivity/DB softwareafter upgrading to a new release of Objectivity/DB that has a differentdatabase format.

DRAFTBackup and Restore Basic Backups



In most cases, you can accommodate these scenarios by performing a series ofbasic backups, which are described in the following subsections. Objectivity/DBalso supports customized backups for sites that want greater control over backupadministration; see “Customized Backups” on page 126.

Basic Backups

A backup (also called a backup event) is a recorded description of a federateddatabase at a particular point in time—a description that enables you to laterreproduce that federated database as it was when the backup was taken.

A backup is physically stored as one or more files (also called volumes) on abackup medium, which is normally a disk directory. On UNIX platforms, you canuse Objectivity/DB tools to back up to tape; for non-UNIX platforms,Objectivity/DB provides a mechanism for executing your own scripts to performtape backup. See “Backing Up to and Restoring From Tape” on page 124.

A basic backup refers to a backup whose administrative details are managed byObjectivity/DB. For example, Objectivity/DB uses its own conventions fornaming a series of backup volumes. A system of basic backups may have up to3 backup levels and is implicitly organized by Objectivity/DB into administrativestructures called backup sets.

Backup Levels

A basic backup can be taken at one of the three backup levels shown in Table 9-1.

The smallest portion of data that can be archived to a backup medium is acontainer.

An incremental backup subsumes any previous incremental backup up to themost recent full backup. Thus, if you take two successive incremental backups ina row, the second one includes all of the containers recorded in the first, plus anycontainers that were modified since the first was taken.

Table 9-1: Basic Backup Levels

This Level Backs Up

full The entire federated database (including all databases and allcontainers within each database regardless of whether theyhave been updated).

incremental All containers updated since the most recent full backup.

subincremental All containers updated since the most recent incrementalbackup.

DRAFTBackup and Restore Point of Restore



Similarly, a subincremental backup subsumes any previous subincrementalbackup up to the most recent incremental backup; if you take two successivesubincremental backups in a row, the second one includes all of the containersrecorded in the first, plus any additional containers that were modified since thefirst was taken.

You can customize your system of backups by introducing up to ten backuplevels; see “Customized Backups” on page 126.

Backup Sets

Within a system of basic backups, Objectivity/DB implicitly creates logicalgroupings called backup sets for administrative purposes. Each backup setconsists of a single full backup and any incremental and subincremental backupsthat are based on it.

You can customize your system of backups by creating your own backup sets forseparately administered group of backup events. For example, each backup setcan represent an entire month of federated database backup events. See“Customized Backups” on page 126.

Point of Restore

The point of restore is the point in time to which the federated database is restored.Each backup event represents a possible point of restore.

Full Restore

Objectivity/DB always restores an entire federated database to guarantee thereferential integrity of the relationships (associations) between databases and thelogical integrity of the data within and across databases. Consequently:■ Specifying a full backup as the point of restore is sufficient to reconstruct an

entire federated database.■ Specifying an incremental backup as the point of restore causes

Objectivity/DB to restore data from both the specified incremental backupand the full backup on which it is based.

■ Specifying a subincremental backup as the point of restore causesObjectivity/DB to restore data from the specified subincremental backup, aswell as the incremental and full backups on which it is based.

Backup Diary

When you first back up a federated database, Objectivity/DB creates a containerand objects within the federated database to help administer data backups andrestorations. These objects are collectively called the backup diary.

DRAFTBackup and Restore User Access During Backup and Restore



Objectivity/DB uses the diary to keep track of all backup and restore events,creating objects to represent each event. The diary is used internally byObjectivity/DB tools such as ooqueryset (page 265), and is not available fordirect user access. It is archived during each backup to ensure the ability torecover from its accidental deletion or corruption.

User Access During Backup and Restore

Objectivity/DB allows full user access (both read and write) during backups. Bycontrast, once you initiate a restore, Objectivity/DB prevents other users fromaccessing the federated database until it is entirely restored.

NOTE Even if you restore the federated database to an entirely new location (in effect,making a copy), both the copy and the original are inaccessible for the durationof the restore. For directions on how you can work around this restriction, see“Allowing Restricted User Access During a Restore” on page 119.

Increased Space Requirements Due to User Access

To allow full access during a backup while maintaining data consistency,Objectivity/DB retains the old versions of any containers modified while thebackup is in progress. (Normally, old versions of containers are deleted as soonas transactions commit.) Other users access the most recent versions of thecontainers while the Objectivity/DB backup tool records the state of thefederated database as it was when the backup began.

This has important implications for the amount of free disk space required toexecute a backup. Namely, while a backup is in progress, the federated databasegrows in size as users update its containers. The extra versions of a container arepurged (and the space is recycled for reuse) the first time the container isupdated after the backup is complete and all locks on the extra versions havebeen released.

Backup Boot File

Whenever you take a full backup of a particular federated database, youestablish its backup boot file, which is the boot file you must specify in allsubsequent backup and restore operations within the same backup set.

When a federated database has only one boot file, that boot file is the backupboot file. When a federated database has multiple boot files, you must choose one

DRAFTBackup and Restore Developing a Backup Strategy



specific backup boot file for the full backup and any incremental andsubincremental backups based on it. For example:■ (HA) In a partitioned federated database, each autonomous partition has its

own boot file. You must specify the same partition’s boot file to everyoperation that takes a backup or restores a backup within the same backupset. (One boot file per autonomous partition is saved in a backup.)

Developing a Backup Strategy

To ensure the safety of critical data, you should develop a backup strategy beforeproblems arise. Developing a backup strategy involves:■ Estimating the disk space required to perform and store backups■ Defining a backup schedule

NOTE Always perform a full backup before a software upgrade in case you need torestore the data to its prior format because of problems with the softwareupgrade.

Estimating the Disk Space Required for Backups

The amount of free disk space required to execute a full, online backup of afederated database can be as much as two times (2X) the current size of thedatabase. This figure has two components: 1X represents the space required tostore the backup volumes and 1X represents the potential increase in databasesize while the backup is in progress.

NOTE The 1X figure given for database growth during a backup assumes that everycontainer is updated while the backup is in progress. This may or may not be areasonable assumption for your federated database backup. For a discussion ofdatabase growth during an online backup, see “Increased Space RequirementsDue to User Access” on page 112.

You can decrease the space required to store a backup in two ways:■ Process the backup volumes as they are produced to compress them or move

them to another medium; see “Processing Backup Files” on page 123.Note: Objectivity/DB allows you to override the default storage capacity(1 MB) of the backup volumes. When moving backup volumes from disk to

DRAFTBackup and Restore Defining a Backup Schedule



another backup medium, you can decrease the amount of disk spacerequired for temporary storage by decreasing the backup volume capacity.

■ Execute an incremental backup. Containers that have not been updated arenot archived.

You can decrease the amount of database growth during a backup in two ways:■ Perform the backup when usage is light. This slows the rate of database

growth.■ Execute an incremental backup. This decreases the total time required to

perform the backup and thus the time during which the database can grow.

Defining a Backup Schedule

A backup schedule defines how much data is archived at what times. It providesa means of administering data backups and informs users when backups willoccur. Informed users can request changes to the backup schedule to improve thesecurity of critical data given their pattern of usage.

For a small federated database, daily full backups can be practical. For a largefederated database, however, daily full backups are impractical because of thetime required to complete a full backup, and the space needed to execute andstore full backups. Therefore, most backup schedules involve:■ A full backup at the beginning of the week (or some other defined cycle)■ Incremental backups during the week (or cycle)

For example, as a normal routine, you might perform a full backup each Sundayand incremental backups every weekday.

Guidelines for Defining a Backup Schedule

To help you choose the length of the cycle, and the frequency of incremental andsubincremental backups, observe the following guidelines:■ Match the backup frequency to the rate at which critical data is updated.

Ideally, you should make sure that every modified container with criticaluser data is in at least one backup.

■ Avoid frequent full backups if the amount of data to be archived is large.■ Build in some redundancy by taking several successive incremental (or

subincremental) backups of critical data. Doing so preserves most of themodified containers in multiple backup files, reducing the risk of losingmany days’ updates if one of the backup files is damaged.

DRAFTBackup and Restore Performing a Backup



Example Backup Schedule

Table 9-2 shows a sample schedule for a federated database that is updated dailyduring the week.

Performing a Backup

The basic way to back up a federated database is to run oobackup (page 190)with options specifying the backup level (-full, -incremental, or-subincremental) and the destination directory in which to write the backupfiles. You must specify the federated database’s backup boot file; see “BackupBoot File” on page 112. You may perform only one backup on a federateddatabase at a time.

EXAMPLE This example runs a full backup of the federated database whose backup bootfile is mfgFd, and stores the backup files in the directory /fdb/backups.

oobackup -full -destination /fdb/backups mfgFd

You use different options if you want to customize your system of backups; see“Performing a Customized Backup” on page 131.

WARNING Do not run oobackup and either ootidy or oogc concurrently, because thesetools may delete objects that oobackup references.

Table 9-2: Sample Weekly Backup Schedule

Day Level Days’ Changes Backed Up

Sunday full (full backup creates a new baseline)

Monday incremental Monday

Tuesday subincremental Tuesday

Wednesday incremental Monday–Wednesday

Thursday subincremental Thursday

Friday subincremental Friday

DRAFTBackup and Restore If a Backup Fails



If a Backup Fails

Because backups of corrupted federated databases often fail, you can use routinebackups as opportunities to check for database corruption. If you run oobackupfrom a backup script, make sure that the script checks the tool’s return status.

The oobackup tool cannot recover from errors that occur during its execution. Ifa backup fails at any time during the backup process, you must restart thebackup. An aborted backup event has no effect on the existing federateddatabase.

Restoring From a Backup

You restore a federated database by running oorestore (page 267) with optionsspecifying the point of restore. You must also specify the path of the backup bootfile (the boot file that was used to create the backup).

You can restore a federated database and its associated files—its system-databasefiles, backup boot file, and database files—either to their original locations or todifferent locations.

The following subsections describe:■ “Specifying the Point of Restore” on page 116■ “Restoring Files to Their Original Locations” on page 117■ “Restoring Files to a Single New Location” on page 118■ “Restoring Files to Multiple New Locations” on page 119■ “If a Restore Fails” on page 121

Usually you restore from the most recent backup event. However, if you want torestore a federated database because you have detected corruption, try todetermine when the corruption occurred and restore from the most recentbackup before the time of corruption. If you cannot determine when thecorruption occurred, you can restore (to a new location so that you do notoverwrite the current system-database file) from a recent backup and then testthe restored federated database for corruption—for example, using the oochecktool.

Restoring a federated database automatically consolidates fragmented space, soit is normal for the restored files to be significantly smaller than the original files.

Specifying the Point of Restore

When the point of restore is represented by a basic backup, you specify it withthe -time option indicating the time at which the backup was taken, and the

DRAFTBackup and Restore Restoring Files to Their Original Locations



-source option indicating the directory that contains the backup files to berestored.

You use different options if you want to restore from a customized backup; see“Restoring a Customized Backup” on page 132.

You express the -time option as an integer YYYYMMDDHHmm containing up to 12digits that represent component times as follows:

For example, 200105150030 specifies 12:30 A.M. the morning of May 15, 2001.

If no backup in the specified directory corresponds exactly to the specified time,oorestore searches the directory and selects the latest backup that was startedprior to the specified time. Thus, if you specified 200105150000, but no backupwas taken starting at 12:00 A.M. (midnight) on May 15, oorestore would selectthe last (or only) backup taken on May 14, 2001 (if such a backup exists in thedesired directory).

If the selected backup is incremental (or subincremental), Objectivity/DBautomatically restores the full (and incremental) backup(s) on which the selectedbackup is based. However, the files for these backups must reside in the samelocation as they did when they were first created, because Objectivity/DB findsthem by consulting the archived backup diary.

Restoring Files to Their Original Locations

You typically restore a federated database and its associated files to the samephysical locations (host and directory) where they resided when they werearchived. To restore a federated database’s files to their original locations:

1. Verify that the backup files and the original directories exist and areaccessible.

2. Run oorestore (page 267) with options that specify the point of restore(page 116). You must also specify the path of the backup boot file (the boot filethat was used to create the backup).

YYYY Year

MM Month of the year (01 to 12). For example, 02 is February.

DD Day of the month (01 to 31).

HH Hour of the day (00 to 23). For example, 00 is 12:00 A.M. midnight,01 is 1:00 A.M., 13 is 1:00 P.M., and 23 is 11:00 P.M.

mm Minute of the hour (00 to 59)

DRAFTBackup and Restore Restoring Files to a Single New Location



EXAMPLE This command restores the mfgFd federated database from the backup that wasstarted on or before February 6, 2001 at 3:30 A.M. and that was archived to the/fdb/backups directory. The restored files are placed on the hosts anddirectories from which they were archived.

oorestore -time 200102060330 -source /fdb/backups mfgFd

Restoring Files to a Single New Location

Sometimes you cannot restore a federated database’s files to their originallocations—for example, when the original hosts or directories no longer exist. Insuch cases, you can specify a new location for the restored federated database.When you do this:■ The backup boot file is restored to the current working directory.■ The system-database file(s) and all database files are restored to the specified

location. The global catalog is updated accordingly.■ Every journal-directory property (one for each autonomous partition) is reset

to the same specified directory.

To specify a new location for restored files:

1. Verify that the required backup files and the destination directory exist andare accessible.

2. Run oorestore (page 267) with the -newhost and -newdirectoryoptions in addition to the options specifying the point of restore (page 116).You must also specify the path of the backup boot file (the boot file that wasused to create the backup).

3. If the federated database is partitioned, move each partition’s restoredsystem-database file and boot file to an appropriate location, and set a uniquejournal directory for each autonomous partition (use oochange, page 194).

You can specify the -failonly option to restore files to the new location only ifthe files’ original locations are inaccessible. The backup boot file is restored to thecurrent working directory if its original location is inaccessible.

DRAFTBackup and Restore Restoring Files to Multiple New Locations



EXAMPLE This command restores the mfgFd federated database from the backup that wasstarted on or before February 6, 2001 at 3:30 A.M. and that was archived to the/fdb/backups directory. The federated database files are restored to thedirectory /mnt/newfdloc on host machine42.

oorestore -time 200102060330 -source /fdb/backups-newhost machine42 -newdirectory /mnt/newfdloc mfgFd

This command restores the mfgFd federated database from same point of restoreas the previous command. Any files that cannot be restored to their originallocations are restored to directory /mnt/newfdloc on host machine42.

oorestore -time 200102060330 -source /fdb/backups-newhost machine42 -newdirectory /mnt/newfdloc-failonly mfgFd

Allowing Restricted User Access During a Restore

For development purposes, you may want to restore a federated database to anew location without locking users out of the original. To do this you useoorestore with the -newhost, -newdirectory, and -standalone options. Ineffect, you make a copy that you can modify without endangering the original.

Restoring Files to Multiple New Locations

You can restore the files of a federated database to multiple new locations. To doso, you provide the file destinations explicitly in an ASCII-text mapping file. Filesnot specified in the mapping file are restored to their original locations, except forthe backup boot file, which is placed in the current working directory. Normally,you restore to multiple new locations only if the original locations areinaccessible and the files to be restored are too large to fit into a single directory.

To restore to multiple new locations:

1. Create a mapping file specifying the desired destination locations; see below.2. Verify that the required backup volumes and the destination directories exist

and are accessible.3. Run oorestore with options specifying the point of restore (page 116) and

with the -dbmap option followed by the name of the mapping file. You cannotuse the -dbmap option with the -newhost, -newdirectory, or -failonlyoption.

DRAFTBackup and Restore Restoring Files to Multiple New Locations



Creating a Mapping File

To create the mapping file, you need the system names of the federated database,autonomous partitions, and databases that you want to restore to new locations.If the federated database has been corrupted or destroyed, you may need toobtain global-catalog information from the backup volumes themselves; see“Obtaining Global-Catalog Information” on page 121.

Each line in the mapping file specifies the destination location of asystem-database or boot file, or a new value for a journal-directory property.Each line consists of four strings, separated by spaces or tab characters, asfollows:

FD fdSysName targetHost targetPathFDJNL fdSysName targetHost targetPathAP apSysName targetHost targetPathAPBOOT apSysName targetHost targetPathAPJNL apSysName targetHost targetPathDB dbSysName targetHost targetPath

where

EXAMPLE This command restores the mfgFd federated database from the backup that wasstarted on or before February 6, 2001 at 3:30 A.M. and that was archived to the/fdb/backups directory. The files are restored to the locations specified in themapping file /tmp/file.map. If a file is not specified in the mapping file, it isrestored to its previous location.

oorestore -time 200102060330 -source /fdb/backups-dbmap /tmp/file.map mfgFd

The mapping file /tmp/file.map reads as follows:

FD mfgFd machine42 /mnt/newfdloc/fd/mfgFd.FDBFDJNL mfgFd machine42 /mnt/newfdloc/fdAP mfgAp1 machine42 /mnt/newfdloc/ap/mfgAp1.AP

fdSysName Federated-database system name(HA) Name of the initial autonomous partition in a partitionedfederation

apSysName (HA) Autonomous-partition system name

dbSysName Database system name

targetHost Target hostname

targetPath Target path for directory or filename

DRAFTBackup and Restore If a Restore Fails



AP mfgAp2 machine42 /mnt/newfdloc/ap/mfgAp2.APAPJNL mfgAp2 machine42 /mnt/newfdloc/apAPBOOT mfgAp2 machine42 /mnt/newfdloc/ap/mfgAp2DB partsDb fafhrd /newdbloc/partsDb.mfgFd.DB

Obtaining Global-Catalog Information

To display the global catalog, including all system names, for an archivedfederated database, you use oorestore (page 267) with the -dumpcatalogoption. You can use this information when creating a mapping file.

WARNING Do not run oorestore with the -dumpcatalog option in the directory thatcontains the federated database’s system-database or other files.Using oorestore with -dumpcatalog overwrites and then deletes anysystem-database and related files in the current working directory.

EXAMPLE This example displays global-catalog information for the mfgFd federateddatabase from the specified point of restore.

oorestore -time 200102060330 -source /fdb/backups-dumpcatalog mfgFd

If a Restore Fails

A restore operation may fail in any of the following circumstances:■ If the intended locations for the restored files are inaccessible.■ If any of the required backup files cannot be found.■ If you run oorestore in a directory that contains the backup boot file. This

restriction safeguards the backup boot file from possibly being overwrittenby a restored version of the file.

The oorestore tool cannot recover from errors that occur during itsexecution—for example, if backup volumes cannot be located or if a destinationdirectory does not exist. If a restore fails at any time during the restore process,you must restart the restore. However, a failed restore can leave behind both filesand locks. Therefore, before you restart the restore, delete any files that wererestored before the failure occurred and restart the lock server.

DRAFTBackup and Restore Managing Backup History



Managing Backup History

You can display the backups for a federated database and delete unwantedbackups.

Displaying Backup History

You can list some or all of the backups for a specified federated database. To doso, you use ooqueryset (page 265).■ If you have taken basic backups, you can specify the -time option to display

information about the latest full backup started on or before the specifiedtime, along with any incremental backups based on it.The value of the -time option is an integer YYYYMMDDHHmm containing up to12 digits that represent component times; for details, see “Specifying thePoint of Restore” on page 116.

■ If you have created explicit backup sets for a customized system of backups,you can specify the -set option to display information about the backups inthe specified set.

■ You can omit both the -time or the -set option to display informationabout all basic and customized backups.

You can execute this command when a lock server is not running or to bypass arunning lock server; to do so, use the -standalone option.

Deleting Unwanted Backups

You can delete an unwanted backup set and the corresponding information inthe backup diary. To do this, you use oodeleteset (page 219), with the -setoption specifying the name of the set to be deleted.

If you want to delete a basic backup, you must first use ooqueryset to get thename of the implicitly created backup set containing the backup.

For consistency, you may delete only entire backup sets, not individual backupsin a set.

DRAFTBackup and Restore Processing Backup Files



Processing Backup Files

You can run custom programs or shell scripts to pre- or post-process backup fileswhile a backup or restore is in progress. To do this you run oobackup (page 190)and oorestore (page 267) with various -procfiles options followed by thename of your program or shell script.

Although you can use this feature with any program or shell script you choose,the most common application involves conserving disk space by:■ Compressing backup files as oobackup produces them■ Uncompressing backup files before oorestore reads them and

recompressing them after oorestore restores them

Another common use for pre- and post-processing is to back up to and restorefrom tape. This conserves disk space by temporarily storing only one backup fileat a time. On UNIX systems, you should initially use the provided direct-to-tapebackup scripts. Later you may want to write customized scripts. On non-UNIXsystems, you need to write your own scripts for backing up to and restoring fromtape.

Your custom program or script should exit with a value of zero upon successfulcompletion, and nonzero otherwise. oobackup and oorestore terminate withan error message if the system call to run the program or shell script returns anonzero value.

Processing Backup Files During a Backup

To run a program or script after oobackup completes writing each backup file,you use oobackup with the -procfiles option followed by the program orscript name. During the execution of oobackup, the name of the file just writtenand the total size in bytes of the backup files written so far are passed to theprogram or script as command-line arguments.

Processing Backup Files During a Restore

To run a program or script before oorestore opens each backup file for restore,use oorestore with the -procfilesbef option followed by the program orscript name. The name of the file about to be restored is passed to the program orscript as a command-line argument.

You can also run the same or a different program or script after oorestorefinishes restoring each backup file by using the -procfilesaft option followedby the program or script name. The name of the file just restored is passed to theprogram or script as a command-line argument.

DRAFTBackup and Restore Backing Up to and Restoring From Tape



EXAMPLE Assume that mycompress is a user-defined program that compresses a single file,and myuncompress is a user-defined program that uncompresses a single file.

The following command directs oobackup to compress each backup file as soonas it is produced:

oobackup -full -destination /fdb/backups-procfiles mycompress mfgFd

The following command directs oorestore to uncompress each backup filebefore it is restored and to recompress it after it is restored:

oorestore -time 200102060330 -source /fdb/backups-procfilesbef myuncompress -procfilesaft mycompress mfgFd

Backing Up to and Restoring From Tape

On UNIX platforms, Objectivity/DB provides a direct-to-tape backup and restorecapability using two driver programs (ootapebackup and ootaperestore),which run several Bourne shell scripts and either oobackup or oorestore.

The syntax and command-line options for ootapebackup and ootaperestoreare identical to those for oobackup and oorestore, respectively, except that the-procfiles options cannot be used directly with the driver programs.

Backing up to tape requires sufficient free disk space to hold each backup filefrom the time it is created to the time it is written to tape. If space is limited, youcan use ootapebackup with the -capacity option to decrease the size of thebackup files. (The default size is 1 MB.)

Configuring ootapebackup and ootaperestore

Before backing up to and restoring from tape, you must configureootapebackup and ootaperestore to fit your UNIX environment. To do this,you must modify the following shell scripts provided by Objectivity/DB:■ oobackf

■ ooendb

■ ooendr

■ oorestfa

■ oorestfb

■ oostrtb

■ oostrtr

DRAFTBackup and Restore Backing Up to Tape



These shell scripts (as well as oobackup and oorestore) must reside in adirectory in your path so that ootapebackup and ootaperestore can findthem.

Perform the following steps in each script:

1. Locate the configuration variables for your environment. These are definednear the beginning of each file between two comment blocks that delineatethe configuration section.

2. Set the variable dev equal to the pathname of the tape device. Note that thename of the tape device is not the same as the path to the disk directory wherethe backup files are stored temporarily, which is specified by the-destination, -source, or -device option to ootapebackup andootaperestore.

3. Uncomment the configuration information for your platform.

Backing Up to Tape

First, ootapebackup runs the Bourne shell script oostrtb to prepare the tapedevice for the backup. Next, ootapebackup runs oobackup, which creates aseries of backup files, writing each first to disk, then moving each to tape usingthe Bourne shell script oobackf. After oobackup finishes, ootapebackup resetsthe tape drive by invoking the Bourne shell script ooendb. If oobackup or one ofthe shell scripts terminates with an error, ootapebackup exits immediately.

When backing up to tape, you must place the backup files for all incremental andsubincremental backups on the same tape as the backup files for the associatedfull backup. If you are taking customized backups (where you specify your ownfilename prefixes), the prefixes for distinct backup events stored on the same tapemust be different.

EXAMPLE This command backs up the mfgFd federated database to tape.

ootapebackup -full -destination /fdb/backups mfgFd

Restoring From Tape

First, ootaperestore runs the Bourne shell script oostrtr to prepare the tapedevice for the restore. Next, ootaperestore runs oorestore with the-procfilesbef and the -procfilesaft options designating the oorestfband oorestfa shell scripts, respectively. During the execution of oorestore,each backup file is read unopened from tape to disk by oorestfb, restored byoorestore, and then removed from disk by oorestfa. After oorestore

DRAFTBackup and Restore Customized Backups



finishes restoring all files, ootaperestore resets the tape drive and cleans up byinvoking the Bourne shell script ooendr.

If oorestore or one of the shell scripts terminates with an error,ootaperestore exits immediately.

EXAMPLE The following command restores the mfgFd federated database from tape.

ootaperestore -time 200102060330 -source /fdb/backups mfgFd

Customized Backups

You can customize your backup scheme for more fine-grained administrativecontrol. A system of customized backups allows you to:■ Use up to ten backup levels■ Explicitly create and name any number of backup sets■ Explicitly associate each backup with a backup set■ Explicitly specify a naming prefix for sets of backup files

In contrast, a system of basic backups has up to 3 backup levels and relies onObjectivity/DB to create and name backup sets and files implicitly.

Backup Structures

Customized backups require you to manipulate lower-level administrativestructures explicitly. Consequently, you should become familiar with the termsin this section.

Backup Events and Backup Sets

An individual backup, regardless of its level, is called a backup event. Backupevents are grouped into backup sets for administration purposes. You can definethe semantics for your backup sets. For example, one backup set can represent anentire month of federated-database backup events.

The Objectivity/DB backup and restore tools require you to reference customizedbackup events by their encompassing set names. Each backup set must have aunique name and each backup event must have a unique name within the scopeof its encompassing set.

DRAFTBackup and Restore Backup Structures



Backup Medium and Backup Volumes

The backup medium is the medium used to store the physical backup of afederated database. Just as for basic backups, you can write backup files to yourdisk or to a tape (see “Backing Up to and Restoring From Tape” on page 124).

Each backup event is stored as one or more files, or backup volumes. When youinitiate a backup event, you specify both a volume name prefix and the backupvolume capacity. The name of each backup volume consists of the volume nameprefix plus a sequential numeric value. For example, if you assign the volumename prefix myVol, the Objectivity/DB backup tool assigns the first volume of afederated database backup the name myVol_1. If a second volume is generated,it is given the name myVol_2. Multiple volumes are generated only if the backupsize exceeds the backup volume capacity.

During a backup, you cannot append data to an already existing backup volume.Consequently, each backup volume contains data from at most one federateddatabase and at most one backup event.

Figure 9-1 shows the relationships among the backup medium, sets, events, andvolumes. Keep in mind that sets and events are only logical constructs. Thephysical entities are the medium and the volumes.

Figure 9-1 Backup Medium, Sets, Events, and Volumes

Disk Backup Medium

Backup Set s_1

Backup Event b_4

Backup Event b_1…

Volume v_3Volume v_2

Volume v_1

Backup Event b_3

Backup Event b_2

DRAFTBackup and Restore Backup Levels



Backup Levels

Objectivity/DB supports both full and incremental backups with a system of tenuser-specified backup levels. You specify the desired level of backup when you runthe Objectivity/DB backup tool.

During a full (or level-0) backup, the entire contents of a federated database arearchived to the backup medium. During an incremental backup (backup levels 1through 9), only a specific portion of the data is archived to the backup medium:those containers that have changed since the most recent lower-level backup.

Table 9-3 summarizes which containers are backed up at each backup level..

Table 9-4 shows which days’ changes are recorded in a 4-level series backups(assuming that the backups occur after business hours on the days indicated).

Table 9-3: Backup Levels

Use This Level To Back Up

0 Entire federated database (including all databases and all containerswithin each database regardless of whether they have beenupdated).

1 All containers updated since the most recent level-0 backup

2 All containers updated since the most recent backup of level-1 orlevel-0

3 All containers updated since the most recent backup of level-2,level-1, or level-0

n All containers updated since the most recent backup of level-n–1,level-n–2, …, or level-0

Table 9-4: Successive Backups Using a Combined Strategy


Sunday 0 Entire federated database

Monday 1 Monday

Tuesday 1 Monday and Tuesday

Wednesday 1 Monday–Wednesday

Thursday 2 Thursday

Friday 3 Friday

Saturday 3 Friday and Saturday

DRAFTBackup and Restore Full Restore



Basic and customized backup levels correspond as follows:■ A full backup (taken with -full) and is internally a level 0 backup.■ An incremental backup (taken with -incremental) and is internally a

level 3 backup.■ A subincremental backup (taken with -subincremental) is internally a

level 6 backup.

Full Restore

Objectivity/DB always restores an entire federated database to guarantee thereferential integrity of the relationships (associations) between databases and thelogical integrity of the data within and across databases. Consequently,specifying a backup event whose level is greater than 0 as the point of restorecauses Objectivity/DB to restore multiple backup events, including the point ofrestore itself, the last full backup before the point of restore, and any relevantintermediate backups.

Defining a Backup Schedule For 10 Backup Levels

When developing a backup schedule for up to 10 backup levels, use theguidelines in “Guidelines for Defining a Backup Schedule” on page 114.

Example Backup Schedules

Table 9-5 shows a sample schedule for a federated database that is updated dailyduring the week. The schedule reduces the risk of losing many days’ updates ifone of the backup volumes is damaged (This is because most modified containersappear on multiple backup volumes and because the number of events thatObjectivity/DB must access during a restore is minimized.) Depending upon thesize of the database, a level-0 backup could occur either at the beginning of eachmonth or at the beginning of each week.

Table 9-5: Backup Schedule Minimizing the Risk of Losing Data


Sunday 1 (or 0) Since last full backup (or full backup)

Monday 6 Monday

Tuesday 6 Monday–Tuesday

Wednesday 6 Monday–Wednesday

Thursday 6 Monday–Thursday

Friday 6 Monday–Friday

DRAFTBackup and Restore Defining a Backup Schedule For 10 Backup Levels



Table 9-6 shows a moderately low-risk backup schedule for an entire monthunder the assumption that archiving once a week to a previous level-0 backup istoo time consuming. In this example, the schedule in Table 9-5 has been modifiedso that Sunday backups archive only the previous week’s changes.

If user access is heavy at all times during weekday business hours, thenarchiving the updates occurring over smaller periods of time may be necessary inorder to decrease the time and space devoted to the weekday backups. Theschedule in Table 9-7 illustrates such a strategy.

This schedule entails more risk than the schedule presented in Table 9-5. Forexample, to restore from a backup performed on Tuesday, Wednesday, or

Table 9-6: Modified Low-Risk Backup Schedule Decreasing the Time Required to PerformSunday Backups


End of month 0 Full backup

Weekdays of 1st week (daily) 6 1st weekday–day of backup

1st Sunday 2 Since last full backup

Monday—Friday of 2nd week (daily) 6 Monday–day of backup

2nd Sunday 3 Since 1st Sunday

Monday—Friday of 3rd week (daily) 6 Monday–day of backup

3rd Sunday 4 Since 2nd Sunday

Monday—Friday of 4th week (daily) 6 Monday–day of backup

4th Sunday 5 Since 3rd Sunday

Table 9-7: Backup Schedule for a Heavily Used Federated Database


Sunday 1 (or 0) Since last full backup (or full backup)

Monday 2 Monday

Tuesday 4 Tuesday

Wednesday 6 Wednesday

Thursday 8 Thursday

Friday 2 Monday–Friday

DRAFTBackup and Restore Creating Backup Sets



Thursday, Objectivity/DB must access backup volumes from three (Tuesday) tofive (Thursday) backup events, as opposed to two for the schedule in Table 9-5.Moreover, until the Friday backup is complete, an updated container appears ononly one backup volume during the week.

To contrast the safety of the two schedules, consider the following scenario:■ Federated database corruption is detected during a failure of the Friday

backup.■ One of the Tuesday backup volumes is damaged.

For the schedule in Table 9-5, the restore from the Thursday backup event issuccessful. Only Friday updates are lost. For the schedule in Table 9-7, you mustrestore from the Monday backup. Updates made from Tuesday through Fridayare lost.

Creating Backup Sets

All backup events must be associated with a particular backup set. You canassociate a backup event with an existing backup set or you can create a newbackup set using oocreateset (page 215).

The name of each backup set for a particular federated database must be unique.The backup set information is maintained in the backup diary as part of thefederated database and is archived during each backup event to protect againstits accidental deletion or corruption.

EXAMPLE This command creates a backup set named septemberBackups in the federateddatabase named mfgFd:

oocreateset -set septemberBackups mfgFd

To execute this command when a lock server is not running or to bypass arunning lock server, you use the -standalone option.

See “Managing Backup History” on page 122 for information about displayingand deleting backup sets.

Performing a Customized Backup

You back up a federated database using the Objectivity/DB backup tool,oobackup (page 190), with options specifying where to store the physical backupand how to identify the backup for future reference. You must include thebackup set name, the backup event name, the volume name, and the fulldirectory pathname where the backup volumes are to be stored. When taking an

DRAFTBackup and Restore Restoring a Customized Backup



incremental backup (that is, a backup whose level is greater than 0), you mustplace it in the same backup set as the full (level-0) backup on which it is based.

You must specify the federated database’s backup boot file; see “Backup BootFile” on page 112.

EXAMPLE This command runs a full backup (level-0) of the mfgFd federated database to themfgset backup set and names the backup event weeklyBackup. The storagelocation for the backup volumes is indicated using the -device option followedby the pathname /dba/mfgFd/backups.

oobackup -set mfgset -backup weeklyBackup -volume vol020401-level 0 -device /dba/mfgFd/backups mfgFd

You can process files as you take a customized backup by adding the-procfiles option; see “Processing Backup Files During a Backup” onpage 123.

Restoring a Customized Backup

You restore a federated database by running oorestore (page 267) with optionsspecifying the point of restore. For a customized backup, these options are thebackup set name, the backup event name, the volume name, and the fulldirectory pathname. In all other respects, restoring a customized backup is thesame as restoring a basic backup; see “Restoring From a Backup” on page 116.

EXAMPLE This command restores the mfgFd federated database from the Monday backup,which is a member of the dailyBackups backup set. The restored files areplaced on the hosts and directories from which they were archived.

oorestore -set dailyBackups -backup Monday -volume fdbVol-device /fdb/backups mfgFd

This command restores the same federated database as the previous command,but restores it to the directory /mnt/newfdloc on host machine42.

oorestore -set dailyBackups -backup Monday -volume fdbVol-device /fdb/backups -newhost machine42-newdirectory /mnt/newfdloc mfgFd




This command restores the same federated database as the previous command.However, files that cannot be restored to their original locations are restored todirectory /mnt/newfdloc on host machine42.oorestore -set dailyBackups -backup Monday -volume fdbVol

-device /fdb/backups -newhost machine42-newdirectory /mnt/newfdloc -failonly mfgFd

This command restores the same federated database as the previous command,but restores its files to the locations specified in the mapping file /tmp/file.map(see the example on page 120). If a file is not specified in the mapping file, it isrestored to its previous location.

oorestore -set dailyBackups -backup Monday -volume fdbVol-device /fdb/backups -dbmap /tmp/file.map mfgFd

You can process files as you restore a customized backup by adding the-procfilesbef and -procfilesaft options, which are described in“Processing Backup Files During a Restore” on page 123.




135

<6/11/2003, 12:40 PM; /wrld/mnt09/pubs/working/admin/admRecoveryTasks.fm>

DRAFT

10Automatic and Manual Recovery

Recovery is the process of restoring a federated database to a consistent state aftera transaction fails to commit. Depending on the nature of the failure, recovery isperformed by the application that started the transaction or through one ofseveral automatic recovery mechanisms that you enable.

This chapter describes:■ General information about Objectivity/DB recovery mechanisms■ Enabling automatic recovery from application, client-host, and lock-server

failures■ Performing manual recovery when automatic recovery is not possible

You can also create a special-purpose recovery application using theObjectivity/C++ programming interface. For more information, seeObjectivity/C++ Programmer’s Guide.

About Recovery

Recovery is required in both of the following situations:■ A read transaction obtains locks then terminates without releasing the locks.■ An update transaction obtains locks, makes changes to data, and then

terminates without committing the changes and releasing the locks.

Objectivity/DB recovers a transaction by:■ Rolling back any uncommitted changes. This restores the federated database

to the logical state it was in before the transaction started. Objectivity/DBuses the information recorded in one or more journal files to roll backchanges.

■ Instructing the lock server to release all locks held by the transaction. (If thelock server has stopped, its locks are lost, so there are no locks to release.)

An executing Objectivity/DB application initiates recovery automaticallywhenever it aborts a transaction. An application may abort a transaction directly

DRAFTAutomatic and Manual Recovery Automatic Recovery From Application Failures



through a function call or indirectly through a signal or exception handler. Thus,if an Objectivity/C++ or Objectivity for Java application catches an interruptduring a transaction (for example, a user enters Control-c on UNIX), the defaultObjectivity/DB signal handler aborts the transaction and rolls it back. AnObjectivity/Smalltalk application must provide an exception handler that abortsthe transaction.

Sometimes a transaction terminates due to an application, client-host, orlock-server failure that does not result in an abort. For example, the failure mayproduce a signal or exception that the application cannot handle, or it maysimply stop execution, preventing the abort from taking place. After such afailure, recovery must be performed by an Objectivity/DB process other than theone that started the transaction.

You can enable various Objectivity/DB processes to initiate recoveryautomatically after application, client host, and lock-server failures, as describedin the following sections. When automatic recovery is enabled, manual recoveryis normally necessary only when an Objectivity/DB host becomes permanentlyinaccessible after a failure.

Automatic Recovery From Application Failures

Objectivity/DB applications can fail in a number of ways, leaving incompletetransactions on a federated database. Application failures can be caused by:■ A Windows application issuing an ExitProcess or TerminateProcess■ Quitting a debugging session during a transaction■ A UNIX SIGKILL signal, for example, from a kill -9 command

No special arrangement is required for the automatic recovery of incompleteread transactions; if a failed Objectivity/DB application leaves any incompleteread transactions, the locks from these transactions are released immediatelywhen the application’s connection to the lock server is broken.

You arrange for the automatic recovery of incomplete update transactions byenabling your Objectivity/DB application to initiate recovery at the start of itsfirst transaction. Thus, if your application fails and leaves update transactionsincomplete, you simply restart the application to trigger automatic recovery.Recovery must be explicitly enabled in your application’s code; for information,see the documentation for the appropriate Objectivity programming interface.

A recovery-enabled application recovers more than just its own incompletetransactions. The first time a recovery-enabled application tries to open afederated database, Objectivity/DB determines whether incomplete transactionshave been left on that federated database by any applications that are known tono longer be active. If so, Objectivity/DB automatically rolls back the leftover

DRAFTAutomatic and Manual Recovery Automatic Recovery From Client-Host Failures



transactions before opening the federated database. Thus, if severalObjectivity/DB applications fail, leaving incomplete transactions on the samefederated database, all of the transactions are recovered by the firstrecovery-enabled application to be (re)started after the failures. This applicationmay, but need not, be started on the same client host as the failed applications.

Unrecovered transactions may prevent still-active applications from accessingobjects in the same federated database. If a recovery-enabled application cannotbe started in a timely fashion, or if your applications are not recovery-enabled,you should perform manual recovery; see “Manual Recovery From ApplicationFailures” on page 144.

Automatic Recovery From Client-Host Failures

Client hosts can fail in ways that prevent an application’s exit or terminationsignal from being caught—for example, when:■ The client host’s operating system fails.■ The client host loses power.■ The network connection between the client host and the lock server fails.

When a client host fails in one of these ways, Objectivity/DB applicationsrunning on the host may leave incomplete transactions on one or more federateddatabases.

You can arrange for automatic recovery from client-host failures using one ormore of the following techniques:■ You can enable the lock server’s recovery monitor, which periodically tests for

client-host failures, and then recovers any transactions that originated on afailed host; see “Enabling the Lock Server’s Recovery Monitor” on page 138.

■ You can configure each client host so that it runs a recovery toolautomatically after restarting; see “Configuring a Client Host to PerformRecovery” on page 139.

■ You can run one or more recovery-enabled Objectivity/DB applications on aclient host after it restarts; see “Automatic Recovery From ApplicationFailures” on page 136.

Unrecovered transactions can prevent any active applications from accessingobjects in the same federated database. If you choose not to enable the lockserver’s recovery monitor and you are not able to restart a failed client host in atimely fashion, you should perform manual recovery; see “Manual RecoveryFrom Client-Host Failures” on page 145.

DRAFTAutomatic and Manual Recovery Enabling the Lock Server’s Recovery Monitor



Enabling the Lock Server’s Recovery Monitor

If you are using a standard lock server (not an in-process lock server), you canenable its recovery monitor to initiate recovery from client-host failures. Arecovery monitor is a thread within a standard lock server that periodicallyidentifies all transactions against a particular federated database and checkswhether the processes that started these transactions are on client hosts that arestill operational. The recovery monitor performs its checks by attempting tomake a network connection to each client host and then waiting for a responsewithin a specified timeout period. If a client host does not respond for any reason(for example, due to machine or network problems), it is assumed to have failed,and all transactions started by its processes are automatically recovered.

Enabling a recovery monitor is recommended whenever multiple applicationsaccess the same federated database from multiple client hosts, particularly if thenetwork is unreliable. A recovery monitor can simplify system administrationtasks by reducing the need for immediate manual intervention whenever a clienthost fails.

You can enable a recovery monitor for only one federated database per lockserver. To enable a recovery monitor for a federated database:

➤ Start the standard lock server (see page 93), specifying both of the following:■ The -monitor option.■ The boot-file name of the federated database whose transactions are to

be monitored. If you are specifying multiple boot-file names as describedin “Performing Recovery at Lock-Server Startup” on page 141, only thefirst name is used by the recovery monitor.

To ensure that the recovery monitor can find and access all of the files of thespecified federated database, see “Guidelines for Lock-Server Setup” onpage 142.

By default, the recovery monitor tests each client host every 60 seconds and waits30 seconds for a response. You can adjust these times by specifying twoadditional options: -interval and -timeout, respectively.

EXAMPLE UNIX

This example enables the lock server’s recovery monitor for the federateddatabase myFD with an interval of 45 seconds and a timeout period of 35 seconds.

oolockserver myfd -monitor -timeout 35 -interval 45

DRAFTAutomatic and Manual Recovery Configuring a Client Host to Perform Recovery



Use the following guidelines when choosing a test interval and timeout period:■ The recovery monitor’s timeout period should be at least as long as the

network timeout period used by your applications; see “Lock-ServerTimeout” on page 99 and “AMS Timeout” on page 108.

■ The recovery monitor’s test interval and timeout period together should beshorter than the amount of time each application waits for lock requests to begranted (that is, the application’s lock-waiting timeout period).For example, assume your applications are programmed to wait at least twominutes to obtain locks. By default, the recovery monitor detects failed hostsand performs recovery every minute and a half (60+30 seconds), so stalelocks are released before lock requests from the applications time out.

A recovery monitor cannot guarantee that a client host has actually failed—onlythat the host has failed to respond within the specified time limit. Consequently,it is possible for the monitor to occasionally recover a transaction that belongs toan application that is still running. When this happens, the lock serverdisconnects from the application to prevent any further activity in thetransaction; an error is signaled in the application, which aborts the transaction.The application automatically reconnects to the lock server by starting a newtransaction.

Sometimes a recovery monitor cannot recover a transaction—for example,because a failed data-server host prevents access to the database files in whichchanges are to be rolled back. The recovery monitor makes no further attempt torecover such transactions, even while recovering other transactions left bysubsequent client-host failures. Any unrecovered transactions must be cleanedup manually when the necessary files are accessible again; see “PerformingManual Recovery” on page 143.

Configuring a Client Host to Perform Recovery

You can configure each client host to perform automatic recovery by runningoocleanup (page 206) after being restarted. The oocleanup tool causesObjectivity/DB to roll back any incomplete transactions that exist on thespecified federated databases. If the lock server is still running, the locks held bythese transactions are released. If the lock server is not running, the oocleanupcommand will fail because it requires the -standalone option to run without alock server; in this case, you can run oocleanup from a command prompt.

The following subsections describe how to configure Windows and UNIX clienthosts, respectively.

DRAFTAutomatic and Manual Recovery Automatic Recovery From Lock-Server Failures



Windows

You can configure a Windows client host to run oocleanup whenever a userlogs in:

➤ For each federated database that is accessed by applications running on theclient host, add the following command to the Startup program folder:oocleanup -local bootFilePath

If the client host is also the lock-server host, then rebooting the host restarts thelock server automatically as a Windows service. You should configure the lockserver to initiate recovery for every federated database accessed by anapplication that runs on the host; see “Performing Recovery at Lock-ServerStartup” on page 141. Adding oocleanup to the Startup program folder isredundant but not harmful.

UNIX

You can configure a UNIX client host to run oocleanup whenever the systemreboots:

➤ For each federated database that is accessed by applications running on theclient host, add the following command to the startup script (usually/etc/rc.local):oocleanup -local bootFilePath

If the client host is also the lock-server host, you should check whether the host’sstartup script runs the lock server:■ If the startup script runs the lock server, you should configure the lock server

to initiate recovery for every federated database accessed by an applicationthat runs on the host; see “Performing Recovery at Lock-Server Startup” onpage 141. You do not need to add the oocleanup command to the startupscript.

■ If the startup script does not run the lock server, you should either add thelock server to the script or add the oocleanup command with the -localand -standalone options.

Automatic Recovery From Lock-Server Failures

If a lock server or its host fails while transactions are in progress, the failureleaves incomplete transactions on one or more federated databases. You initiateautomatic recovery from lock-server failures by restarting the lock server. Theway you start the lock server determines when recovery is performed, asdescribed in the subsections below.

DRAFTAutomatic and Manual Recovery Performing Recovery at Lock-Server Startup



If a lock-server host becomes permanently inaccessible, incomplete transactionscannot be recovered automatically. To recover from this situation, see “ManualRecovery From Lock-Server Host Failures” on page 146.

When a lock server stops, the locks it manages are lost, so recovery just rolls backuncommitted changes. If uncommitted changes cannot be rolled back (forexample, because a data-server host is inaccessible), the lock server reestablishesthe appropriate locks.

Performing Recovery at Lock-Server Startup

If you are using a standard lock server (not an in-process lock server), you cancause automatic recovery to be performed immediately after the lock serverrestarts. To do this:

➤ Start the standard lock server with one or more boot-file names as arguments(see page 93).You can specify boot files for any or all of the federated databases that areserviced by the lock server. (If you also want to enable a recovery monitor fora particular federated database, the boot file for this federation must be listedfirst; see “Enabling the Lock Server’s Recovery Monitor” on page 138.)

When the lock server starts, Objectivity/DB rolls back all incomplete transactionson the specified federated databases. New transactions may experience a delayuntil recovery is complete.

If the lock server services multiple federated databases and you specify onlysome of them explicitly, the specified federated databases are recovered when thelock server is restarted. Each of the remaining, unspecified federated databases isrecovered the next time an application opens it for a transaction, as described in“Performing Recovery When Locks are Requested”, below.

Performing recovery at lock-server startup is recommended in a distributedenvironment because you can ensure that the lock server gets boot-filepathnames it can resolve; if the lock server cannot resolve a pathname, you getan error message when the lock server starts.

Performing Recovery When Locks are Requested

You can delay the automatic recovery of each serviced federated database untildata is requested from it. To do this:

➤ Start the standard lock server without specifying boot-file names (seepage 93) or start an in-process lock server (see page 94).

Recovery is initiated on a particular federated database when its boot-file name ispassed by the application to the lock server. Thus, the first time a federateddatabase is opened by an application after the lock server restarts,

DRAFTAutomatic and Manual Recovery Guidelines for Lock-Server Setup



Objectivity/DB rolls back any incomplete transactions on that federateddatabase. Recovery from the lock-server failure proceeds independently ofwhether recovery is enabled or disabled in the application.

Automatic recovery is performed only once per federated database during thelifetime of a particular lock-server process. If a federated database is recoveredwhen the lock server starts, the lock server will not recover the same federationagain when an application later opens it. (Subsequent recovery may beperformed by a recovery-enabled application, however.)

Guidelines for Lock-Server Setup

The following subsections provide guidelines for setting up the lock server sothat it can perform automatic recovery, either with or without an enabledrecovery monitor.

Access Required by the Lock Server

The lock server must be able to access all the files for each federated databasebeing serviced. Therefore, you must ensure that:■ The lock-server host can access all file systems containing the relevant files.■ The lock server has appropriate permissions to the relevant

files—specifically:❐ Read access to the boot file❐ Read and write access to the system-database and database files❐ Read and write access to the journal directory and journal files

Setting Up Recovery in Mixed Environments

The lock server must be able to resolve all boot-file pathnames that you specifyas arguments or that an application passes to it. (A boot-file pathname passed byan application is taken from the member function or method that opens thefederated database, and expanded, if necessary, to the form host::full_path.)

The lock server must be able to resolve the name of the federated database listedin each of the specified boot files, as well as the names of the database files listedin the federated database’s global catalog and journal directory.

In general, the lock server consults the local file system to resolve the names oflocal files (or remote Windows Network files referenced by UNC share names).The lock server contacts either AMS or NFS on remote hosts to find all otherremote files.

DRAFTAutomatic and Manual Recovery Performing Manual Recovery



When Objectivity/DB is distributed among network nodes running differentoperating systems, you should consider the following guidelines to enable thelock server to access all of the files it needs:■ Always start a standard lock server with one or more explicitly specified

boot-file pathnames. This way you can ensure that the lock server gets apathname it can resolve. Furthermore, if the lock server cannot resolve apathname, you get an error message when the lock server starts.

■ Set up all data servers to run either AMS or NFS.❐ If data servers run AMS (recommended), you can use host-specific

pathnames in your application and in the global catalog.❐ If data servers run NFS, you can use NFS pathnames uniformly in all

applications and in the global catalog.■ If you set up Windows data servers to use Windows Network without AMS

or NFS:❐ Run the lock server on a Windows node that recognizes the UNC share

names used by your Windows applications. Do not use a UNIX node asthe lock-server host because it will not be able to resolve the UNC sharenames.

❐ Be sure to start the lock server under a logon account that haspermissions to use the UNC share names.

Performing Manual Recovery

In rare circumstances, Objectivity/DB may not be able to recover a federateddatabase automatically. In these situations, you can recover a federated databasemanually using the procedures described in this section. Possible scenarios thatrequire manual recovery after a failure are summarized in Table 10-1.

Table 10-1: Manual Recovery Scenarios

Scenario Manual Recovery NeededSee

Page

An application fails, and automaticrecovery is not enabled in this application.

On the client host, run oocleanup with the-local option.

144

A client host with no Objectivity/DB filesbecomes permanently inaccessible orcannot be restored in a timely fashion.

On another host, run oocleanup with the-deadhost option.

145

The lock-server host becomespermanently inaccessible.

Run oocleanup with the -standalone option, orstart a new lock server on a host that you renamedto the hostname of the failed lock-server host.

146

DRAFTAutomatic and Manual Recovery Manual Recovery With oocleanup



Manual Recovery With oocleanup

In most manual recovery scenarios, you will run oocleanup (page 206), whichuses journal files to roll back the uncommitted changes made by incompletetransactions. If the lock server is still running, oocleanup also releases the locksheld by the incomplete transactions.

You must run oocleanup with a user identifier that has read access to the bootfile, and read/write access to:■ Journal files and the directories that contain them■ All system-database and database files

Whenever possible, you should run oocleanup on the same machine as theprocess that started the transaction to be recovered. This allows Objectivity/DBto verify that the process is no longer active, so it is safe to recover thetransaction. If the state of a process cannot be verified (for example, because itsclient host or network connection have failed), Objectivity/DB will not recoverany transaction started by that process without confirmation.

WARNING oocleanup may not successfully roll back a transaction if the transactionterminated while databases were being deleted. Under these circumstances, thefederated database may remain in an inconsistent state. Currently, the only wayto recover from such a situation is to restore the federated database from backuparchives.

Manual Recovery From Application Failures

If an application leaves incomplete transactions after terminating abnormally,you can initiate automatic recovery by starting a recovery-enabled applicationthat accesses the same federated database. If, however, automatic recovery is notenabled in any applications, or you cannot restart a recovery-enabled applicationin a timely fashion, you must manually recover the incomplete transactions.

A data-server host fails temporarily,preventing access to Objectivity/DB filesneeded for automatic recovery.

Run oocleanup with appropriate options after thedata-server host is restored.

144–146

A data-server host becomes permanentlyinaccessible.

Restore the federated database from a backuparchive.

116

Table 10-1: Manual Recovery Scenarios (Continued)

Scenario Manual Recovery NeededSee

Page

DRAFTAutomatic and Manual Recovery Manual Recovery From Client-Host Failures



NOTE If the application fails due to client host or network failures, you must recover itstransactions as described in “Manual Recovery From Client-Host Failures”below.

To manually recover all incomplete transactions started by applications that areknown to no longer be active, use oocleanup (page 206) with the -localoption. To manually recover a particular incomplete transaction, use oocleanupwith the -transaction option. (You can run oocleanup with just a boot-filename to obtain a list of incomplete transactions.)

EXAMPLE In this UNIX example, oocleanup recovers the transaction 357254 for thefederated database named mfgFD.

oocleanup -transaction 357254 mfgFD

oocleanup checks to make sure the process that owns the transaction isterminated before performing the recovery.

Manual Recovery From Client-Host Failures

Failure of a client host can cause Objectivity/DB applications to leave incompletetransactions. You normally arrange for automatic recovery from client-hostfailures by enabling the lock server’s recovery monitor. Or, you can set up clienthosts or Objectivity/DB applications to perform automatic recovery, so thatwhen a client host fails, you can initiate recovery by rebooting the host andrestarting its applications.

If the client host is permanently inaccessible (for example, due to a disk failure orother hardware problem), or if the client host cannot be rebooted in a timelyfashion, you can manually recover the incomplete transactions.

To manually recover all the incomplete transactions that originated on a failedhost, run oocleanup (page 206) on another host, specifying the failed host to the-deadhost option. To manually recover a particular incomplete transaction, youcan run oocleanup on another host, specifying the -transaction and-deadowner options.

NOTE If the client host becomes permanently inaccessible, and this host also containsObjectivity/DB files, recovery cannot roll back any updates to those files. Youmust restore the federated database from a backup archive; see “Restoring Froma Backup” on page 116.

DRAFTAutomatic and Manual Recovery Manual Recovery From Lock-Server Host Failures



Manual Recovery From Lock-Server Host Failures

If a lock-server host fails, but not permanently, you do not need to performmanual recovery. Instead, you should restart the lock server with one or moreboot-file names to trigger automatic recovery; see “Performing Recovery atLock-Server Startup” on page 141.

If a lock-server host becomes permanently inaccessible, you must recoverincomplete transactions manually. To recover when a lock-server host becomespermanently inaccessible, you:

1. Use oocleanup (page 206) with the -standalone option. This optionallows oocleanup to run without a lock server.Note: When a lock server stops, the locks it manages are lost, so recovery justrolls back uncommitted changes.

2. Change the lock-server host for the federated database (see page 96).3. If necessary, start the lock server on the new lock-server host (see page 93).

Alternatively, you can start a new lock server on a host that you have renamed tothe hostname of the failed lock-server host.

Manual Recovery From oocleanup Failures

Objectivity/DB allows only one recovery activity to occur against any givenfederated database at a time. To accomplish this, Objectivity/DB places a recoverylock on a federated database—each time a recovery operation is run, a file namedoorecvr.LCK is placed in the journal directory and is deleted when recovery iscomplete. While this file exists, all other attempts to run recovery against thesame federated database will fail.

If an oocleanup process fails, the oorecvr.LCK file may be left behind. Torecover from this failure, you delete this file by running oocleanup with the-resetlock option.

147

<6/11/2003, 12:40 PM; /wrld/mnt09/pubs/working/admin/admXmlTasks.fm>

DRAFT

11Exporting and Importing

Objectivity/DB enables you to export a federated database (or a portion of it) toan Extensible Markup Language (XML) document. Because an XML document isASCII text, you can read it to inspect the various exported structures. You canalso import the XML document into another federated database, which re-createsthe exported structures in the destination federated database. You can even usethird-party tools to transform the exported XML elements to an XML formatsuitable for importing into other applications.

This chapter describes:■ General information about exporting and importing■ Copying and merging federated databases■ Importing a group of databases■ Transferring or modifying a global catalog■ Synchronizing schemas■ Transferring data only

About Exporting

You can export all or part of an Objectivity/DB federated database to represent itsstructures textually in an XML document. Such an XML document consists of ahierarchy of XML elements corresponding to the hierarchy of structures in thefederated database. A federated database from which an XML document isproduced is called a source federated database.

Objectivity/DB Structures You Can Export

When an entire federated database is exported, the resulting XML documentcontains representations of:■ Data—The persistent objects stored by applications in the federated database.

Persistent objects are either basic objects (fundamental units of storage) or

DRAFTExporting and Importing XML Elements Representing Exported Structures



containers (objects that organize basic objects, clustering them together withindatabase files).

■ Schema—The portion of the federated database that describes the types ofdata that can be stored persistently in that federated database. The schemaconsists of descriptions of application-defined classes and descriptions ofinternal (Objectivity/DB-defined) classes.

■ Global catalog—The portion of the federated database that lists all of themember databases, their filenames and locations, and other properties. (HA)In a federated database with multiple autonomous partitions, the globalcatalog identifies the controlling partition of every database in the federation.When databases are replicated, the global catalog identifies the filename andlocation of each database image.

Data, schema, and global-catalog structures for an entire federated database aretypically exported together, but you can also export each type of structureindividually as indicated in Table 11-1:

You use ooexportfd for the most common tasks, and the other exportcommands for more specialized tasks.

XML Elements Representing Exported Structures

The exported Objectivity/DB structures are represented in an XML document asa hierarchy of XML elements. The set of possible XML elements and theirarrangement within an XML document are defined by the XML Schema forObjectivity/DB.

Table 11-1: Commands for Exporting Objectivity/DB Structures

Use this Command To Produce an XML Document Representing

ooexportfd (page 233) The data, schema, and global catalog of the sourcefederated database.

ooexportdata (page 228) Just the data of the source federated database; caninclude data from all databases, an individualdatabase, an individual container, or a basic object.

ooexportschema (page 237) Just the schema of the source federated database;can include descriptions of all application-definedclasses, all application-defined and internal classes,or just an individual class.

ooexportcatalog (page 225) Just the source federated database’s globalcatalog; can include all databases, autonomouspartitions, and database images, or just thedatabase images controlled by a particularautonomous partition.

DRAFTExporting and Importing XML Elements Representing Exported Structures



The XML Schema for Objectivity/DB is located in a subdirectory of yourObjectivity/DB installation directory (installDir):

Although the types of exported XML elements are specific to Objectivity/DB, thesyntax of these elements conforms to standard XML. Consequently, you can usethird-party XSLT tools to transform an Objectivity/DB XML document into XMLdocuments that conform to other XML Schemas.

Top-Level XML Elements

When you export an entire federated database, the resulting XML documentcontains the following hierarchy of top-level XML elements:

<ObjyXml><Fd>

<Schema>… 

</Schema><Catalog>

… </Catalog><Data>

… </Data>

</Fd></ObjyXml>

The XML document consists of the XML element <ObjyXml> … </ObjyXml>,which has a single child element <Fd> … </Fd> representing the federateddatabase. Within the federated database are nested XML elements representingthe three major exported structures (schema, global catalog, and data). Each ofthese XML elements in turn contains its own hierarchy of nested XML elements(not shown), representing the structure’s components.

If you use one of the commands in Table 11-1 to export just a portion of afederated database, no XML elements are generated for the nonexportedstructures. For example, if you use ooexportdata to export just the federateddatabase’s data, the resulting XML document contains no XML elementsrepresenting the schema or global catalog.

On Windows installDir\etc\Objy.xsd

On UNIX installDir/arch/etc/Objy.xsd, where arch is thesubdirectory for your UNIX architecture

DRAFTExporting and Importing Control Over Readability



Form of XML Elements

Most XML elements in an Objectivity/DB XML document consist of a start tag(for example, <Fd>) and an end tag (for example, </Fd>), which delimit nestedcontent (typically child XML elements). Some Objectivity/DB XML elementsconsist of a single tag because they have no nested content. Every XML elementhas a name (for example, Fd) and some elements may additionally includeattributes of the form attribute="value".

EXAMPLE This example shows two nested XML elements that have attributes.

…<Db systemName="SampleData" oid=”18-0-0-0"

isReadOnly="false" pageSize="8192">

<DbImage …host="machine22" file="F:\data\SampleData.TestFd.DB"… />

</Db>…

The element (<Db …> … </Db>) represents a global-catalog entry for a database.The attributes of this element (systemname=, oid=, and so on) generallyrepresent the database’s logical properties.

The child element (<DbImage …/>) consists of a single tag. The attributes of thiselement (host=, file=, and so on) generally represent the database’s physical(file-based) properties. (The representation of an unreplicated database has onlyone <DbImage …/> element; the representation of a replicated database hasmany such elements.)

NOTE The term attribute may be used in a number of distinct ways. In discussions ofdatabases or federated databases, an attribute is an alternative term for aproperty such as a system name. In discussions of XML elements, an attribute isa portion of a tag such as systemName=”SampleData”. In discussions ofpersistent objects, an attribute is a language-independent term for a C++ datamember, Java field, or Smalltalk instance variable.

Control Over Readability

An Objectivity/DB XML document typically serves as an intermediate form forimporting into another federated database or even into another application.However, because XML is a textual representation, you can also generate an

DRAFTExporting and Importing XML Files



XML document in order to read it—for example, to inspect the class descriptionsin a federated database’s schema.

The commands in Table 11-1 allow you to control the readability of the XMLdocuments they generate. By default, a generated XML document is fairlyreadable—for example, “white space” (line breaks and tabs) indicates thehierarchic relationship among XML elements. You can increase the readability ofan XML document by specifying command options such as the following:

Alternatively, if you do not need to read an XML document, you can condensethe document’s content by specifying command options such as the following:

You normally need to condense the output when exporting an entire federateddatabase.

XML Files

By default, each export command in Table 11-1 sends its output XML documentto stdout. Alternatively, you can use the -outfile option to request that thecommand save the XML document to an XML file (a file with the filenameextension .xml). Very large XML documents can be written to a series of XMLfiles that share a specified filename prefix. You can control the size and number ofXML files by specifying command options to condense the content of the XMLdocument (see “Control Over Readability” above), limit the size of each XML file(-maxfilesize), and compress each XML file (-compress).

Saving an XML document to one or more files causes a report file to be generated.The report file summarizes the number of XML elements of each kind in the XMLdocument.

Install File

When you export a global catalog (either by itself or in an entire federateddatabase), saving the resulting XML document causes a corresponding install fileto be created. An install file exposes the various customizable aspects of anexported global catalog, and is used to specify how the catalog is to be importedinto another federated database (see “Control Over Imported Catalogs” on

-verbose Generates “verbose” versions of XML elements, which contain moreinformation than the minimum used for importing.

-standardMaps Generates higher-level representations of certain Objectivity/DB datastructures (maps).

-nws Suppresses all white space.

-shortnames Abbreviates all XML element names.

DRAFTExporting and Importing About Importing



page 156). For example, you can edit an install file to specify a nondefaultfilename and location for each database being imported.

Each install file is created in the same directory as the XML file(s) containing thecorresponding exported global catalog. An install file is itself an XML filecontaining a second XML document whose top-level element is<ObjyInstall> … </ObjyInstall>.

About Importing

Importing an XML document into an Objectivity/DB federated databasepopulates the federated database with the structures represented in the XMLdocument. You use a single command—namely, ooimport (page 243)—toperform all Objectivity/DB import operations.

What You Can Import

You can import an XML document that represents any of the following:■ An entire source federated database (its data, schema, and global catalog)■ All the data from a source federated database, or just the data from a single

database■ An entire schema from a source federated database, or the just portion of the

schema containing descriptions of the application-defined classes■ All or part of a source federated database’s global catalog

The most common tasks call for importing an entire source federated database.

You typically import an XML document produced by one of the Objectivity/DBexport commands shown in Table 11-1. However, XML documents from othersources can be imported, provided they conform to the XML Schema forObjectivity/DB described in “XML Elements Representing Exported Structures”on page 148.

NOTE Although you can export just a single class description, a single container, or asingle object from a source federated database, you cannot import an XMLdocument that represents such a small increment unless you modify thedocument first. This book describes only operations that import the largerincrements listed above.

DRAFTExporting and Importing Destination Federated Database



Destination Federated Database

A federated database that is populated by importing is called a destinationfederated database. Any existing federated database can be the destination of animport operation. The destination federated database may be “empty” (newlycreated) or already populated with user-created databases, classes, and data.

A destination federated database requires no special preparation before animport operation is performed, unless you are importing an XML document thatrepresents only data (without any schema and global-catalog representations). Inthis case, the destination federated database must already have the databasesinto which the data will be written and a schema describing the classes of theimported data. If necessary, you must add the databases and schema to thedestination federated database prior to the import operation. See “TransferringData” on page 168.

What Import Operations Can Create

When you import an XML document into a destination federated database, theoperation interprets the document’s XML elements as instructions for creatingglobal-catalog components, schema components, or data in the destinationfederated database. Thus, an import operation creates:■ New databases (and possibly autonomous partitions and database images) in

response to any XML elements representing a source global catalog.■ New class descriptions in response to any XML elements representing a

source schema.■ New persistent objects (containers and their basic objects) in response to any

XML elements representing source data.

NOTE A new database is created in response to two different kinds of XML elements: aglobal-catalog element representing the database as a component of the globalcatalog, and a data element representing the database’s contents. Theglobal-catalog element instructs the import operation to create the database’sphysical file and logical entry in the destination global catalog. The data elementinstructs the import operation to populate the database with persistent objects.

Add-Only Policy

An Objectivity/DB import operation follows an add-only policy, which means itcan create new structures or add to existing ones, but it cannot change theproperties of, replace, or delete any existing structure. In some cases, an importoperation simply identifies a corresponding existing structure to use instead ofcreating a new one; in other cases, the import operation creates a new (possibly

DRAFTExporting and Importing What Import Operations Can Create



duplicate) structure. Thus, the exact results of a particular import operationdepend not only on the contents of the import XML document, but also on thecontents of the destination federated database, as described in the followingsubsections.

NOTE When global-catalog information is imported, the results are also affected by thecorresponding install file; see “Control Over Imported Catalogs” on page 156.

When the Destination is Empty

When you import an entire source federated database into an empty (newlycreated) destination federated database, the import operation completelyre-creates the source federated database. That is, the import operation is able tocreate every database, partition, application-defined class, and persistent objectthat is represented in the XML document, because the destination federateddatabase has no existing user-created structures to consider. The importoperation creates the represented databases and class descriptions first becausethe represented persistent objects depend on them.

When the Destination is Populated

When you import an entire source federated database into an existing, populatedfederated database, the import operation creates new components among theexisting ones, in effect, merging the source and destination federated databases.

When an import operation encounters a global-catalog element representing asource database, the operation checks whether the destination federated databasealready has an existing database with a matching system name. A new databaseis created only if no match is found.

When the import operation encounters a data element representing a sourcedatabase’s data, the operation again uses system names to determine where tocreate the represented data. By default, the import operation uses the systemname recorded with the source data to find a destination database in which tocreate the imported data. The found database may have been created earlier inthe import operation (and therefore empty) or one that existed before theoperation began (and possibly nonempty).

When creating data in a nonempty destination database, the import operationmerges it on a container-by-container basis. If a source container has a systemname recorded for it, the import operation looks up the container in thedestination database. If an existing container with a matching system name isfound, that container is populated with the source container’s contents;otherwise, a new container is created and populated.

DRAFTExporting and Importing Schema Compatibility



An import operation creates a new basic object in the destination container forevery basic object represented in the source container, even if the destinationcontainer already has existing objects in it. This is because the import operationhas no way to tell whether a source object “matches” any existing object. (Inparticular, object identifiers are not used for matching because they are normallyreassigned on import; see “Identifiers” on page 157.)

New classes are merged into a populated federated database only on request; see“Schema Compatibility” on page 155.

(HA) Imported autonomous partitions are merged with existing ones just likedatabases are merged—a new partition is created only if no existing partition hasa matching system name. If an imported partition’s system name matches that ofan existing partition, any database images controlled by the imported partitionare placed under the control of the existing partition.

Schema Compatibility

When you import an XML document that represents a schema (either by itself oras part of an entire federated database), the imported source schema must becompatible with the schema in the destination federated database. A source anddestination schema are compatible when the classes they have in common areidentical in all respects. An import operation checks for compatibility bycomparing the classes in the represented source schema to the classes in thedestination schema; whenever a source class has the same type number as adestination class, the two classes must also have the same name and members.

NOTE Schema compatibility is normally an issue only for application-defined classes.By default, Objectivity/DB internal classes are not exported, and so are not partof an imported source schema.

You can always import a source schema into:■ A newly created destination federated database. With no application-defined

classes in common, the source and destination schemas are completelycompatible, and all represented source classes are created in the destinationfederated database.

■ A populated destination federated database whose schema is identical to or asuperset of the source schema. In effect, the entire source schema is alreadypresent in the destination, so no new classes are created.

You use the -addnewclasses option to import a source schema into a populatedfederated database when the destination schema is a subset of the source schema.New class descriptions are created for any source classes not already in thedestination schema; see “Adding Classes to a Populated Schema” on page 167.

DRAFTExporting and Importing Control Over Imported Catalogs



Control Over Imported Catalogs

When you import an XML document that represents a global catalog (either byitself or as part of an entire federated database), the import operationpreprocesses the document’s global-catalog information by substitutingcorresponding information from the document’s install file; see “Install File” onpage 151.

As generated, an install file is a companion XML document whose elementsspecify the default values that will be used when new global-catalog componentsare created in the destination federated database. By default, for example, whenan import operation creates new databases, it retains their original filenames andsystem names, assigns each database the next available database identifier in thedestination federated database, and creates the new database files in thesystem-database directory of the destination federated database.

You can edit the install file to change the default properties for importedglobal-catalog components. In general, you do this by changing values inXML tags or attributes whose names start with the string Import or import.(XML tag names and attribute names starting with the string Export or exportshow the corresponding original values in the source global catalog.)

For example, you can edit the install file to perform the following tasks (see“Modifying an Imported Global Catalog” on page 162):■ Filter which databases are imported, causing the import operation to ignore

one or more represented databases (and their data).■ Change the system name of a represented database to control whether the

database is merged with an existing database.■ Specify nondefault database-file locations to control the distribution of data

in the destination file system.■ (HA) Change the configuration of autonomous partitions and replicated

databases.

An import operation consults an install file only if such a file exists in the samedirectory as the imported XML file and has the same filename prefix. If no installfile is found, default global-catalog properties are used.

Containment Hierarchy and Clustering

An Objectivity/DB import operation preserves the containment hierarchy ofbasic objects within containers and databases. Thus:■ Basic objects belonging to the same source container are clustered together in

the same destination container.■ Containers belonging to the same source database are created or merged

together in the same destination database.

DRAFTExporting and Importing Data Packing



Data Packing

Within each destination container, the imported basic objects are created inconsecutive slots on consecutive logical pages. Furthermore, if an imported basicobject has a variable part, such as the vector portion of a variable-size array(VArray), the variable part is placed near the rest of the object.

The import operation has the effect of repacking basic objects in each destinationcontainer, relative to their placement on logical pages in the source containers.Repacking can improve application performance by making storage (andtherefore object access) much more efficient. For example, objects in a containermay, over time, become separated by empty logical pages as other objects aredeleted; exporting the container and then importing it into a destination databaseeliminates the gaps by repacking the objects onto contiguous pages. Similarly,objects in a container may have VArrays that grow over time, causing the VArrayvectors to be relocated to other pages with more space; exporting the containerand then importing it into a destination database writes each object with itsentire VArray on contiguous pages.

NOTE Because of repacking, you can periodically export and import a federateddatabase just as you periodically tidy it. Importing repacks objects onto logicalObjectivity/DB pages, whereas tidying repacks logical Objectivity/DB pagesonto physical disk pages. See “Copying a Development Federated Database” onpage 159 and “Tidying a Federated Database” on page 53.

Identifiers

A database, container, or basic object created by an import operation rarely hasthe same identifier as the corresponding exported source structure. Instead, eachnew database, container, or basic object is normally assigned the next availableidentifier at its storage level within the destination federated database. Althoughan exported XML document includes identifiers in the representations ofexported objects, the exported identifiers serve only as guides for settingreference attributes and relationships (associations) among imported persistentobjects.

As described in “Referencing Objects in a Federated Database” on page 57,database identifiers and container identifiers are components of theobject identifiers (OIDs) of basic objects. When an imported database or containeris assigned its destination identifier, the OIDs of the contained basic objects areadjusted automatically.

You can preserve the original identifier of an imported database by explicitlyspecifying the desired identifier in the install file; however, the specified databaseidentifier must be unique within the destination federated database. Imported

DRAFTExporting and Importing Reference Attributes and Relationships



basic objects rarely retain the identifiers with which they were exported, even ifthe relevant database and container identifiers stay the same, because repackingnormally introduces different page and slot identifiers into the OIDs.

NOTE When an import operation adds new classes to a destination federated database,the new classes always keep the same identifiers (type numbers) they had in thesource federated database.

Reference Attributes and Relationships

Imported basic objects may be linked together through reference attributes orrelationships (associations); in both cases, the links are established by storedOIDs. When reference attributes and relationships exist among imported objectsthat have acquired new OIDs, the reference attributes and relationships that storethese OIDs are adjusted automatically.

Importing only part of a federated database can result in one or more externalreferences (a reference attribute or relationship that links an imported object to oneor more objects that are not being imported). For example, external referencescould occur if you import an XML document that represents an entire federateddatabase, but with an install file that filters out one or more databases.

By default, such import operations attempt to maintain referential integrity, soeach external reference is set to the OID it had during export, but only if thereferenced or related object exists in the destination federated database and is ofthe correct type. You can make a large import operation faster by specifying the-nullify option to it set all external references to null, or by specifying the-norefcheck option to suspend some of the validity checking. You should planto set or validate such references in a subsequent operation—for example, bycreating and running a custom application.

Multiple Passes

An import operation makes multiple passes through the destination federateddatabase—for example, one pass to create objects, another pass to set theirreference attributes and relationships, and so on. Changes are committed aftereach pass; in large import operations, changes may be committed several timesduring the same pass.

If an import operation reports an error and terminates before all passes arecomplete, the destination federated database may be left in an inconsistent state.In most cases, you can simply correct the error and then run ooimport again; theimport operation will pick up where it left off.

DRAFTExporting and Importing Copying a Development Federated Database



WARNING Always make a backup of the destination federated database before you performan import operation. A backup is essential because you cannot roll back anyportion of the import that has already been committed.

Copying a Development Federated Database

Copying a federated database with export and import operations creates asecond set of files with the same federated-database content, but differentproperties. You can create copies of federated databases for various developmentpurposes, such as:■ Supporting remote teams collaborating on the same suite of applications,

where identical federated databases with identical schemas are required.■ Changing a federated-database’s storage-page size while tuning application

performance.■ Repacking the objects in a federated database for more efficient storage.

To copy a federated database:

1. Run ooexportfd (page 233) with the path to the bootfile of the federateddatabase to be copied. Use the -outfile option to specify a prefix for theoutput XML file(s). If the federated database is large, use the -nws,-shortnames, and -compress options to condense the output.

2. If necessary, make the output XML files (including the install file) availablewherever the copy is to be located.

3. Run oonewfd (page 263) with appropriate options to create an emptyfederated database with the desired properties in the desired location. Thisstep determines the location of the copy’s system-database file and boot file.

4. Optionally edit the install file to specify any nondefault locations for the copy’sindividual database files. See “Specifying Filenames and Locations” onpage 164.(HA) If you are copying a partitioned federated database, and you want tore-create the autonomous partitions, you can optionally edit the install file toconfigure the partitions and any replicated databases.

5. Run ooimport (page 243) with the path to the new federated database’sbootfile. Use the -input option to specify the prefix of the XML files.(HA) If you are copying a partitioned federated database, and you do notwant to re-create the autonomous partitions, you can specify the-collapsepartitions option.

DRAFTExporting and Importing Merging Federated Databases



An alternative to the preceding technique is to copy and install a federateddatabase, as is recommended for distributing an existing federated database at anend-user site; see “Installing a Federated Database” on page 178. Copying andinstalling is generally faster, but these operations do not repack data or allow youto specify final file locations as part of the same operation.

Merging Federated Databases

Merging two federated databases with export and import operations creates newbasic objects, containers, and databases among existing ones in a destinationfederated database, as described in “When the Destination is Populated” onpage 154. You can merge federated databases for various purposes—for example,to propagate changes from a “master” federated database to members of adistributed development team or to update a federated database with datacollected in the other one.

You can merge federated databases only if their schemas are compatible; see“Schema Compatibility” on page 155.

WARNING Always make a backup of a federated database before you import into it.

To merge a source federated database into a destination federated database:

1. Run ooexportfd (page 233) with the path to the bootfile of the sourcefederated database. Use the -outfile option to specify a prefix for theoutput XML file(s). If the federated database is large, use the -nws,-shortnames, and -compress options to condense the output.

2. If necessary, make the output XML files (including the install file) availablewherever the destination federated database is located.

3. Optionally edit the install file to control how databases are merged; see“Renaming an Imported Database” on page 163. You can also specify databasefile locations (see page 164).(HA) If you are copying a partitioned federated database, and you want tore-create the autonomous partitions, you can optionally edit the install file toconfigure the partitions and any replicated databases.

4. Make a backup of the destination federated database.5. Run ooimport (page 243) with the path to the destination federated

database’s bootfile. Use the -input option to specify the prefix of the XMLfiles. Use the -addnewclasses option if you know that the source schemacontains classes that are not in the destination schema.

DRAFTExporting and Importing Importing a Group of Databases



Importing a Group of Databases

You can import a group of databases into a destination federated database—forexample, to create a partial copy of the source federated database or to merge aportion of the source into a destination federated database.

You can merge federated databases only if their schemas are compatible; see“Schema Compatibility” on page 155.

For the most consistent results, you should ensure that all reference attributesand relationships (associations) create links only among objects in the databasesbeing imported; see “Reference Attributes and Relationships” on page 158.


To add or merge selected databases from a source federated database into adestination federated database:

1. Run ooexportfd (page 233) with the path to the bootfile of the sourcefederated database. Use the -outfile option to specify a prefix for theoutput XML file(s). If the federated database is large, use the -nws,-shortnames, and -compress options to condense the output.

2. Find or create the destination federated database.3. If necessary, make the output XML files (including the install file) available

wherever the destination federated database is located.4. Edit the install file to filter out all databases except the ones to be added; see

“Filtering Out a Database” on page 163.You can optionally use the install file to specify database file locations (seepage 164) or adjust their system names to control merging (see page 163).

5. If the destination federated database is populated, make a backup of it.6. Run ooimport (page 243) with the path to the destination federated

database’s bootfile. Use the -input option to specify the prefix of the XMLfiles. Use the -addnewclasses option if necessary to add source classes to apopulated destination schema. Optionally use the -nullify or -norefcheckoption, depending on how you want to handle external references.

The preceding technique repacks the data in the imported databases, mergesimported containers with existing containers as appropriate, and creates anyneeded schema descriptions. As alternatives, you can:

■ Copy and attach databases, but only if you are adding (not merging) them toa federated database that already has an appropriate schema; see “Attachinga Database to a Federated Database” on page 81.

DRAFTExporting and Importing Transferring a Global Catalog



■ Export and import just the data from individual databases, but only if youare importing the data into a federated database that already has anappropriate schema and global catalog; see “Transferring Data” on page 168.

Transferring a Global Catalog

You can transfer a global catalog to a destination federated databases, either byitself or as part of an entire imported source federated database. Importing aglobal catalog creates the physical files and logical catalog entries for databases,autonomous partitions, and database images.

Duplicating Database Structure

You can import a global catalog by itself to duplicate a source federateddatabase’s organization into files:

1. Run ooexportcatalog (page 225) with the path to the bootfile of the sourcefederated database. Use the -outfile option to specify a prefix for theoutput XML file(s).

2. Run oonewfd (page 263) with appropriate options to create the destinationfederated database. This step determines the location of the copy’ssystem-database file and boot file.

3. If necessary, make the output XML files (including the install file) availablewherever the destination federated database is located.

4. Optionally edit the install file to:■ Specify any nondefault locations for the copy’s individual database files.

See “Specifying Filenames and Locations” on page 164.■ Specify the original identifier for each database; see “Specifying an

Imported Database’s Identifier” on page 164.5. Run ooimport (page 243) with the path to the destination federated

database’s bootfile. Use the -input option to specify the prefix of the XMLfiles.

The preceding technique is an alternative to creating empty databasesindividually; see “Creating a Database” on page 79.

Modifying an Imported Global Catalog

You can modify various aspects of an imported global catalog by editing thecorresponding install file; see “Control Over Imported Catalogs” on page 156. An

DRAFTExporting and Importing Filtering Out a Database



install file is generated automatically when you export a global catalog to anXML file.

An install file shares the same filename prefix as the corresponding XML file orfiles, and resides in the same directory. For example, when a global catalog isexported to an XML file called MyCatalog.xml, the corresponding install fileMyCatalogInstall.xml is generated in the same directory.

Filtering Out a Database

You can filter out one or more individual databases from the global catalogrepresented in an XML document. When you filter out a database, its XMLrepresentation is ignored, and the import operation proceeds without creating ormerging the database’s file or data.

To filter out one or more databases:

1. Open the appropriate install file in a text editor.2. For each database to be filtered out:

a. Find the <DbInstall … > tag whose exportSystemName= attribute isset to the system name of the unwanted database.

b. In the found tag, set the import= attribute to 'false'.You do not need to change any attribute of a nested <DbImageInstall …>tag unless the database is replicated and you are filtering out a particularimage.

3. Save the install file.

Renaming an Imported Database

You can change an imported database’s system name. By default, an importeddatabase keeps the system name of the exported source database. Renaming animported database affects how it is merged into a populated destinationfederated database, because the import operation uses the new system namewhen looking for an existing destination database with a matching system name.

To rename one or more databases:

1. Open the appropriate install file in a text editor.2. For each database to be renamed:

a. Find the <DbInstall … > tag whose exportSystemName= attribute isset to the database’s current system name.

b. In the found tag, set the importSystemName= attribute to the desiredsystem name.


DRAFTExporting and Importing Specifying an Imported Database’s Identifier



Any changed system names are automatically used throughout the XMLdocument being imported. For example, assume you edited an install file tochange a database’s system name from MyDB to YourDB, and you are importingthe corresponding XML document, where both the global-catalog componentand the data for MyDB are represented. The import operation will automaticallycreate (or find) a database called YourDB and place MyDB’s data in it.

Specifying an Imported Database’s Identifier

By default, an imported database acquires either an autogenerated identifier (if anew database is created) or the identifier of an existing database (if the databasesare merged). You can specify a nondefault identifier for a database that is newlycreated; the specified identifier must be unique among the database identifiers inthe destination federated database.

To specify a nondefault identifier for one or more databases:

1. Open the appropriate install file in a text editor.2. For each database to be given a new identifier:

a. Find the <DbInstall … > tag whose exportDbId= attribute is set tothe database’s current identifier.

b. In the found tag, set the importDBId= attribute to the desired identifier.3. Save the install file.

Specifying Filenames and Locations

By default, any files created by an import operation are placed in thesystem-database directory of the destination federated database. You can use aninstall file to specify nondefault file locations. Doing so enables you to:■ Arrange for the distribution of imported files in a single operation.■ Accommodate the import of a large federated database whose files won’t all

fit into a single directory.

To specify the file location of one or more databases:

1. Open the appropriate install file in a text editor.2. For each database to be relocated:

a. Find the <DbInstall … > tag whose exportSystemName= attribute isset to the database’s system name.

b. In the found tag, find the nested <ImportFile …> tag. Set the host=,dir=, and file= attributes to the desired hostname, directory path, andfilename, respectively.

If the database is replicated, find and edit the <ImportFile …> tag that isnested in the <DbImageInstall …> tag for the image to be relocated.

DRAFTExporting and Importing Configuring Partitions and Replicated Data




Configuring Partitions and Replicated Data

(HA) When you import a partitioned federated database, you can use the installfile to configure the properties of each autonomous partition—that is, to specifyeach partition’s system name, system-database file location, boot file location,lock-server host, journal directory and journal host. You can also change thecontrolling partition for one or more database images.

To configure autonomous partitions or replicated databases:

1. Open the appropriate install file in a text editor.2. For each autonomous partition to be configured:

a. Find the <ApInstall … > tag whose exportSystemName= attribute isset to the partition’s system name.

b. In the found tag, change properties or nested elements as desired:● Filter out the partition by setting the import= attribute to 'false'.● Change the partition’s system name by setting the

importSystemName= attribute to the desired name.● Change other properties by finding the corresponding nested

<Importxxx … > tags and replacing the default values with thedesired values. For example, to change the partition’s lock-serverhost, find the <ImportLockServer … > tag and replace the defaultvalue of the host= attribute with the desired hostname.

3. For each replicated database to be configured:a. Find the <DbInstall … > tag whose exportSystemName= attribute is

set to the database’s system name.b. In the found tag, find the nested <DbImageImport …> tag whose

exportAp= attribute is the system name of the controlling partition.c. Change the controlling partition by setting the importAp= attribute to

the system name of the desired partition.4. Save the install file.

NOTE When the source federated database is unpartitioned, the install file has a single<ApInstall …> tag representing the implicit initial partition. This element andthe partition it represents are ignored when the destination federated database isalso unpartitioned.

DRAFTExporting and Importing Synchronizing Schemas



Synchronizing Schemas

You can synchronize the schemas of two federated databases by exporting aschema from a source federated database and importing it into a destinationfederated database. A schema can be transferred either by itself or as part of anentire imported source federated database.

Duplicating a Schema

You can duplicate a schema by importing it into an empty federateddatabase—for example, as preparation for attaching a database or importing justthe data from a database.

To duplicate a schema an empty federated database:

1. Run ooexportschema (page 237) with the path to the bootfile of the sourcefederated database. Use the -outfile option to specify a prefix for theoutput XML file(s).

2. Run oonewfd (page 263) with appropriate options to create the destinationfederated database.

3. If necessary, make the output XML files available wherever the destinationfederated database is located.

4. Run ooimport (page 243) with the path to the destination federateddatabase’s bootfile. Use the -input option to specify the prefix of the XMLfiles.

This technique is an alternative to running the DDL processor ooddlx to includea schema defined in an Objectivity/C++ application. (See Objectivity/C++ DataDefinition Language for information about ooddlx.)

Checking for Identical Schemas

You can check whether the schemas of two populated federated databases areidentical:

1. Run ooexportschema (page 237) with the path to the bootfile of the firstfederated database. Use the -outfile option to specify a prefix for theoutput XML file(s).

2. Run ooimport (page 243) with the path to the second federated database’sbootfile. Use the -input option to specify the prefix of the XML files. Do notspecify the -addnewclasses option.

3. Repeat steps 1 and 2, with the federated databases reversed—that is, exportthe schema of the second federated database and import it into the first.

DRAFTExporting and Importing Adding Classes to a Populated Schema



If the schemas are identical, ooimport terminates normally in steps 2 and 3.Otherwise, ooimport reports an error and terminates if one schema is a supersetof the other, or if the two schemas are incompatible.

Adding Classes to a Populated Schema

You can transfer new classes from one populated schema to another, providedthe two schemas are compatible; see “Schema Compatibility” on page 155.

To ensure compatibility, you should adopt a policy of propagating new classes“in the same direction”—that is, new classes should always originate in aparticular source federated database and be imported into the same destinationfederated database(s). In general, you cannot mix classes of two independentlydeveloped schemas, unless there is absolutely no overlap among the typenumbers of the class descriptions.


To add classes from one populated schema to another:

1. Run ooexportschema (page 237) with the path to the bootfile of the sourcefederated database. Use the -outfile option to specify a prefix for theoutput XML file(s).


3. Make a backup of the destination federated database.4. Run ooimport (page 243) with the path to the destination federated

database’s bootfile. Use the -input option to specify the prefix of the XMLfiles. Use the -addnewclasses option to permit new classes to be added.

If the source and destination schemas are incompatible, ooimport reports anerror and terminates without adding classes. An error may indicate either of thefollowing:■ The source and destination schemas use inconsistent type numbers—for

example, due to independent development.■ Schema evolution has been performed in one of the schemas and the changes

need to be propagated to the other schema; see ooschemadump (page 272)and ooschemaupgrade (page 274).

DRAFTExporting and Importing Transferring Data



Transferring Data

You can transfer persistent objects to a destination database by importing anXML document that represents these objects (with no schema or global-catalogrepresentations).


To import an XML document that contains only data:

1. Create or generate an XML document representing the data you want toimport, and save this document in an XML file. For example, you can createthe XML document in either of the following ways:■ Transform the output of another application. The document must

conform to the XML Schema for Objectivity/DB.■ Run ooexportdata (page 228) with the path to the bootfile of the source

federated database. Use the -outfile option to specify a prefix for theoutput XML file(s). Optionally use the -id option to export just the datafrom a particular database.

2. Find or create the destination federated database.3. If the destination federated database is populated, make a backup of it.4. Ensure that the schema of the destination federated database describes every

class required by the imported data. If necessary, create or update thedestination schema; see “Duplicating a Schema” on page 166 or “AddingClasses to a Populated Schema” on page 167.

5. Ensure that the destination federated database has all the databases requiredby the imported data. If necessary, add one or more databases; see “Creatinga Database” on page 79 or “Duplicating Database Structure” on page 162.Hint: To check for required databases, search for the <DbData … > tags inthe XML document. The systemName= attribute in each tag specifies thesystem name of a database in which data will be written.


7. Run ooimport (page 243) with the path to the destination federateddatabase’s bootfile. Use the -input option to specify the prefix of the XMLfiles.

169

<6/11/2003, 12:40 PM; /wrld/mnt09/pubs/working/admin/admMixedOS.fm>

DRAFT

12Working With Distributed Databases

You can distribute an Objectivity/DB system among the nodes in various kindsof network environments. This chapter provides information you shouldconsider when setting up a distributed Objectivity/DB system, including:■ Elements of a distributed environment■ Considerations for using Windows hosts■ Summary of Objectivity/DB usage in a mixed network environment

Elements of a Distributed Environment

When you distribute Objectivity/DB applications and databases in a networkenvironment, you make choices about where to put various Objectivity/DBelements. This chapter uses the following terms to refer to the various nodes in adistributed Objectivity/DB system:

Accessing a database or federated database across a network may addsignificantly to response time because of network overhead and contention.Regardless of the size and configuration of a database, an application’s speed islikely to improve significantly if you store databases locally to your application.

For information about specifying local and remote Objectivity/DB files, see“Specifying Remote and Local Files” on page 33.

Client host Network node that runs an Objectivity/DB application;sometimes called an application host

Data-server host Network node that provides data storage; location ofsystem-database, database, and journal files

Lock-server host Network node that runs an Objectivity/DB lock server

DRAFTWorking With Distributed Databases Using Windows Hosts



Using Windows Hosts

You can run Objectivity/DB applications on a TCP/IP network that includesnodes running the various supported Windows operating systems.

TCP/IP is included in Windows. See the Installation and Platform Notes forWindows for information about configuring TCP/IP in preparation forObjectivity/DB.

Windows Data-Server Hosts

Windows nodes can be data-server hosts for one or more Objectivity/DB files(system-database, database, and journal files). Various restrictions apply,depending on the kind of client hosts you plan to use.

The way you share files determines how filenames should be specified to toolsand applications that access the federated database and update its global catalog.For information about the formats for specifying files on Windows data-serverhosts, see “Specifying Remote and Local Files” on page 33.

Serving Windows and UNIX Client Hosts

You can run either of the following on a Windows data-server host to makeObjectivity/DB files available to both Windows and UNIX client hosts:■ Objectivity/DB’s Advanced Multithreaded Server (AMS). AMS is required

for accessing replicated databases created with Objectivity/HA.

NOTE AMS is not supported on Windows 98.

■ Network File System (NFS). Call Objectivity Customer Support for a list ofNFS products that have been tested with Objectivity/DB.

Any Windows or UNIX client host can access Objectivity/DB files on AMS orNFS data-server hosts. AMS is recommended over NFS on Windows data serversbecause it improves update performance and it simplifies the specification ofpathnames for distributed Objectivity/DB files.

Serving Only Windows Client Hosts

If Objectivity/DB files will be accessed exclusively by applications on Windowsclient hosts, you can choose AMS, NFS, or Microsoft Windows Network to makethese files available from Windows data-server hosts. AMS is recommended overWindows Network because it simplifies the pathname specification forObjectivity/DB files.

DRAFTWorking With Distributed Databases Windows Client Hosts



Sharing Files Using UNC Names

If you choose to use Windows Network to share Objectivity/DB files residing onWindows data-server hosts, you must refer to these files using Universal NamingConvention (UNC) network share names. You may not use virtual drivemappings. UNC names are of the form \\host\sharedDirectoryName\path.

When you use UNC names in a tool or application, you must also specify the filehost using the literal string oo_local_host (see page 36).

When specifying names to be entered in the global catalog (for example,system-database names, database names, or journal-directory names), you maynot mix UNC share names with non-UNC names. If any such name is specifiedas a UNC share name, you must specify all names that way, even if you arerunning AMS or NFS in addition to Windows Network.

Windows Client Hosts

You can run Objectivity/DB database applications on Windows nodes.

Access to Data-Server Hosts

Applications running on a Windows client host can access data on:■ Any kind of data-server host running AMS or NFS■ A Windows data-server host running Windows Network instead of AMS or

NFS

Restriction on Windows Applications Accessing NFS

Every application that accesses an NFS data-server host from a Windows clienthost has a user ID of 100. You must ensure that user 100 has the desired accesspermissions for Windows client host access.

Lock-Server Hosts

You can run the lock server on a Windows or a UNIX node.

NOTE The lock server is not supported on Windows 98.

When Objectivity/DB is distributed among network nodes running differentoperating systems, you should follow the guidelines for locating the lock serverin “Setting Up Recovery in Mixed Environments” on page 142. These guidelinesenable the lock server to access Objectivity/DB files when performing automaticrecovery.

DRAFTWorking With Distributed Databases Boot-File Location



Boot-File Location

Database applications and lock servers use boot files to find a federateddatabase’s (or autonomous partition’s) system-database files. In principle, onlyone boot file is necessary per federated database or partition. However, innetworks that contain multiple client hosts, it is sometimes convenient tomaintain several copies of the boot file, one on each client host. This allows eachapplication to use a local copy of the boot file.

WARNING If you use the oochange tool to change federated-database properties, thechanges are written only to the boot file you specify to the tool. It is yourresponsibility to copy the boot file and distribute the copies after such changes.

Mixed Environments: Summary

Table 12-1 summarizes the possible combinations of platforms (Windows andUNIX) in a mixed Objectivity/DB environment. Use this table to chooseappropriate hosts for Objectivity/DB applications, lock servers, and files(system-database, database, and journal files).

When creating files that will be listed in a federated database’s global catalog, besure to use the host and path formats specified in the table for each particular fileserver platform.

Table 12-1: Mixed Environment Platform Combinations

Data-Server Hosts Catalog Entry FormatAllowed

Client Hosts

AllowedLock-Server

Hosts

Windows using AMSa

a. AMS is recommended.

host, c:\pathName Any Anyb

b. In a mixed environment, you should enable automatic recovery by starting the lock server withthe boot file path as an argument. See “Setting Up Recovery in Mixed Environments” onpage 142.

Windows using NFSc

c. The pathname to access a file varies among NFS vendors.

host, /c/pathName Any Anyb

Windows usingWindows Network

oo_local_host,\\host\pathName

Windows only Windows only

UNIX using AMSa orNFS

host, /pathName Any Anyb

173

<6/11/2003, 12:40 PM; /wrld/mnt09/pubs/working/admin/admDeploy.fm>

DRAFT

13Deploying to End Users

Deploying an application is the process of making the application available to endusers. Deploying an Objectivity/DB application typically results in theproduction of distribution media containing an Objectivity/DB applicationexecutable, various runtime libraries and database administration tools, thefederated database to be used by the application, and an installation program.

Because Objectivity/DB applications vary widely, this chapter provides generalguidelines and topics for consideration, rather than prescribing a singledefinitive set of steps. In particular, this chapter describes:■ Building the application executable (C++ applications)■ Distributing appropriate Objectivity/DB executables■ Distributing appropriate Objectivity/DB and third-party libraries for

deployment on Windows and UNIX platforms■ Setting up the end-user site■ Installing a federated database

This chapter does not describe general deployment tasks, such as how to packagesoftware on a distribution medium or how to write an installation program.

Building C++ Applications for End Users

To build C++ applications for end users, follow the compiling and linkingguidelines described in the Installation and Platform Notes for your operatingsystem.

DRAFTDeploying to End Users Distributing Objectivity Executables



Distributing Objectivity Executables

You typically deploy an Objectivity/DB application with a number of additionalexecutables, generally including custom administration tools, redistributedObjectivity/DB administration tools, and redistributed Objectivity/DB servers. Ifyou plan to distribute any Objectivity executables, you must do so in accordancewith your Objectivity runtime-licensing agreement.

Executables You May Distribute

The table in “Reference Index” on page 182 lists executables for Objectivity/DBtools. Depending on your application’s requirements, you may redistribute thesetools except as noted in the table and summarized in the following sections. Youmay consider redistributing the Objectivity/DB executables for:■ Administrative tools■ The lock server■ The Advanced Multithreaded Server (AMS)

NOTE The lock server is not required for standalone applications (single-userapplications providing database access through a single thread). However, if youdo not deploy the lock server, you must guarantee that only one thread hasaccess to the federated database at any time, or data corruption may occur.

If the deployed application also uses:■ Objectivity/HA autonomous partitions, you should consider distributing

that product’s executables for tools that manage autonomous partitions.■ Objectivity/HA data replication, you must distribute the Objectivity/DB

executables for AMS, and you should consider distributing that product’sexecutables for tools that manage database images.

■ Objectivity for Java or Objectivity/Smalltalk, you should distribute theObjectivity for Java or Objectivity/Smalltalk garbage-collection tool.

Executables You May Not Distribute

Because you cannot license your end users for database development, you arenot permitted to distribute the Objectivity/DB executables for:■ Browsing a federated database: oobrowse, ootoolmgr■ Debugging a federated database: oodebug■ Creating a new federated database or schema: oonewfd, ooconfig, ooddlx■ Dumping or loading a federated database’s data: oodump, ooload

DRAFTDeploying to End Users Distributing Libraries (Windows)



Distributing Libraries (Windows)

For Deployed Applications

All Objectivity/DB applications deployed on Windows platforms are linkeddynamically with the Objectivity/DB kernel. This means all applications writtenusing the Objectivity/C++, Objectivity for Java, and Objectivity/Smalltalkinterfaces.

When deploying a dynamically linked Objectivity/DB application on a Windowsplatform, you must:■ Redistribute the Objectivity/DB DLL oodbxx.dll (the characters xx

represent version numbers). You must purchase a runtime license fromObjectivity to redistribute this library.

For Redistributed Objectivity Executables

Objectivity executables for tools and servers are dynamically linked with theObjectivity/DB kernel. Therefore, any Objectivity executables you redistributerequire the same DLLs used by deployed applications.

DRAFTDeploying to End Users Distributing Libraries (UNIX)



Distributing Libraries (UNIX)

For Deployed Applications

Most Objectivity/DB applications deployed on UNIX platforms are linkeddynamically with the Objectivity/DB kernel. These include:■ All applications written against the Objectivity for Java and

Objectivity/Smalltalk interfaces■ Dynamically linked applications written against the Objectivity/C++

interface

When deploying a dynamically linked Objectivity/DB application on a UNIXplatform, you must:■ Redistribute the shared Objectivity/DB library for the deployment

architecture. This library is provided in the installDir/arch/libdirectory of your Objectivity/DB development environment. Youredistribute this library under the terms negotiated in your Objectivityruntime-licensing agreement.

■ Ensure that the end-user environment has an appropriate C++ runtimelibrary. You normally do not need to redistribute this library, because it isusually provided with the operating system.

For Redistributed Objectivity Executables

Objectivity executables for tools and servers are dynamically linked with theObjectivity/DB kernel. Therefore, if you redistribute any Objectivity executableswith your application, you must:■ Redistribute the shared Objectivity/DB tools library for the deployment

architecture. This library has _tools embedded in its name and is providedin the installDir/arch/lib directory of your Objectivity/DBdevelopment environment. You redistribute this library under the termsnegotiated in your Objectivity runtime-licensing agreement.

■ Ensure that the end-user environment has an appropriate C++ runtimelibrary. You normally do not need to redistribute this library, because it isusually provided with the operating system.

DRAFTDeploying to End Users Setting Up the End-User Site



Setting Up the End-User Site

Setting up an end-user site for a deployed Objectivity/DB application is similarto setting up an Objectivity/DB development site. You may find it helpful toconsult the Installation and Platform Notes for the appropriate operating system.

Hardware Requirements

Before deploying your application, you should establish the hardwarerequirements through testing and performance tuning.

Software Requirements

The end-user environment must have Winsock-compatible TCP/IP softwareinstalled, even for standalone (single-user) Objectivity/DB applications. OnWindows platforms, Microsoft TCP/IP is normally installed with the operatingsystem.

If NFS has been chosen as the data-server software for accessing data on remoteWindows hosts, the end user may need to install separately purchased NFSsoftware on those hosts.

Objectivity/DB Setup (Windows)

You can create a setup program similar to the setup program used for installingObjectivity products (which is created with InstallShield). If you are installing thelock server or AMS at your end-user site, the appropriate executables (ools.exeor ooams.exe) must be installed as services. You can accomplish this using thestandard capabilities of a commercial setup product such as InstallShield. If youare creating your own setup program, you can use the Service Controller (sc)tool provided with the Windows Resource Kit.

Objectivity/DB Setup (UNIX)

When you install your application and any Objectivity executables on a UNIXplatform, you may need to perform additional setup steps:■ On some architectures, you may need to set environment variables to enable

redistributed Objectivity/DB tools to operate correctly in an end-userenvironment. See Installation and Platform Notes for UNIX.

■ If you are installing the lock server at the end-user site, see the steps forsetting up the lock server in Installation and Platform Notes for UNIX.

■ If you are installing AMS or using NFS at the end-user site, see the steps forsetting up data-server software in Installation and Platform Notes for UNIX.

DRAFTDeploying to End Users Installing a Federated Database



Installing a Federated Database

To install an existing federated database at an end-user site:

1. Use oocopyfd (page 213) to copy all the files of the federated database toone directory.

2. Copy the files to the distribution media (CD-ROM or tape) and distribute themto your end users. No preparation of the federated database is required for theinstallation procedure.

3. At the end-user site:a. Load all executables and libraries from the distribution media; install

and start the lock server.b. Load the federated database’s files from the distribution media and run

ooinstallfd (page 249) with the appropriate options.

The ooinstallfd tool requires that all database files be located in the samedirectory. When database files are very large, however, this may not be possible.In this case, you can run ooinstallfd with the -nocheck option. This allowsooinstallfd to run to completion, printing a warning for each database file itcould not locate. You must then update the global catalog for each of the missingfiles using oochangedb (page 197) with the -catalogonly option.

179


DRAFT

Part 2 REFERENCE

DRAFT



181

<8/7/2003, 5:32 PM; /wrld/mnt09/pubs/working/admin/admTools.fm>

DRAFT

14Tools

This chapter describes the Objectivity/DB administration tools. See:■ “Overview of Administration Tools” on page 26 for a summary of the kinds

of tasks you can perform using Objectivity/DB administration tools■ “Reference Index” on page 182 for an alphabetical list of tools■ “Reference Descriptions” on page 185 for complete syntax and usage

descriptions of tools

Tool Names

The names of the tools are the same on Windows and UNIX, with the exceptionthat the filenames of the executables have an extension (.exe) on Windows thatis not required on UNIX.

Tool Options and Arguments

The command-line syntax for most tools includes either or both of the following:■ Options, which modify the way the tool works. Syntactically, options are

characters prefixed with a hyphen and set off with spaces—for example,-help. Some options are followed by values—for example, -hosthostName.

■ Arguments, which specify values directly to the tool. For example, many toolsaccept a bootFilePath argument.

When specifying options for an Objectivity/DB tool, you need to type only asmany letters of the option as are necessary to identify it uniquely. This is also truefor the fixed values sometimes associated with a command name or option.

Most options and arguments to Objectivity/DB tools are case sensitive, usuallylower case. Be sure to type options and arguments using the correct case.

DRAFTTools Reference Index



Reference Index

Tool Brief Description

Objectivity/Assist Graphical tool for getting started quickly with Objectivity/DB.

ObjectivityNetwork Services

Starts Objectivity servers (on Windows).

objytool Starts administration tools (on Windows).

ooattachdb Attaches a database to a federated database.

oobackup Archives a federated database.

oobrowse Browses objects and types, and makes queries (on Windows).For development only; you may not redistribute.

oochange Displays or changes the properties of a federated database or autonomouspartition.

oochangedb Displays or changes the properties of a database or database image.

oocheck Checks the consistency of a federated database.

oocheckams Checks whether AMS is running on a system.

oocheckls Checks whether a lock server is running on a system.

oocleanup Rolls back transactions that have terminated abnormally.

ooconfig Creates a DDL processor for your compiler (Objectivity/DDL on UNIX only).For development only; you may not redistribute.

oocopydb Copies a database.

oocopyfd Copies a federated database.

oocreateset Creates a backup set for a federated database.

oodebug Provides commands for inspecting and editing a federated database.For development only; you may not redistribute.

oodeletedb Deletes a database from a federated database.

oodeletefd Deletes a federated database.

oodeleteset Deletes a backup set.

oodump Represents a federated database as a proprietary-format text file.For development only; you may not redistribute.

oodumpcatalog Lists all the files in a federated database.




ooexportcatalog Represents the global catalog of a federated database in an XML document.

ooexportdata Represents the data of a federated database as an XML document.

ooexportfd Represents an entire federated database as an XML document.

ooexportschema Represents the schema of a federated database as an XML document.

oofile Displays information about a database or federated database.

oogc Deletes unreferenced objects in a federated database (Objectivity for Java andObjectivity/Smalltalk only).

ooimport Populates a federated database with Objectivity/DB structures represented inan XML document.

ooinstallfd Installs a remote federated database.

ookillls Kills a lock server.

oolicense Displays or updates a federated database’s license.

oolistwait Lists waiting transactions.

ooload Populates a federated database with objects created from a proprietary-formattext file. For development only; you may not redistribute.

oolockmon Lists all processes and locks currently managed by a lock server.

oolockserver Starts a lock-server process for a federated database.

oonewdb Creates a new database in a federated database.

oonewfd Creates a new federated database.For development only; you may not redistribute.

ooqueryset Queries a federated database for existing backup sets.

oorestore Restores an archived federated database.

ooschemadump Writes a federated database’s evolved schema to a file.For development only; you may not redistribute.

ooschemaupgrade Applies an evolved schema to a federated database.

oostartams Starts the Advanced Multithreaded Server (AMS).

oostopams Terminates AMS.

oosupportinfo Displays configuration and environment information needed by ObjectivityTechnical Support.





ootidy Consolidates a fragmented federated database or database.

ootoolmgr Browses objects and types, and makes queries (on UNIX).For development only; you may not redistribute.


DRAFTTools Reference Descriptions



Reference Descriptions

Objectivity/AssistGraphical tool for getting started quickly with Objectivity/DB.

Discussion You can use Objectivity/Assist (Assist) to perform tasks such as:■ Creating a federated database.■ Creating, browsing, and changing the types in a federated database’s schema.■ Creating, browsing, and changing the data in a federated database.■ Listing a federated database’s physical components (files and servers) and

logical components (databases, containers, and persistent objects).

NOTE Assist is available on Windows platforms and on selected UNIX architectures.(A UNIX architecture arch has Assist if the Objectivity/DB installation directoryinstallDir/arch contains a subdirectory called eclipse).

Assist is a collection of plug-ins to the Eclipse Platform, a general-purposeintegrated development environment (IDE) that serves as a workbench forrunning tools from a variety of vendors. You start Assist by simply starting theEclipse Platform.

For convenience, you can install and use the Eclipse Platform that is providedwith Objectivity/DB. To start Assist on the installed Eclipse Platform:

➤ (On Windows) Click Start and point to Programs. In the Objectivitysubmenu, select Assist.

➤ (On UNIX) Enter the following command:installDir/arch/eclipse/eclipse

If your computer already has an Eclipse installation, you can use it instead of theone provided with Objectivity/DB. For information about configuring your ownEclipse for Assist, see the Objectivity/DB installation chapter of Installation andPlatform Notes for your platform.

The Objectivity/Assist welcome page displays a list of items that help you getstarted with Objectivity/DB. To request the Objectivity/Assist welcome page:

➤ Click Help > Welcome and then click Objectivity/Assist.

For complete information about the Eclipse Platform, use your Web browser tovisit the Web site www.eclipse.org.




Objectivity Network ServicesA graphical interface on Windows platforms for starting, stopping, andconfiguring Objectivity servers, such as the lock server and AMS.

Discussion To start the Objectivity Network Services tool:


Objectivity Network Services.3. See Appendix A, “Running Objectivity Servers on Windows,” for information

about using this tool.

objytoolA graphical interface on Windows platforms for starting administration tools.

Discussion To use ObjyTool:

1. In a command prompt, enter objytool.2. Click to open a menu of tools. For example:

■ To run a backup/restore tool, click Backup.■ To run an administration tool, click Administration.

3. Choose a tool from the menu.4. In the dialog box that appears, type the desired options and arguments for the

selected tool. For help with syntax, type -help in the dialog box. To save tooloutput to a file, select File > Save Buffer to specify the filename.

ooattachdbAttaches the specified database to a federated database.

ooattachdb([-host hostName] -filepath path -db dbSysName [-id dbId])

| (-dbmap mapFile [-catalogonly])[-readonly][-tidy][-standalone][-notitle][-quiet][-help][bootFilePath]




Options -host hostName

Data-server host of the database file to be attached. If you omit this option,the default host is:■ The current host, if -filepath specifies a local path.■ The host implied by -filepath, if an NFS mount name is specified.If -filepath specifies a Windows UNC share name, hostName is set to theliteral string oo_local_host; any value you specify is ignored.

-filepath path

Path (including the filename) to the database file to be attached. If the -hostoption specifies a remote system, path must be full, not relative. If path doesnot identify a valid database file on the specified host, ooattachdb reportsan error and terminates.

-db dbSysName

System name with which the database is to be attached. If a database withthis system name already exists in the federated database, the ooattachdbtool reports an error and terminates.

-id dbId

Integer identifier with which the database is to be attached (for example, 78).This option also accepts the identifier specified in D-C-P-S format (forexample, 78-0-0-0). The maximum database identifier is 65535.If a database with the specified identifier already exists in the federateddatabase, the ooattachdb tool reports an error and terminates.If you omit this option, the database is attached with its original identifier(that is, the identifier is obtained from the database file). If a database withthis identifier already exists in the federated database, a new identifier isgenerated for the attached database.

-dbmap mapFile

ASCII text mapping file that specifies a group of databases to be attached.This option replaces the -db, -id, -host, and-filepath options. Themapping file contains one line for each database to be attached. Each linemust have the following general format:destDbID destDbSys hostName filepath

wheredestDbID (Optional) Database identifier with which the database is to

be attached.destDbSys System name with which the database is to be attached.hostName Data-server host of the database file.filepath Path (including the filename) to the database file.




If you omit the destDbID for a database, the identifier is obtained from thedatabase file; if a database with this identifier already exists in the federateddatabase, a new identifier is generated for the attached database.If any filepath does not identify a valid database file on the specified host,or if any other error is detected in a mapping-file entry, ooattachdb reportsan error and terminates, and none of the databases are attached.

-catalogonly

Updates the federated database’s global catalog with minimal verification.Specifying this option can save time when you are attaching a large numberof databases in a single operation.When you specify this option, ooattachdb verifies that the specified fileexists, but does not check whether it is a valid database file. Furthermore:■ No indexes are updated with objects from the attached databases.■ No adjustments are made to the contents of the attached files, if any

database is attached with a new identifier.This option applies only when the -dbmap option is specified. You mustspecify each database’s original identifier explicitly as the destDbID in themapping file entries.Warning: Do not use the -catalogonly option if any database is beingattached with a new identifier. Doing so will make the objects in the attacheddatabase unusable.

-readonly

Attaches the database file as a read-only database. When a database isread-only, all requests for read locks are automatically granted and allrequests for update locks are automatically refused, independently of thelock server. You can omit this option to attach the database as a read-writedatabase. After the database is attached, you can change its access statususing oochangedb.

-tidy

Consolidates the disk space for each database that is being attached with anew identifier. Changing a database’s identifier increases the size of thedatabase due to adjustments made to object identifiers, references, and so on.This option minimizes the impact of these adjustments.

-standalone

Nonconcurrent mode. Use this option only if the lock server for the specifiedfederated database or autonomous partition is stopped. If the lock server isrunning, the tool reports an error and terminates.

-notitle

Suppresses the copyright notice and program title banner. Useful wheninvoking the tool from another tool or product.




-quiet

Suppresses all normal program output.

-help

Prints the tool syntax and definition to the screen.

bootFilePath

Path to the boot file of the federated database to which the database is to beattached. You can omit this argument if you set the OO_FD_BOOTenvironment variable to the correct path. (HA) Specify the boot file of theautonomous partition that is to control the attached database.

Discussion Objectivity/DB checks whether a valid database file exists in the specifiedlocation(s). It is your responsibility to ensure that the schema of the destinationfederated database is identical to (or a superset of) the schema of each databasebeing attached.

A database identifier is a component of the object identifiers (OIDs) of objects inthe database. By default, Objectivity/DB automatically adjusts the followingitems if you attach one or more databases with new database identifiers:■ The object identifiers of all objects within each attached database■ Any relationships (associations) within each attached database■ Any relationships (associations) that exist among a group of databases

attached through the -dbmap optionHowever, Objectivity/DB does not attempt to find and adjust references thatmay exist from objects in the destination federated database to objects in thedatabases being attached.

Warning: Such adjustments are not made if you specify the -catalogonlyoption, which prevents ooattachdb from opening any database files. Whenspecifying -catalogonly, you must ensure that every database is attached withits original identifier; otherwise, Objectivity/DB will not be able to find objects inthe attached database.

The adjustments made to accommodate a new identifier increase the database’ssize. Use the -tidy option to minimize the impact of these adjustments.

When you attach a database to a federated database that has indexes, and theattached database contains objects of an indexed class, ooattachdbautomatically updates all of the relevant indexes. Indexes are not updated whenyou specify -catalogonly.

See also oochangedboocopydb




oobackupArchives a federated database to a backup medium.

oobackup(([-full] | -incremental | -subincremental)

[-destination backupDirPath] )| (-set setName -backup backupName -volume volName

-device deviceSpecifier [-level backupLevel])[-capacity size][-quiet][-procfiles programName][-purgeAps][-standalone][-notitle][-help][bootFilePath]

Options -full

Take a full backup of the specified federated database. This is the default ifyou omit the backup-level options -full, -incremental, and-subincremental.This option may be used with the -destination option.

-incremental

Take an incremental backup of the specified federated database. Anincremental backup records all changes made since the most recent fullbackup.This option may be used with the -destination option.

-subincremental

Take a subincremental backup of the specified federated database. Asubincremental backup records all changes made since the most recentincremental backup.This option may be used with the -destination option.

-destination backupDirPath

Full path to the disk directory in which to write the backup files. The defaultis the current directory (the directory in which you are executing oobackup).This option may be used with the -full, -incremental, or-subincremental option.

-set setName

Name of the backup set that is to contain the backup event.This option must be used with the -backup, -volume, -device, and -leveloptions.




-backup backupName

Name of the backup event to be executed. The name must be unique withinthe scope of the backup set specified by setName.This option must be used with the -set, -volume, -device, and -leveloptions.

-volume volName

Volume name prefix. Each volume name consists of the volume name prefixplus a sequential numeric value. For example, if volName is myVol, the firstvolume of a federated database backup has the name myVol_1. The secondvolume has the name myVol_2. Multiple volumes are generated only if thebackup size exceeds the backup capacity value.This option must be used with the -set, -backup, -device, and -leveloptions.

-device deviceSpecifier

Full path to the disk directory in which to store the backup volumes. Forexample, if the value for deviceSpecifier is /dba/backups and the valuefor volName is fdb020492, then the actual disk filename for the first backupvolume is /dba/backups/fdb020492_1.This option must be used with the -set, -backup, -volume, and -leveloptions.

-level backupLevel

Backup level. Valid values are integers 0 through 9. The default level is 0,which executes a full backup.This option must be used with the -set, -backup, -volume, and -deviceoptions.

-capacity size

Capacity of each backup volume in kilobytes. The default is 1000 (1 MB).

-quiet


-procfiles programName

Full or relative path to the shell script or program to be executed after eachbackup volume is written.During the execution of oobackup, the name of the backup volume justwritten and the total size in bytes of the backup volumes written so far arepassed to the script as command-line arguments. If the script exits with anonzero status, oobackup reports an error and terminates immediately.




-purgeAps

(HA) Skips the system-database file of any autonomous partition other thanthe boot partition. This option enables you to back up the data in apartitioned federated database when some partitions are inaccessible.If you specify this option, oobackup must be able to access (at least) aquorum of partitions and quorum for each database. If you omit this option,oobackup must be able to access all partitions.If you specify this option on a full backup, then you must also specify theoption on all subsequent incremental backups and on oorestore.

-standalone

Nonconcurrent mode. Use this option if no lock server is running or tobypass a running lock server.Warning: Corruption can occur if concurrent access to the federated databaseis attempted while any process is using this mode.

-notitle


-help


bootFilePath

Path to the backup boot file for the federated database to be archived. Youcan omit this argument if you set the OO_FD_BOOT environment variable tothe correct path. You must use the same boot file when restoring thefederated database.

Discussion Depending on your requirements, you can perform:■ A basic backup, where you simply specify one of three backup levels (-full,

-incremental, or -subincremental) and the directory (-destination) inwhich to write the resulting backup files. Objectivity/DB automaticallygenerates the names of all backup files and other administrative structures. Ifyou omit all of the backup-level options, a full backup is taken.

■ A customized backup, where you can specify one of 10 backup levels(-level) and you must provide naming information for the backup files(-device and -volume) and other administrative structures (-set and-backup).

You can use a combination of basic and customized backups to archive a givenfederated database:■ A full backup (taken with -full) and is internally a level 0 backup.




■ An incremental backup (taken with -incremental) and is internally alevel 3 backup.

■ A subincremental backup (taken with -subincremental) is internally alevel 6 backup.

Some federated databases have multiple boot files—for example, a distributedfederated database may require multiple copies of the boot file. Similarly, in apartitioned federated database, each autonomous partition has its own boot file.When a federated database has multiple boot files, you must choose one specificboot file, called the backup boot file, to specify the federated database for bothbackup and restore operations.

If the size of the backup event exceeds the volume capacity, multiple backupvolumes with the same volume name prefix are generated.

You may perform only one backup on a federated database at a time. Theoobackup tool reports an error and fails if it is started while another oobackupprocess is running on the same federated database.

Warning: Do not run oobackup and either oogc or ootidy concurrently, becausethese tools may delete objects that oobackup references.

See also oorestore

oobrowseGraphical interface for browsing objects, browsing types, and making queries onWindows.

oobrowse[-standalone][bootFilePath]

Options -standalone

Nonconcurrent mode. Use this option if no lock server is running or tobypass a running lock server.

bootFilePath

Path to the boot file of the federated database to be browsed. If you omit thisargument, you can open the federated database from within the tool. (HA)You can specify the boot file of any autonomous partition.

Discussion See Chapter 4, “Browsing Objects and Types,” for information about using thebrowser.

See also ootoolmgr




oochangeLists and optionally changes the properties of a federated database or (HA) anautonomous partition.

oochange[-ap apSysName | -id apId][-lockserverhost newLockServerHost][-fdnumber newFdId][[-bootfilehost newBootFileHost]

-bootfilepath newBootFilePath][[-sysfilehost newFileHost] -sysfilepath newFilePath][[-jnldirhost jnlDirHost] -jnldirpath jnlDirPath][-offline | -online][-weight][-nowait | -standalone][-notitle][-quiet][-help][bootFilePath]

Options -ap apSysName

System name of the autonomous partition whose properties are to bechanged or listed.

-id apId

Integer identifier of the autonomous partition whose properties are to bechanged or listed (for example, 18).

-lockserverhost newLockServerHost

New lock-server host. (HA) Requires the -ap or -id option to change thelock-server host for an autonomous partition.

-fdnumber newFdId

New integer identifier for the federated database.

-bootfilehost newBootFileHost

New host for the boot file. To leave the host unchanged, omit both the-bootfilehost and -bootfilepath options.If you omit only the -bootfilehost option, the default host is:■ The host on which you are running this tool, if -bootfilepath specifies

a local path.■ The host implied by -bootfilepath, if an NFS mount name is specified.If -bootfilepath specifies a Windows UNC share name,newBootFileHost is set to the literal string oo_local_host; any value youspecify is ignored.




(HA) Requires the -ap or -id option to change the boot-file host for anautonomous partition.

-bootfilepath newBootFilePath

New path to the boot file on the designated host. To leave the pathunchanged, omit both the -bootfilehost and -bootfilepath options. Ifthe -bootfilehost option designates a remote system, newBootFilePathmust be full, not relative.(HA) Requires the -ap or -id option to change the boot-file path for anautonomous partition.

-sysfilehost newFileHost

New data-server host for the system-database file. To leave the hostunchanged, omit both the -sysfilehost and -sysfilepath options. If youomit only the -sysfilehost option, the default host is:■ The host on which you are running this tool, if -sysfilepath specifies a

local path.■ The host implied by -sysfilepath, if an NFS mount name is specified.If -sysfilepath specifies a Windows UNC share name, newFileHost is setto the literal string oo_local_host; any value you specify is ignored.(HA) Requires the -ap or -id option to change the file host for anautonomous partition.

-sysfilepath newFilePath

New path to the system-database file on the designated host. To leave thepath unchanged, omit both the -sysfilehost and -sysfilepath options.If the -sysfilehost option designates a remote system, newFilePath mustbe full, not relative.(HA) Requires the -ap or -id option to change the file path for anautonomous partition.

-jnldirhost jnlDirHost

New host for the federated database’s journal directory. To leave the hostunchanged, omit both the -jnldirhost and -jnldirpath options. If youomit only the -jnldirhost option, the default host is:■ The host on which you are running this tool, if -jnldirpath specifies a

local path.■ The host implied by -jnldirpath, if an NFS mount name is specified.If -jnldirpath specifies a Windows UNC share name, jnlDirHost is set tothe literal string oo_local_host; any value you specify is ignored.(HA) Requires the -ap or -id option to change the journal-directory host foran autonomous partition.




-jnldirpath jnlDirPath

New path to the federated database’s journal directory. To leave the pathunchanged, omit both the -jnldirhost and -jnldirpath options. If the-jnldirhost option designates a remote system, jnlDirPath must be full,not relative.(HA) Requires the -ap or -id option to change the journal-directory path foran autonomous partition.

-offline

(HA) Sets the status of the specified autonomous partition to offline. Requiresthe -ap or -id option.

-online

(HA) Sets the status of the specified autonomous partition to online. Requiresthe -ap or -id option.

-weight weight

(HA) New weight of the designated autonomous partition. weight must be apositive integer. If it is 0, oochange reports an error.You may not change the weight of a partition if doing so would eliminate thequorum of partitions.

-nowait

Instructs the tool to terminate immediately if the federated database or theautonomous partition (specified by the -ap or -id option) is being accessedby another process.

-standalone

Nonconcurrent mode. Use this option if no lock server is running. You mayalso use this option to bypass a running lock server when changing anyproperty except the lock-server host. In this case, the tool must be allowed tointeract with the original lock server, if it is still running.Warning: Corruption can occur if concurrent access to the federated databaseis attempted while any process is using this mode.

-notitle


-quiet


-help





bootFilePath

Path to the boot file of the federated database to be changed or listed. Youcan omit this argument if you set the OO_FD_BOOT environment variable tothe correct path. (HA) You can specify the boot file of any autonomouspartition; the -ap or -id option specifies the autonomous partition to bechanged or listed.

Discussion To list the current properties of a federated database, enter oochange with just thebootFilePath argument.

(HA) You must specify the -ap or -id option if the specified federated databasehas multiple autonomous partitions. For example, to list the current properties ofan autonomous partition, enter oochange with the -ap or -id option and thebootFilePath argument.

If you use the -bootfilepath argument to specify a new boot file location,oochange writes an updated boot file in the specified location. After oochangecompletes, however, the old boot file remains. You must delete the old boot fileusing the suitable operating system commands.

Warning: You must specify a fully operational federated database. If necessary,use ooinstallfd to install the federated database before you attempt to changeits properties.

See also oofile

oochangedbDisplays and optionally changes the properties of a database or an individualimage of a replicated database.

oochangedb-db dbSysName | -id dbId[-ap apSysName][[-host newDbHost] -filepath newDbFilePath [-catalogonly]][-movetoap newapSysName][-weight weight][-exists ask | delete | quit][-readonly | -readwrite][-standalone][-notitle][-quiet][-help][bootFilePath]




Options -db dbSysName

System name of the database to be changed. If you use this option, youcannot use the -id option.

-id dbId

Integer identifier of the database to be changed (for example, 78). This optionalso accepts the identifier specified in D-C-P-S format (for example, 78-0-0-0).If you use this option, you cannot use the -db option.

-ap apSysName

(HA) System name of the autonomous partition containing the databaseimage to be changed. This option is not required if there is only one image ofthe database.

-host newDbHost

New data-server host for the database file. To leave the host unchanged, omitboth the -host and -filepath options. If you omit only the -host option,the default host is:■ The host on which you are running this tool, if -filepath specifies a local

path.■ The host implied by -filepath, if an NFS mount name is specified.If -filepath specifies a Windows UNC share name, newDbHost is set to theliteral string oo_local_host; any value you specify is ignored.

-filepath newDbFilePath

New path (including the filename) to the database file. To leave the pathunchanged, omit both the -host and -filepath options. If the -hostoption designates a remote system, newDbFilePath must be full, notrelative.

-catalogonly

Updates the federated database’s global catalog, without physicallyrelocating the database file. This option is valid only in combination with the-host and -filepath options.

-movetoap newapSysName

(HA) System name of the new autonomous partition that is to control thedatabase. The oochangedb tool reports an error if the partition alreadycontains an image of the database.

-weight weight

(HA) New weight of the designated database image. weight must be apositive integer. If it is 0, oochangedb reports an error.




-exists ask | delete | quit

Action to take if the file specified by the -host and -filepath optionsalready exists.ask Prompts whether to overwrite the existing file. If the answer

is No, the program terminates. No is the default.delete Overwrites any existing file.quit Terminates without changing the database if the file currently

exists.The default value is ask.

-readonly

Changes the database to a read-only database. When a database is read-only,all requests for read locks are automatically granted and all requests forupdate locks are automatically refused, independently of the lock server.While a database is read-only, you can either read its contents or change itback to read-write. You must change the database back to read-write beforeyou can perform any other operations on it.(HA) If one image of a database is made read-only, all images areautomatically made read-only.

-readwrite

Changes a read-only database back to a read-write database. When adatabase is read-write, all lock requests are serviced by the lock server. Alldatabases are created as read-write databases.You can change a read-only database back to read-write only if noapplication or tool is currently reading either that database or any otherread-only database in the same federated database.(HA) If one image is changed back to read-write, all images are changed toback read-write.

-standalone


-notitle


-quiet





-help


bootFilePath

Path to the boot file of the federated database containing the database to becopied. You can omit this argument if you set the OO_FD_BOOT environmentvariable to the correct path. (HA) You can specify the boot file of anyautonomous partition.

Discussion To relocate the database file and update the global catalog, you use both the -hostand -filepath options. To update the global catalog without physicallyrelocating the database file, you use the -catalogonly option with the -host and-filepath options.

If a database is read-only, you must change it back to read-write with the-readwrite option before you can change any other properties. You can changea read-only database back to read-write only if no application or tool is currentlyreading either that database or any other read-only database in the samefederated database.

If you specify only the -db (or -id) and bootFilePath options, oochangedbprovides a report of the current properties.

See also ooattachdboofile




oocheckChecks the consistency of the specified federated database or a portion of it.

oocheck[-id oid | -db dbSysName [-cont contSysName] | -ap apSysName

| -jnl jnlFileName | -schema][-fd | -databases | -containers | -pages | -objects

| -relationships][-outfile filename [-exists ask | delete | quit]][-xml filename][-standalone][-verbose][-help]bootFilePath

Options -id oid

Identifier of the object to be checked. You can specify:■ The integer identifier of a database (for example, 78). This option also

accepts the identifier specified in D-C-P-S format (for example, 78-0-0-0).■ The object identifier in D-C-P-S format of a container (for example,

78-16-0-0), a page (for example, 78-16-43-0), or a basic object (forexample, 78-16-43-5).

This option checks the specified object, the objects that contain it, and anyobjects it contains.Omitting this option (and all its alternatives) allows the check to include alldatabases and their contents.

-db dbSysName

System name of a particular database to be checked. This option checks thespecified database and its contents.Omitting this option (and all its alternatives) allows the check to include alldatabases and their contents.

-cont contSysName

System name of a particular container to be checked. If you use this option,you must also use the -db option to specify the database that contains thiscontainer.This option checks the specified database, the specified container, and thecontainer’s contents.Omitting this option allows the check to include all containers within thespecified database.




-ap apSysName

(HA) System name of a particular autonomous partition to be checked.Specifying this option checks all databases with an image in the specifiedpartition, and the contents of those databases.Omitting this option (and all its alternatives) allows the check to include alldatabases and their contents.

-jnl jnlFileName

Filename of a particular journal file to be checked. Checking a journal fileensures that its contents can be read and interpreted by Objectivity/DB.Specifying this option causes other options to be ignored (except foroutput-related options).

-schema

Checks just the schema of the specified federated database. Checking aschema ensures, among other things, that its physical storage is intact andthat the definitions of all bidirectional relationships are complete.Specifying this option causes other options to be ignored (except foroutput-related options).

-fd

Performs top-level checking only. Specifying this option checks the structuresmaintained by the federated database, such as the global catalog,federation-wide indexes, and so on.Omitting this option (and all its alternatives) is equivalent to specifying-relationships.

-databases

Performs checking down to the database level. Specifying this option checks:■ The structures maintained by databases, such as database-wide indexes,

catalogs of containers, and so on.■ The structures indicated by the -fd option.Omitting this option (and all its alternatives) is equivalent to specifying-relationships.

-containers

Performs checking down to the container level. Specifying this option checks:■ The structures maintained by containers, such as page maps, free lists,

container-wide indexes, and so on.■ The structures indicated by the -fd and -databases options.Omitting this option (and all its alternatives) is equivalent to specifying-relationships.




-pages

Performs checking down to the page level. Specifying this option checks:■ Logical pages (for space usage, consistency with page maps, and so on).■ The structures indicated by the -fd, -databases, and -containers

options.Omitting this option (and all its alternatives) is equivalent to specifying-relationships.

-objects

Performs checking down to the basic-object level. Specifying this optionchecks:■ Basic objects (for existence, accessibility, valid attribute types,

consistency with the schema, and so on).■ Persistent collections (for well-formedness, valid references, and so on).■ The structures indicated by the -fd, -databases, -containers and

-pages options.Omitting this option (and all its alternatives) is equivalent to specifying-relationships.

-relationships

(Default) Performs checking down to the relationship (association) level.Specifying this option checks:■ Relationships and reference attributes (for validity and accessibility).■ The structures indicated by the -fd, -databases, -containers,

-pages, and -objects options.

-outfile fileName

Name of the file (including any filename extension) in which to write thegenerated report as ASCII text. You can omit this option to send all output tostdout. The generated report contains Objectivity/DB error messages anddescriptions of any found problems.


Action to take if the file specified with the -outfile option already exists.ask Prompts whether to overwrite the existing file. If the answer

is No, the program terminates. No is the default.delete Deletes any existing file.quit Terminates the program if the file currently exists.The default value is ask.




-xml

Name of the file (without any filename extension) in which to write anExtended Markup Language (XML) document containing representations ofany problematic objects. If you omit this option, no XML report is generated.

-standalone


-verbose

Includes additional detail in the generated report.

-help


Discussion This tool checks user-created structures as well as Objectivity/DB internalstructures in a federated database.

To check a portion of a federated database’s storage hierarchy, you can combineat most one option from each of the following groups:■ Use the -id, -db, or -ap option to select one or more branches of the storage

hierarchy for oocheck to traverse. Omitting these options selects allbranches—that is, all databases and their contents.

■ Use the -fd, -databases, -containers, -pages, -objects, or-relationships option to indicate the depth of checking along the selectedbranch(es). Checking starts at the federated-database level and proceeds tothe specified level. Omitting these options checks all levels, down torelationships.

In the following table, each valid combination of oocheck options is indicated bya check mark (✓ ).

-fd -databases -containers -pages -objects -relationships

-id basicObjectId ✓ ✓

-id pageId ✓ ✓ ✓

-id containerId ✓ ✓ ✓ ✓

-id dbId or-db dbSysName

✓ ✓ ✓ ✓ ✓

-ap apSysName ✓ ✓ ✓ ✓ ✓

(Default: all databases) ✓ ✓ ✓ ✓ ✓ ✓




To check the federated database’s schema, you specify the -schema option. Tocheck a particular journal file, you specify the -jnl option. You cannot combine-schema or -jnl with any of the options in the previous table.

oocheckamsChecks whether AMS is running on a particular data-server host.

oocheckams[hostName][-notitle][-quiet][-help]

Options hostName

Name of the data-server host to be checked for AMS. If you omit this option,the current host is checked.

-notitle


-quiet


-help


oochecklsChecks whether a lock server is running on a particular host system.

oocheckls[hostName][-notitle][-quiet][-help]

Options hostName

Name of the host system to be checked for a lock server. If you omit thisoption, the current host is checked.

-notitle





-quiet


-help


Discussion This tool checks whether the specified host is running either a standard lock server(which runs as a separate process) or an in-process lock server (which runs as partof an IPLS application process). The oocheckls output identifies the running lockserver by its process name; a standard lock server is identified as ools or ools-xx,where xx is a number.

oocleanupLists the active transactions for a federated database or autonomous partition;recovers the specified abnormally terminated transactions.

oocleanup[-local | (-transaction tId [-deadowner])

| -deadhost hostName ][-resetlock][-force][-standalone][-allpart | -onepart][-notitle][-help][bootFilePath]

Options -local

Recovers all transactions started by processes that are no longer active,provided oocleanup can verify the status of these processes. Transactionsare skipped if they belong to processes that are still active or whose statuscannot be verified.In general, oocleanup can directly verify the status of all local processes.However, the status of a remote process cannot be verified if either theremote host or its network link has failed. oocleanup with the -localoption therefore recovers only those transactions belonging to inactive localprocesses or to remote processes that disconnected from the lock server dueto application failure.If the lock server has failed (and the -standalone option is used), onlytransactions from local processes are recovered.

-transaction tId

Transaction identifier of a specific transaction to be recovered.




For safety, oocleanup checks the status of the process that started thespecified transaction. If the process is no longer active, the transaction isrecovered; otherwise, if the process is active or its status cannot bedetermined, oocleanup reports an error and terminates. (See also the-deadowner option.)

-deadowner

Used with the -transaction option; permits recovery of the specifiedtransaction regardless of the status of the process that started it.For safety, oocleanup checks the status of the process that started thespecified transaction. If the process is no longer active, the transaction isrecovered; otherwise, if the process is active or if its status cannot bedetermined, oocleanup displays a prompt asking you whether recoveryshould continue.Warning: You can corrupt the federated database by recovering a transactionthat belongs to an active process.

-deadhost hostName

Recovers transactions started by processes on the specified host, providedthe host is “dead” (has failed or lost its network link), so its processes are nolonger active.For safety, oocleanup attempts to contact the specified host to verify that itis dead. If the host responds instead of timing out, oocleanup displays aprompt asking you whether recovery should continue.Warning: Do not rely solely on this safety check to determine whether thespecified host is dead. You can corrupt the federated database by recoveringtransactions that belong to active processes.

-resetlock

Resets the recovery lock before recovering transactions. The -resetlockoption is required if a previous invocation of oocleanup terminatedabnormally while recovering the transaction. A prompt is displayed askingyou to confirm that the recovery lock should be reset.Warning: You can corrupt the federated database by using this option whena recovery lock belongs to a cleanup process that is still active.

-force

Used with the -deadowner, -deadhost, or -resetlock option; recovers therequested transaction(s) without prompting for confirmation.Warning: You can corrupt the federated database by recovering a transactionthat belongs to an active process.Because this option suppresses the display of any warning prompts, it isuseful when invoking the tool from a script or application.




-standalone


-allpart

Inspects the journal files of all autonomous partitions in the federateddatabase to identify the transactions to be recovered:■ When used with the -local or -deadhost option, -allpart causes the

recovery of all incomplete transactions against the entire federation.■ When used with the -transaction option, -allpart permits the

recovery of any incomplete transaction against the federation.Inspecting all journal files is time-consuming; if you know that only a smallsubset of partitions require recovery, you can save time by using the-onepart option to clean up each partition individually.This option should be considered only the federated database has multipleautonomous partitions.

-onepart

Inspects just the journal files of the autonomous partition specified bybootFilePath to identify the transactions to be recovered:■ When used with the -local or -deadhost option, -onepart causes the

recovery of just the incomplete transactions listed in the inspectedjournal files.

■ When used with the -transaction option, -onepart permits thespecified transaction to be recovered only if it is among those listed inthe inspected journal files.

Recovery may still affect other partitions—specifically, if a transaction hadupdated multiple partitions, the transaction’s changes are rolled back inevery affected partition. However, the journal files of other partitions are notinspected for transactions to be recovered, so transactions requiring recoverycould exist elsewhere in the federated database.If you know that only a small subset of partitions require recovery, you canuse this option to clean up each partition individually. This is faster thanusing -allpart to clean up transactions in all partitions; however, you mustdetermine which partitions require recovery and ensure that they arerecovered.This option should be considered only the federated database has multipleautonomous partitions.

-notitle





-help


bootFilePath

Path to the boot file of the federated database or autonomous partitionwhose transactions are to be listed or recovered. If you are recovering atransaction that holds locks in multiple autonomous partitions, you canspecify the boot file of any of these partitions. You can omit this argument ifyou set the OO_FD_BOOT environment variable to the correct path.

Discussion You can use oocleanup to accomplish these tasks:■ To display a list of active update transactions on a particular federated

database or autonomous partition, specify just the bootFilePath argument.■ To recover all incomplete transactions started by local processes that are no

longer active, use the -local option. (This option also recovers transactionsstarted by remote processes, but only if the status of these processes can beverified.) For a partitioned federated database, you can further control thescope of recovery by adding either the -allpart or the -onepart option.

■ To recover all incomplete transactions started by processes on remote hosts,run oocleanup -local on each host computer so the process status can beverified directly. If you cannot access a particular host computer (forexample, if it fails to reboot) and you know that the processes on it haveterminated, run oocleanup with the -deadhost option on any host.

■ To recover a specific transaction, use the -transaction option, possiblywith the -deadowner option.

■ To recover transactions while the lock server for bootFilePath is stopped,use the -standalone option along with any other required oocleanupoptions. Do not use -standalone while the lock server is running.

When the oocleanup tool recovers a transaction, it rolls back the transaction’suncommitted changes, restoring the federated database to the logical state it wasin before the transaction started. If a transaction left uncommitted changes inmultiple autonomous partitions, the changes are rolled back in all of theaccessible partitions. In particular, if the transaction left uncommitted changes ina replicated database, the changes are rolled back in all of the accessible images.

The oocleanup tool uses the journal files of the specified federated database orautonomous partition to identify the transactions to be listed or recovered. Whenjust the bootFilePath argument is specified, the oocleanup tool lists all activetransactions that opened the specified federated database or partition for update,including:■ Transactions started by local processes (local to the host on which you are

running oocleanup).




■ Transactions started by remote processes (running on a host other than thehost on which you are running oocleanup).

From this list of transactions, oocleanup with the -local option recovers alltransactions started by processes that are no longer running, provided that theirstatus can be verified by oocleanup. (The status of a remote process cannot beverified if either the remote host or its network link has failed.)

If bootFilePath specifies an autonomous partition, and the journal files for thispartition contain at least one incomplete transaction that affects another partition,then oocleanup inspects the journal files of all partitions in the federateddatabase; all incomplete transactions against the entire federation are recovered.Otherwise, if the specified partition’s journal files contain no multipartitiontransactions requiring recovery, then oocleanup recovers only the incompletetransactions affecting the specified partition. You can guarantee one behavior orthe other by specifying either the -allpart option or the -onepart option.

If the lock server for the specified federated database or autonomous partition isstill running, oocleanup causes it to release all locks held by the recoveredtransaction. If the lock server has stopped—or stopped and restarted—thetransaction’s locks are lost, so oocleanup just rolls back changes.

By default, oocleanup acquires a recovery lock to make sure that no recovery isbeing performed by another oocleanup process. If oocleanup fails to acquire arecovery lock, it reports an error.

ooconfigCreates a DDL processor that is compatible with your C++ compiler, deleting anyexisting DDL processor, on UNIX.

ooconfig [targetName]

Options targetName

Name of a supported target architecture for cross-development. OmittingtargetName produces a standard (native) DDL processor called ooddlx.

Discussion This tool creates an appropriate DDL processor for your UNIX architecture. TheDDL processor prepares source files and creates schemas for Objectivity/C++applications. For information about using the DDL processor, see Objectivity/C++Data Definition Language.

By default, ooconfig creates a standard DDL processor called ooddlx for nativedevelopment. Under native development, you run the DDL processor, compilethe resulting output files, link your application, and then run the resultingexecutable, all on platforms of the same architecture.




If targetName is specified, ooconfig creates a cross-development version of theDDL processor called xooddlx. Under cross-development, you run xooddlx onthe host architecture (the platform on which xooddlx was created). You thencross-compile and cross-link the application for execution on the targetNametarget architecture. See Installation and Platform Notes for UNIX for the supportedcombinations of host and target architectures.

The installation program runs ooconfig automatically when theObjectivity/C++ Data Definition Language product is installed. You must rerunooconfig to update your DDL processor every time you change the version orlocation of your C++ compiler. When you run ooconfig to create a native DDLprocessor, you are prompted for such information as:■ The name and version of your compiler■ Whether the C++ preprocessor is ANSI■ The compiler’s include path■ The compiler’s predefined preprocessor variables

For information about running ooconfig to create a DDL processor forcross-development, see the Installation and Platform Notes for UNIX.

oocopydbCopies a database file.

oocopydb-db dbSysName | -id dbId[-host hostName] -filepath path[-exists ask | delete | quit][-external][-standalone][-notitle][-quiet][-help][bootFilePath]


System name of the database to be copied.

-id dbId

Integer identifier of the database to be copied (for example, 78). This optionalso accepts the identifier specified in D-C-P-S format (for example, 78-0-0-0).If you use this option, you cannot use the -db option.




-host hostName

Host on which to place the database copy. If you omit this option, the defaulthost is:■ The current host, if -filepath specifies a local path.■ The host implied by -filepath, if an NFS mount name is specified.If -filepath specifies a Windows UNC share name, hostName is set to theliteral string oo_local_host; any value you specify is ignored.

-filepath path

Path (including the filename) to the database copy on the designated host. Ifthe -host option specifies a remote system, path must be full, not relative.


Action to take if a filename clash exists between the original database file anda file in the destination directory.ask Prompts whether to overwrite the existing file. If the answer

is No, the program terminates. No is the default.delete Overwrites the file in the destination directory.quit Terminates without copying the database to the destination

directory.The default value is ask.

-external

Allows and copies external relationships (associations) in the specifieddatabase. By default, oocopydb terminates if it encounters externalrelationships.

-standalone


-notitle


-quiet


-help


bootFilePath

Path to the boot file of the federated database containing the specifieddatabase. You can omit this argument if you set the OO_FD_BOOT




environment variable to the correct path. (HA) You can specify the boot fileof any autonomous partition.

Discussion The database copy is not attached to any federated database. The oocopydb toolprovides a safe alternative to copying database files directly using operatingsystem commands. The original database is inaccessible for the duration of thecopy operation.

See also ooattachdb

oocopyfdCreates a complete copy of a federated database, placing all the copied files in thespecified directory.

oocopyfd-fdnumber fdId[-host hostName] -dirpath path[-lockserverhost lockServerHost][-fdname fdSysName][-exists ask | delete | quit][-standalone][-notitle][-quiet][-help][bootFilePath]

Options -fdnumber fdId

Integer identifier of the new federated database. This number must not bethe same as the original federated-database identifier (in the boot file for theoriginal federated database).

-host hostName

Host on which to place the copied files. If you omit this option, the defaulthost is:■ The current host, if -dirpath specifies a local path.■ The host implied by -dirpath, if an NFS mount name is specified.If -dirpath specifies a Windows UNC share name, hostName is set to theliteral string oo_local_host; any value you specify is ignored.

-dirpath path

Path to the directory in which to place the copied files. If the -host optionspecifies a remote system, the path value must be full, not relative.

-lockserverhost lockServerHost

Lock-server host for the new federated database.




-fdname fdSysName

System name of the new federated database.


Action to take if a filename clash exists between the original system-databasefile and a file in the destination directory.ask Prompts whether to overwrite the existing file. If the answer

is No, the program terminates. No is the default.delete Overwrites the file in the destination directory.quit Terminates without copying the database to the destination

directory.The default value is ask.

-standalone

Nonconcurrent mode. Use this option only if the lock server for the specifiedfederated database is stopped. If the lock server is running, the tool reportsan error and terminates.

-notitle


-quiet


-help


bootFilePath

Path to the boot file of the federated database to be copied. You can omit thisargument if you set the OO_FD_BOOT environment variable to the correctpath.

Discussion This tool is useful for preparing to deploy an existing federated database. It findsall the files of the federated database, copies them to one directory, updates theglobal catalog with the location of the copied files, and writes a new boot file. Thecopy is fully operational.

(HA) You may not copy a federated database that has multiple autonomouspartitions. Before you can use oocopyfd, you must choose a partition that bestrepresents the federated database, transfer any unique databases from the otherpartitions into that partition, and then delete the other partitions.

This tool obtains an exclusive write lock on the federated database for theduration of the copy operation.




oocreatesetCreates a backup set for the specified federated database.

oocreateset-set setName[-standalone][-notitle][-quiet][-help][bootFilePath]

Options -set setName

Name of the backup set to be created.

-standalone


-notitle


-quiet


-help


bootFilePath

Path to the boot file of the federated database to be archived. You can omitthis argument if you set the OO_FD_BOOT environment variable to the correctpath. (HA) You can specify the boot file of any autonomous partition.

Discussion You need to create a backup set explicitly only if you are planning to performcustomized backups. When you perform basic backups, Objectivity/DB createsany required backup sets implicitly.

See also oodeletesetooqueryset




oodebugTool for debugging a federated database that is not currently locked for update byanother application.

oodebug[-standalone][-help][bootFilePath]

Options -standalone


-help


bootFilePath

Path to the boot file of the federated database to be debugged. You can omitthis argument if you set the OO_FD_BOOT environment variable to the correctpath. (HA) You can specify the boot file of any autonomous partition.

Discussion This tool provides a set of commands for inspecting and editing the contents of afederated database. See Chapter 15, “oodebug Commands.”

You can use this tool on any platform to inspect or edit objects that were createdby applications written in any of the Objectivity programming interfaces.

On UNIX, you can use the oodebug alias to run this tool from within a C++debugger.

oodeletedbDeletes a database from a federated database. (HA) Deletes all images of areplicated database.

oodeletedb-db dbSysName | -id dbId | -all[-catalogonly][-force][-standalone][-notitle][-quiet][-help][bootFilePath]





System name of the database to be deleted.

-id dbId

Integer identifier of the database to be deleted (for example, 78). This optionalso accepts the identifier specified in D-C-P-S format (for example, 78-0-0-0).

-all

Removes all databases from the specified federated database.

-catalogonly

Removes the database from the federated database’s global catalog, withoutdeleting the database file.

-force

Deletes the database without requesting confirmation. Useful when invokingthe tool from another tool or product.

-standalone


-notitle


-quiet


-help


bootFilePath

Path to the boot file of the federated database from which the specifieddatabase is to be deleted. You can omit this argument if you set theOO_FD_BOOT environment variable to the correct path. (HA) You can specifythe boot file of any autonomous partition.

Discussion If the database file exists, all bidirectional relationships (associations) andunidirectional relationships (associations) to objects in other databases areremoved and the file is deleted. If the database file does not exist, you can deletethe database from the federated database’s global catalog by using the-catalogonly option.

(HA) To delete just a single image of a replicated database, you must use theoodeletedbimage tool; see Objectivity/DB High Availability.




oodeletefdDeletes a federated database.

oodeletefd[-force][-notitle][-quiet][-help]bootFilePath

Options -force

Deletes the federated database without requesting verification. Useful wheninvoking the tool from another tool or product.

-notitle


-quiet


-help


bootFilePath

Path to the boot file of the federated database to be deleted. (HA) You canspecify the boot file of any autonomous partition. This is a required argument;there is no default value.

Discussion Before deleting a federated database, you must ensure that no locks are being heldwithin any of its databases. Consequently, you should:■ Ensure that no active transactions exist against the federated database.■ Recover any abnormally completed transactions (for example, using

oocleanup).




oodeletesetDeletes a backup set and all information in the backup diary about the backupsassociated with that set.

oodeleteset-set setName[-procfiles programName][-standalone][-notitle][-quiet][-help][bootFilePath]

Options -set setName

Name of the backup set to be deleted. Deleting a backup set deletes all of thebackup events in it.

-procfiles programName

Executes the shell script or program programName before deleting thebackup volume. programName can contain a full or relative path.During the execution of oodeleteset, the name of the file about to bedeleted is passed to the script as a command-line argument. If the script exitswith a nonzero status, oodeleteset reports an error, but continuesprocessing.

-standalone


-notitle


-quiet


-help


bootFilePath

Path to the boot file of the federated database. You can omit this argument ifyou set the OO_FD_BOOT environment variable to the correct path. (HA) Youcan specify the boot file of any autonomous partition.




Discussion To delete a basic backup (a backup taken with options such as -full,-incremental, -subincremental, or -destination), you must first use theooqueryset tool to find the name of the backup set that was implicitly created forthe backup you want to delete. You then use the -set option to specify this backupset name to oodeleteset.

See also oocreatesetooqueryset

oodump(For backward compatibility only) Creates a text file containing a representation ofthe contents of a federated database to be loaded later using ooload.

oodump[-id dbId | (-db dbSysName [-cont contSysName]) ][-range full | one | down | up][-format dec | oct | hex][-outfile filename [-exists ask | delete | quit]][-line length][-compress [tool]][-empty][-ignore][-standalone][-noheader][-notitle][-help][bootFilePath]

Options -id dbId

Integer identifier of the database to be dumped (for example, 78). This optionalso accepts the identifier specified in D-C-P-S format (for example, 78-0-0-0).If you use this option, you cannot use the -cont or -db option.

-db dbSysName

System name of a particular database to be dumped. By default, this tooldumps all databases within the specified federated database. If you use thisoption, you cannot use the -id option.

-cont contSysName

System name of a particular container to dump. If you use this option, youmust also use the -db option to specify the database that contains thiscontainer. If you use this option, you cannot use the -id option. IfcontSysName contains spaces, you must enclose it in double-quote (" ")characters.




-range full | one | down | up

Range of objects to dump.full Dumps the specified object, all objects it contains, and all

objects that contain it.one Dumps only the specified object.down Dumps the specified object and all objects it contains.up Dumps the specified object and all objects that contain it.The default value is full.

-format dec | oct | hex

Output format of integers.dec Decimal formatoct Octal formathex Hexadecimal formatThe default value is dec.

-outfile filename

Name of the output file, which contains the textual representation in ObjectText Format of the dumped objects. You can omit this option to send alloutput to stdout.




-line length

Line length in characters for string attributes. length can be anynonnegative integer. 0 means that there is no restriction on line length. Thedefault value is 0.

-compress [tool]

Pipes the output through the specified data compression tool. If tool is notspecified, output is sent to the standard UNIX compress tool.

-empty

Includes empty relationships (associations) in the output. If you omit thisoption, empty relationships are not included in the output.

-ignore

Ignores errors when possible and continues processing.




Warning: Use of the -ignore option can result in text files that ooloadcannot load.

-standalone


-noheader

Suppresses the header in the output. If you omit this option, a header isincluded at the beginning of output.

-notitle


-help


bootFilePath

Path to the boot file of the federated database containing the objects to bedumped. You can omit this argument if you set the OO_FD_BOOTenvironment variable to the correct path. (HA) You can specify the boot fileof any autonomous partition.

Discussion Although the oodump and ooload tools are still supported, you should useooexportfd and ooimport instead.

By default, the oodump tool dumps all databases within the specified federateddatabase. You can use oodump to dump a particular database (use the -id or -dboption) or a particular container (use the -cont and -db option).

This tool does not dump the following information:■ Unidirectional relationships (associations) from a not-dumped object to a

dumped object■ (HA) Autonomous partitions

See also ooexportdataooexportfdooload




oodumpcatalogGenerates a textual report of the files in a federated database’s global catalog.

oodumpcatalog[-ap apSysName | -id apId][-outfile filename

[-exists ask | delete | quit]][-format hostlocal | native][-nolabel][-control][-standalone][-notitle][-help][bootFilePath]


(HA) System name of the autonomous partition that controls the files to belisted. You can omit both this option and the -id option to list all of the filesin the federated database.

-id apId

(HA) Integer identifier of the autonomous partition that controls the files tobe listed. You can omit both this option and the -ap option to list all of thefiles in the federated database.

-outfile fileName

Name of the file in which to write the generated report. You can edit this fileto drive a standard backup tool. You can omit this option to send all outputto stdout.



is No, the program terminates. No is the default.delete Overwrites the file in the destination directory.quit Terminates without creating the file.The default value is ask.

-format hostlocal | native

Format for printing filenames.hostlocal Filename printed in host format, as

hostName::localPath—for example,mach3::/mnt/fred/project/myfd.FDB




native Filename printed as full path using the native operatingsystem’s format—for example,/net/mach3/usr/mnt/project/myfd.FDB

The default value is hostlocal.

-nolabel

Suppresses the labeling of files in the output. By default, each filename in theoutput is labeled.

-control

(HA) Lists the controlling autonomous partition for each file.

-standalone


-notitle


-help


bootFilePath

Path to the boot file of the federated database containing the files to be listed.You can omit this argument if you set the OO_FD_BOOT environment variableto the correct path. (HA) You can specify the boot file of any autonomouspartition.

Discussion This tool shows the global catalog of a federated database. The global catalogdescribes the properties of databases, autonomous partitions, and databaseimages—that is, objects that are physically represented as files. You typicallydisplay the global catalog to inspect the distributed structure of a federateddatabase or to see the properties of each file-based object. For example, you can usethis tool to find out which databases (if any) have been made read-only.

This tool shows catalog information in a simple textual format. Useooexportcatalog to represent catalog information in an XML document.

(HA) By default, the output lists the system-database files, boot files, and journaldirectories of all autonomous partitions. Use the -ap or -id option to reportcatalog information about the files controlled by a particular autonomouspartition.




(HA) The output lists the individual image files for each database that hasmultiple images. The output also lists the tie-breaker partition, if any, for eachdatabase.

See also ooexportcatalog

ooexportcatalogCreates an XML document representing the components of a federated database’sglobal catalog.

ooexportcatalog[-ap apSysName | -id apId][-outfile filename [-maxfilesize value][-compress]

[-exists ask | delete | quit]][-nws][-shortnames][-verbose][-stoponerror][-standalone][-notitle][-quiet][-help]bootFilePath


(HA) System name of the autonomous partition that controls theglobal-catalog components to be represented.You can omit this option (and the -id option) to export all of the databases,autonomous partitions, and database images in the federated database. Ifyou use this option, you cannot use the -id option.

-id apId

(HA) Integer identifier of the autonomous partition that controls theglobal-catalog components to be represented.You can omit this option (and the -ap option) to export all of the databases,autonomous partitions, and database images in the federated database. Ifyou use this option, you cannot use the -ap option.

-outfile filename

Base name for all output files. You may optionally include a path to anexisting directory in which to create the output files; if you do not include apath, the output files are created in the directory in which you ran the tool.You can omit this option to send the generated XML document to stdout.




Specifying this option creates the following output files:■ One or more files containing the XML document. The first or only such

file is called filename.xml; subsequent files are numbered sequentially,starting with filename_2.xml. Multiple files are generated only to keepthe file size within the limit specified by -maxfilesize.

■ A report file called filenameReport.xml summarizing the number ofXML elements of each kind in the XML document.

■ A file called filenameInstall.xml showing file locations and otherinformation stored in the exported catalog. This install file serves as atemplate for specifying nondefault file locations and other configurationinformation when the catalog is imported into another federateddatabase.

-maxfilesize value

Maximum size of each output file, expressed as an integer number ofmegabytes (MB). You can omit this option to set the maximum size to100 MB.This option applies only when the -outfile option is also specified.

-compress

Compresses the output files using a built-in gzip utility. When you specifythis option, each output file has the additional extension .gz—for example,filename.xml.gz

This option applies only when the -outfile option is also specified.

-exists

Action to take if a file already exists with the same name as a generatedoutput file.ask Prompts whether to overwrite the existing file. If the answer

is No, the program terminates. No is the default.delete Deletes any existing file.quit Terminates the program if the file currently exists.The default value is ask.This option applies only when the -outfile option is also specified.

-nws

Suppresses all nonessential “white space” (spaces, tabs, and blank lines),producing an XML document that is more compact, but less readable.You can omit this option to format each XML tag on a separate line, indentedto indicate its level of nesting.

-shortnames

Shortens all XML tag names and attribute names, producing an XMLdocument that is more compact, but less readable. Each shortened name is




usually a single character and is not necessarily mnemonic—for example:<v bQ=”3-0-0-0” cv=”test” … >.You can omit this option to generate XML tags and attributes with longer,more mnemonic names—for example:<Db oid=”3-0-0-0” systemName=”test” … >.

-verbose

Expands various XML elements to include additional detail, producing anXML document that is more readable, but less compact. You can omit thisoption to generate XML elements that contain only the minimuminformation required by ooimport.

-stoponerror

Terminates immediately when an error is detected.Omitting this option causes the tool to report errors to stderr and continueprocessing. Each reported error contains an XPath expression for the nodebeing processed at the time of the error, followed by an explanatory message.

-standalone


-notitle


-quiet


-help


bootFilePath

Path to the boot file of the federated database containing the catalog to beexported. You can omit this argument if you set the OO_FD_BOOTenvironment variable to the correct path. (HA) You can specify the boot fileof any autonomous partition.

Discussion This tool exports the global catalog from a federated database by representing itsinformation textually in Extensible Markup Language (XML). More specifically,this tool creates an XML document containing a hierarchy of XML elementsrepresenting the global catalog in the federated database. You can specify this XMLdocument to the ooimport tool to transfer the exported global catalog to a




destination federated database—for example, to prepare the federated databasebefore importing data.

The XML document produced by ooexportcatalog contains no data or schemarepresentations. Rather, the XML document describes the properties of databases,autonomous partitions, and database images—that is, objects that are physicallyrepresented as files.

By default, this tool exports the entire global catalog. To export a subset of theglobal catalog:■ (HA) Use the -ap or -id option to export the portion of the global catalog

that is controlled by a particular autonomous partition.

You can control the size and readability of the XML document with the -nws,-shortnames, and -verbose options.

By default, the XML document is sent to stdout. You can save this document toone or more files by specifying the -outfile option. This option also generates asummary report of the XML elements present in the XML document, along withan install file (a template for changing global-catalog information upon import).You control the size of the output files with the -maxfilesize and -compressoptions.

You can export a global catalog to inspect the distributed structure of a federateddatabase or to see the properties of each file-based object—for example, to findout which databases (if any) have been made read-only. (As an alternative, youcan use oodumpcatalog to display catalog information in a simple textualformat.)

See also ooexportdataooexportfdooexportschemaooimport

ooexportdataCreates an XML document representing the objects in a federated database.

ooexportdata[-id identifier | (-db dbSysName [-cont contSysName])][-outfile filename [-maxfilesize value][-compress]

[-exists ask | delete | quit]][-nws][-shortnames][-verbose][-standardMaps][-stoponerror][-schemalock lockVal]




[-standalone][-notitle][-quiet][-help]bootFilePath

Options -id identifier

Identifier of the data to be exported. You can specify:■ The integer identifier of a database (for example, 78). This option also

accepts the identifier specified in D-C-P-S format (for example, 78-0-0-0).■ The object identifier in D-C-P-S format of a container or basic object (for

example, 78-16-43-5).By default, this tool exports the data in all databases within the specifiedfederated database. If you use this option, you cannot use the -db option.

-db dbSysName

System name of a particular database to be exported. By default, this toolexports all databases within the specified federated database. If you use thisoption, you cannot use the -id option.

-cont contSysName

System name of a particular container to export. If contSysName containsspaces, you must enclose it in double-quote (" ") characters.If you use this option, you must also use the -db option to specify thedatabase that contains this container. You can omit -cont to export allcontainers within the specified database.

-outfile filename

Base name for all output files. You may optionally include a path to anexisting directory in which to create the output files; if you do not include apath, the output files are created in the directory in which you ran the tool.You can omit this option to send the generated XML document to stdout.Specifying this option creates the following output files:■ One or more files containing the XML document. The first or only such



-maxfilesize value

Maximum size of each output file, expressed as an integer number ofmegabytes (MB). You can omit this option to set the maximum size to100 MB.





-compress



-exists



-nws


-shortnames

Shortens all XML tag names and attribute names, producing an XMLdocument that is more compact, but less readable. Each shortened name isusually a single character and is not necessarily mnemonic—for example:<l i="7/>.You can omit this option to generate XML tags and attributes with longer,more mnemonic names—for example: <Basic value="7/>.

-verbose

Expands various XML elements to include additional detail, producing anXML document that is more readable, but less compact. You can omit thisoption to generate XML elements that contain only the minimuminformation required by ooimport.For example, a verbose XML element for a persistent object includes thename and type number of the object’s class. In contrast, the correspondingnonverbose version includes just the type number, which is sufficient foridentifying the object’s class to ooimport.




-standardMaps

Simplifies the XML representation of name maps (instances of ooMap orOoMap), producing a more compact and readable XML document. You mayspecify this option only if all of the name maps to be exported use the defaulthashing function.Warning: Do not specify -standardMaps if the name maps to be exporteduse an application-defined hashing function. Doing so will produce an XMLrepresentation of the name maps that cannot be reconstructed by ooimport;such name maps will be unusable after they have been imported.Omitting this option generates an XML representation of name maps thatmore closely corresponds to their comparatively complex internal structure.When specified, this option causes name maps to be represented using justtwo types of XML element (<Map> and <MapElement>).

-stoponerror


-schemalock lockVal

64-bit unsigned integer key for unlocking the schema. You can normally omitthis option because, by default, the schema is not locked. This option isrequired only if you have explicitly locked the schema of a federateddatabase using Objectivity/DB Active Schema.

-standalone


-notitle


-quiet


-help


bootFilePath

Path to the boot file of the federated database containing the data to beexported. You can omit this argument if you set the OO_FD_BOOT





Discussion This tool exports persistent objects from a federated database by representing themtextually in Extensible Markup Language (XML). More specifically, this toolcreates an XML document containing a hierarchy of XML elements representingthe desired objects. You can specify this XML document to the ooimport tool totransfer the exported persistent objects to a destination federated database. Youcan also transform the XML document to a different XML Schema (for example,using a standard XSLT tool), and then import the transformed document into athird-party application.

The XML document produced by ooexportdata has no schema or cataloginformation, so you can import it only into a destination federated database thatalready has a compatible schema and any referenced databases. Use ooexportfdto export both data and schema in the same XML document.

By default, this tool exports all persistent objects in all containers in all databases.To export a subset of the persistent objects, you can:■ Use the -db option to export a particular database.■ Use the -cont option with the -db option to export a particular container■ Use the -id option to export a particular database, container, or basic object

You can control the size and readability of the XML document with the -nws,-shortnames, -verbose, and -standardMaps options.

By default, the XML document is sent to stdout. You can save this document toone or more files by specifying the -outfile option. This option also generates asummary report of the XML elements present in the XML document. You controlthe size of the output files with the -maxfilesize and -compress options.

You can use this command as an alternative to oodump.

See also ooexportcatalogooexportfdooexportschemaooimport




ooexportfdCreates an XML document representing an entire federated database, includingits data, schema, and catalog information.

ooexportfd[-entireschema][-outfile filename [-maxfilesize value][-compress]

[-exists ask | delete | quit]][-nws][-shortnames][-verbose][-standardMaps][-stoponerror][-schemalock lockVal][-standalone][-notitle][-quiet][-help]bootFilePath

Options -entireschema

Generates XML elements for all classes in the federated database’s schema,including Objectivity/DB internal classes. You can omit this option togenerate XML elements only for application-defined classes, producing asmaller XML document.You can normally omit this option because the destination federateddatabase of an import operation already contains the schema forObjectivity/DB internal classes. You should specify -entireschema if thefederated database being exported was created with a different release ofObjectivity/DB than the intended destination federated database.

-outfile filename







■ A file called filenameInstall.xml showing file locations and otherinformation stored in the exported catalog. This install file serves as atemplate for specifying nondefault file locations and other configurationinformation when the catalog is imported into another federateddatabase.

-maxfilesize value


-compress



-exists



-nws


-shortnames

Shortens all XML tag names and attribute names, producing an XMLdocument that is more compact, but less readable. Each shortened name isusually a single character and is not necessarily mnemonic—for example:<l i="7/>.You can omit this option to generate XML tags and attributes with longer,more mnemonic names—for example: <Basic value="7/>.




-verbose

Expands various XML elements to include additional detail, producing anXML document that is more readable, but less compact. You can omit thisoption to generate XML elements that contain only the minimuminformation required by ooimport.For example, a verbose XML element for a persistent object includes thename and type number of the object’s class. In contrast, the correspondingnonverbose version includes just the type number, which is sufficient foridentifying the object’s class to ooimport.

-standardMaps

Simplifies the XML representation of name maps (instances of ooMap orOoMap), producing a more compact and readable XML document. You mayspecify this option only if all of the name maps to be exported use the defaulthashing function.Warning: Do not specify -standardMaps if the name maps to be exporteduse an application-defined hashing function. Doing so will produce an XMLrepresentation of the name maps that cannot be reconstructed by ooimport;such name maps will be unusable after they have been imported.Omitting this option causes the XML representation of name maps to moreclosely correspond to their comparatively complex internal structure.When specified, this option causes name maps to be represented using justtwo types of XML element (<Map> and <MapElement>).

-stoponerror


-schemalock lockVal


-standalone





-notitle


-quiet


-help


bootFilePath

Path to the boot file of the federated database to be exported. You can omitthis argument if you set the OO_FD_BOOT environment variable to the correctpath. (HA) You can specify the boot file of any autonomous partition.

Discussion This tool exports an entire federated database by representing it textually inExtensible Markup Language (XML). More specifically, this tool creates an XMLdocument containing a hierarchy of XML elements representing the objects,schema, and catalog that comprise the federated database. You can specify thisXML document to the ooimport tool to transfer the exported elements into adestination federated database—for example, to reproduce an entire federateddatabase in a different location or with a different storage page size.

By default, this tool exports schema descriptions only of application-definedclasses. You can use the -entireschema option to export the entire schema.

You can control the size and readability of the XML document with the -nws,-shortnames, -verbose, -entireschema, and -standardMaps options.

By default, the XML document is sent to stdout. You can save this document toone or more files by specifying the -outfile option. This option also generates asummary report of the XML elements present in the XML document, along withan install file (a template for changing global-catalog information upon import).You control the size of the output files with the -maxfilesize and -compressoptions.

You can use this command as an alternative to oodump.

See also ooexportcatalogooexportdataooexportschemaooimport




ooexportschemaCreates an XML document representing part or all of a federated database’sschema.

ooexportschema[-class className | -entireschema][-outfile filename [-maxfilesize value][-compress]

[-exists ask | delete | quit]][-nws][-shortnames][-verbose][-stoponerror][-schemalock lockVal][-standalone][-notitle][-quiet][-help]bootFilePath

Options -class className

Name of a particular class to be exported.By default, this tool exports the set of application-defined classes in thefederated database’s schema. Specifying the -class option produces anXML document that represents only a single class. If you use the -classoption, you cannot use the -entireschema option.You normally use the -class option if you want to inspect an XMLrepresentation of a particular class or import the class into a third-partyCASE tool.Note: A single class cannot be imported by itself into another federateddatabase. If your goal is to transfer a class from one federated database toanother, you should export all the application-defined classes in the schema(optionally including the Objectivity/DB internal classes).

-entireschema

Exports the entire federated-database schema, includng Objectivity/DBinternal classes.By default, this tool exports the set of application-defined classes in thefederated database’s schema. Specifying the -entireschema optionproduces a larger XML document representing Objectivity/DB internalclasses in addition to the application-defined classes. If you use the-entireschema option, you cannot use the -class option.You can normally omit the -entireschema option because the destinationfederated database of an import operation already contains the schema forObjectivity/DB internal classes. You should specify -entireschema if the




federated database of the exported schema was created with a differentrelease of Objectivity/DB than the intended destination federated database.

-outfile filename




-maxfilesize value


-compress



-exists



-nws





-shortnames

Shortens all XML tag names and attribute names, producing an XMLdocument that is more compact, but less readable. Each shortened name isusually a single character and is not necessarily mnemonic—for example:</o>.You can omit this option to generate XML tags and attributes with longer,more mnemonic names—for example: </Class>.

-verbose

Expands various XML elements to include additional detail, producing anXML document that is more readable, but less compact. You can omit thisoption to generate XML elements that contain only the minimuminformation required by ooimport.

-stoponerror


-schemalock lockVal


-standalone


-notitle


-quiet


-help


bootFilePath

Path to the boot file of the federated database containing the schema to beexported. You can omit this argument if you set the OO_FD_BOOT





Discussion This tool exports the schema of a federated database by representing it textually inExtensible Markup Language (XML). More specifically, this tool creates an XMLdocument containing a hierarchy of XML elements representing one or more of theclasses described in the federated database’s schema. You can specify this XMLdocument to the ooimport tool to transfer the exported schema into a destinationfederated database—for example, to prepare a newly created federated databasebefore importing data.

By default, this tool exports the set of application-defined classes in the schema.To export a different set of classes:■ Use the -entireschema option to export the entire schema, including

Objectivity/DB internal classes as well as application-defined classes.■ Use the -class option to export a single class.

Note: A single class cannot be imported by itself into another federateddatabase. If your goal is to transfer a class from one federated database toanother, you should export all the application-defined classes in the schema(optionally including the Objectivity/DB internal classes).

You can control the size and readability of the XML document with the -nws,-shortnames, -verbose, and -entireschema options.

By default, the XML document is sent to stdout. You can save this document toone or more files by specifying the -outfile option. This option also generates asummary report of the XML elements present in the XML document. You controlthe size of the output files with the -maxfilesize and -compress options.

Exporting a schema is the first step of a procedure that synchronizes the schemasof two or more federated databases. You typically synchronize schemas whenyou want to:■ Prepare a destination federated database before attaching a database.■ Prepare a destination federated database before importing data (the output

of ooexportdata).■ Ensure that all members of a distributed development team are using

federated databases with matching schemas.

See also ooexportcatalogooexportdataooexportfdooimport




oofileDisplays the file type and other information about the specified Objectivity/DBfile.

oofilefileName[-notitle][-help]

Options fileName

Filename of the Objectivity/DB file to be described.

-notitle


-help


Discussion This tool displays the following information about the specified file:■ The file type—Database file, system-database file for a federated database or

autonomous partition, or boot file.■ The properties for the type of file, such as the identifier, system name,

journal-directory host and path, lock-server host, storage-page size, andcontaining federated database.

■ The architecture (platform and operating system) on which the file wascreated.

■ The Objectivity/DB release with which the database format is compatible.This information is useful when you are upgrading to a new release.

See also oochangeoochangedb




oogcDeletes unreferenced objects from garbage-collectible containers in a federateddatabase. Garbage-collectible containers can be created and used only byObjectivity for Java or Objectivity/Smalltalk applications.

oogc[-askroots][-nodelete][-verbose][-statistics][-notitle][-quiet][-help][bootFilePath]

Options -askroots

Asks interactively for special root objects.

-nodelete

Displays the object identifiers of containers and objects that would bedeleted, but does not delete them.

-verbose

Displays all roots, followed references, and deleted objects.

-statistics

Displays data about the number of roots, visited containers, visited objects,deleted containers, and deleted objects.

-notitle


-quiet


-help


bootFilePath

Path to the boot file of the federated database containing the containers to begarbage-collected. You can omit this argument if you set the OO_FD_BOOTenvironment variable to the correct path. (HA) You can specify the boot fileof any autonomous partition.

Discussion This tool can delete unreferenced objects from a garbage-collectible container onlyif it can get an update lock on that container. When a garbage-collectible container




is unnamed and contains only unreferenced persistent objects, this tool deletes thecontainer. A persistent object is considered referenced only if it can be reachedfrom an Objectivity for Java or Objectivity/Smalltalk named root.

Garbage collection does not apply to non-garbage-collectible containers, whichexist primarily for interoperating with applications written in anon-garbage-collected language, such as C++. All objects in anon-garbage-collectible container are assumed to be valid and remain in thedatabase until explicitly deleted by an application.

Substantial virtual memory can be required for oogc’s temporary data,depending on how much garbage needs to be collected. Processing a largecontainer with references to many other large containers also increases thememory requirement.

Warning: Do not run oogc and oobackup concurrently, because oogc may deleteobjects that oobackup references.

The oogc tool can run concurrently with other database processes.

ooimportInterprets the specified XML document and populates an existing federateddatabase accordingly.

ooimport-input fileName[-addnewclasses][-nullifyexternals | -norefcheck][-collapsepartitions][[-tmpdirhost hostName] -tmpdirpath dirPath][-schemalock lockVal][-standalone][-notitle][-quiet][-help]bootFilePath

Options -input fileName

Base name of the file or files containing the XML document to be imported.You may optionally include a path to the directory containing the files; if youdo not include a path, the files must reside in the directory in which you runooimport.The specified fileName should not include a file extension or suffix. Rather,fileName is sufficient to designate an XML document contained in one ormore files, where the first or only file is called filename.xml, and anysubsequent files are numbered sequentially, starting with filename_2.xml.




Furthermore, when global-catalog information is being imported, fileNamealso designates an install file called filenameInstall.xml (if there is one)in the same directory as the XML-document files.The input files for ooimport are typically the ouput of an Objectivity/DBexport tool (ooexportfd, ooexportdata, ooexportschema, orooexportcatalog); however, you can specify any XML document thatconforms to the XML Schema for Objectivity/DB data. This XML Schema islocated in a subdirectory of your Objectivity/DB installation directory(installDir):

-addnewclasses

Permits the import operation to add new class descriptions to the schema ofa destination federated database. This option is required only if thedestination schema already contains application-defined classes; the purposeof this option is to confirm that additions to the schema are intentional.When you omit this option, the import operation proceeds only if theimported schema is identical to (or a subset of) the schema in the destinationfederated database or if the destination federated database is newly created(so its schema contains only Objectivity/DB internal classes). Otherwise,ooimport reports an error and terminates.You normally use this option to import a schema containing new classdescriptions that will be needed by imported persistent objects. A new classdescription is not added if its class name or type number matches anyexisting class in the destination schema. An error is reported if an importedclass has the same name as existing class, but a different type number; or ifan imported class has the same type number as an existing class, but adifferent name.

-nullifyexternals

Sets any reference attributes and relationships (associations) that linkimported persistent objects to each other, but sets all external references to null.An external reference is a reference attribute or relationship that would linkan imported object to one or more objects that are not being imported. Awarning is reported for each nullified attribute or relationship.Omitting this option causes ooimport to try to set all reference attributesand relationships, including external references. However, an externalreference is set only if it is valid—that is, if the referenced or related objectexists in the destination federated database and is of the correct type. If aninvalid reference is encountered, ooimport reports an error and terminates.

On Windows installDir\etc\Objy.xsd

On UNIX installDir/arch/etc/Objy.xsd, where arch is thesubdirectory for your UNIX architecture




Specifying this option makes the import operation faster by limiting it toreconstructing just the reference attributes and relationships that are easilyvalidated—specifically, those that create links among the set of objects beingimported. External references are set to null, even those that might be valid.

-norefcheck

Sets the reference attributes of imported persistent objects without checkingfor referential integrity—that is, without checking for the existence of theobjects being referenced.Omitting this option causes ooimport to check for referential integrity, so areference attribute is set only if the referenced object exists and is of thecorrect type; otherwise, ooimport reports an error and terminates.Note: This option suppresses checking only for reference attributes.Relationships (associations) are always checked for referential integritybefore being set, whether not you specify this option.Checking for referential integrity is especially important when you areimporting persistent objects with external reference attributes (where thereferenced objects are not among the objects you are importing). Thus,omitting this option ensures that all external references point to existingobjects within the destination federated database. However, if you areimporting objects with a large number of external references, and you knowthat these references will be valid in the destination federated database, youcan consider using this option to make the import operation faster.Warning: Do not use the -norefcheck option unless you can guarantee thatall external references are valid. Otherwise, specifying this option couldresult in a loss of referential integrity in your data.Specifying this option has no significant effect when you are importingpersistent objects that reference other imported persistent objects.

-collapsepartitions

(HA) Ignores any autonomous partitions represented in the imported XMLdocument. All imported databases are placed under the control of thedestination federated database or autonomous partition specified bybootFilePath. If multiple images of a replicated database are representedin the imported XML document, the import operation uses the first suchimage encountered in the XML document.You can omit this option to reconstruct autonomous partitions according tothe install file corresponding to the specified XML document.Note: Specifying -collapsepartitions causes ooimport to bypass anyinformation about partitions in the install file corresponding to the specifiedXML document.




-tmpdirhost hostName

Host on which to create a temporary database file. If you omit this option,the default host is:■ The host on which you are running this tool, if -tmpdirpath specifies a

local path.■ The host implied by -tmpdirpath, if an NFS mount name is specified.If -tmpdirpath specifies a Windows UNC share name, hostName is set tothe literal string oo_local_host; any value you specify is ignored.

-tmpdirpath dirPath

Path to the directory on the designated host in which to create a temporarydatabase file. If the -tmpdirhost option specifies a remote system, dirPathmust be full, not relative. If you omit both the -tmpdirhost and-tmpdirpath options, the temporary file is created in the directorycontaining the system-database file of the federated database or autonomouspartition specified by bootFilePath.

-schemalock lockVal


-standalone


-notitle


-quiet


-help


bootFilePath

Path to the boot file of the destination federated database. You can omit thisargument if you set the OO_FD_BOOT environment variable to the correctpath. (HA) You can specify the boot file of any autonomous partition.

Discussion This tool interprets the specified Extensible Markup Language (XML) documentand populates the destination federated database accordingly. For example, if you




specify an XML document produced by ooexportfd, the destination federateddatabase is populated with the persistent objects, schema, and global catalog of thesource federated database.

You can use ooimport to fully populate an empty federated database or to addto an existing populated federated database. Depending on the XML elementspresent in the specified XML document, ooimport may create:■ Persistent objects■ Schema descriptions of new classes■ Global-catalog entries for new databases or (HA) autonomous partitions,

along with the corresponding files

Warning: Always make a backup of your federated database before you performan import operation.

An import operation may add new items (or new versions of existing items) to afederated database, and never deletes or overwrites existing items. However, animport operation is performed in multiple transactions. Therefore, if ooimportquits with an error, the partial import may leave your federated database in aninconsistent state. In most cases, you can simply correct the error and then runooimport again; the import operation will pick up where it left off. A backup isessential because you cannot roll back any portion of the import that has alreadybeen committed.

When ooimport creates new databases or (HA) autonomous partitions from animported global catalog, their file locations are determined by the install filegenerated for the specified XML document. Before running ooimport, you canedit the install file to specify the desired name, host, and directory for each file tobe created, in addition to changing other catalog information. If you do not editthe install file (or if the install file is moved or deleted), the default importoperation creates all new files in the same directory as the system-database file ofthe specified federated database or boot partition. For more information aboutusing an install file to configure an imported catalog, see Chapter 11, “Exportingand Importing.”

When importing only data (without global-catalog or schema information), youmust first ensure that the destination federated database has:■ A schema that is identical to (or a superset of) that of the source federated

database from which the data was exported.■ An existing database corresponding to each source database from which data

was exported; the corresponding pairs of source and destination databasesmust have matching system names.

You can prepare an empty federated database by importing schema andglobal-catalog information exported from the source federated database.ooimport accepts XML documents representing data from all databases or from




an individual database (but not just data from a single container or a single basicobject).

ooimport preserves the relative clustering of basic objects within containers, butdoes not preserve the original object identifiers (OIDs). Instead, basic objects are“repacked” (written to consecutive slots on consecutive logical pages within theircontainers). Reference attributes and relationships (associations) that create linksamong imported objects are automatically adjusted to reflect the new OIDs.

ooimport creates a new basic object in the destination federated database forevery basic object represented in the imported XML document. If an importedobject originally had the same OID as an existing object in the destinationfederated database, the imported object is simply assigned a different OID.

An imported database is merged with an existing database if their system namesmatch; similarly, an imported container is merged with an existing container iftheir system names match. The identifiers of the merged databases or containersneed not match.

By default, external references (attributes and relationships that reference objectsnot in the XML document) are set to their exported values if referential integritycan be maintained; otherwise, ooimport reports an error and terminates. Youcan request different treatment of external references by using either the-nullify or -norefcheck option.

By default, an entire schema is imported only into a newly created destinationfederated database (where the schema contains no application-defined classes).You must specify the -addnewclasses option to enable ooimport to add newclasses into a populated destination schema.

NOTE ooimport reports an error and terminates if the imported schema contains anydescriptions that would change an existing class in the destination schema. Useooschemadump and ooschemaupgrade for schema-evolution operations.

For schema consistency, ooimport allows you to import either an entire schemaor the entire set of application-defined classes in a schema. ooimport reports anerror and terminates if the specified XML document represents just a single class(the output of ooexport -class).

See also Chapter 11, “Exporting and Importing”ooexportcatalogooexportdataooexportfdooexportschemaooload




ooinstallfdUpdates the global catalog and properties of a federated database after its fileshave been placed in a new operating environment.

ooinstallfd[-lockserverhost lockServerHost][-fdname fdSysName][-fdnumber fdId][[-fdfilehost fdFileHost] -fdfilepath fdFilePath][[-dbdirhost dbDirHost] -dbdirpath dbDirPath][[-jnldirhost jnlDirHost] -jnldirpath jnlDirPath][-licensefile fileName][-purgeAps][-nocheck][-standalone][-notitle][-quiet][-help]bootFilePath

Options -lockserverhost lockServerHost

Lock-server host for the newly installed federated database. The default isthe host on which you are running this tool.

-fdname fdSysName

System name of the newly installed federated database. The default is thesystem name specified in the boot file.

-fdnumber fdId

Integer identifier of the newly installed federated database. The default is theidentifier specified in the boot file.

-fdfilehost fdFileHost

Data-server host of the system-database file to be installed. If you omit thisoption, the default host is:■ The current host, if -fdfilepath specifies a local path.■ The host implied by -fdfilepath, if an NFS mount name is specified.■ The host of the specified boot file, if -fdfilepath is also omitted.If -fdfilepath specifies a Windows UNC share name, fdFileHost is set tothe literal string oo_local_host; any value you specify is ignored.

-fdfilepath fdFilePath

Path (including the filename) to the system-database file to be installed. If the-fdfilehost option specifies a remote system, fdFilePath must be full,not relative.




If you omit both the -fdfilepath and -fdfilehost options, the defaultpath consists of the system-database filename in the directory of the specifiedboot file (where the system-database filename is extracted from the boot file.)

-dbdirhost dbDirHost

Data-server host of the database files to be installed. If you omit this option,the default host is:■ The current host, if -dbdirpath specifies a local path.■ The host implied by -dbdirpath, if an NFS mount name is specified.■ The host of the specified boot file, if -dbdirpath is also omitted.If -dbdirpath specifies a Windows UNC share name, dbDirHost is set tothe literal string oo_local_host; any value you specify is ignored.

-dbdirpath dbDirPath

Path to the directory containing the database files to be installed. If the-dbdirhost option specifies a remote system, dbDirPath must be full, notrelative. If you omit both the -dbdirpath and -dbdirhost options, thedefault is the directory of the specified boot file.


Host of the journal directory for the newly installed federated database. Ifyou omit this option, the default host is:■ The current host, if -jnldirpath specifies a local path.■ The host implied by -jnldirpath, if an NFS mount name is specified.■ The host of the specified boot file, if -jnldirpath is also omitted.If -jnldirpath specifies a Windows UNC share name, jnlDirHost is set tothe literal string oo_local_host; any value you specify is ignored.


Path to the journal directory for the newly installed federated database. If the-jnldirhost option specifies a remote system, jnlDirPath must be full,not relative. If you omit both the -jnldirhost and -jnldirpath options,the default is the directory of the specified boot file.

-licensefile fileName

File containing the license to be placed in the newly installed federateddatabase. You may optionally include a path to the directory containing thelicense file; if you specify a filename without a path, the license file mustreside in the current directory.If you omit this option, the installed federated database keeps its currentlicense.




-purgeAps

Deletes any references to autonomous partitions from the global catalog ofthe federated database being installed. The partition indicated bybootFilePath becomes the newly installed (unpartitioned) federateddatabase. Any database without an image in the partition indicated bybootFilePath is detached, but not deleted.

-nocheck

Continues the installation even if a database file cannot be found in thelocation specified by dbDirHost and dbDirPath. By default, ooinstallfdterminates if a file is missing.

-standalone


-notitle


-quiet


-help


bootFilePath

Path to the boot file of the federated database to be installed. This argument isrequired.

Discussion You use this tool when setting up a federated database after its files have beenplaced in a new operating environment, such as a new host. This tool is typicallyused by an end user who has received the files of a deployed federated database,by a QA engineer who has received federated-database files for testing, or by atechnical-support engineer who has received federated-database files from acustomer for troubleshooting. No preparation of the federated-database files isrequired, other than placing its system-database file in the desired location andplacing all database files in a single directory. After you use ooinstallfd toupdate the global catalog and properties to reflect the new locations, you can useoochangedb to distribute individual database files to other locations.

By default, this tool verifies that all database files in the federated database arepresent in the specified directory. If some databases do not fit into that directory,you can run ooinstallfd with the -nocheck option. You must then update the




global catalog with the locations of these database files by using oochangedbwith the -catalogonly option.

(HA) Because autonomous partitions are highly specific to a particular operatingenvironment, this tool assumes the federated database being installed isunpartitioned. If you need to install a federated database that has partitions, youmust specify the -purgeAps option; otherwise, ooinstallfd will terminatewith an error. The -purgeAps option:■ Purges the partitions from the global catalog, leaving only the partition

whose boot file was specified to ooinstallfd; this partition becomes thenewly installed federated database.

■ May detach any database that had an image in any of the purged partitions.The detached databases are reported in the command output.

After installing, you can optionally create any desired partitions and then useooattachdb to reattach the desired databases.

ookilllsKills a standard lock server (a lock server that is running as a separate process).

ookillls[lockServerHost][-notitle][-help]

Options lockServerHost

Host system where the lock server is running. If you do not specifylockServerHost, the local lock server is killed.

-notitle


-help


Discussion If the lock server is currently servicing active transactions, the lock server refusesto terminate and an error is reported.

You cannot use this tool to kill an in-process lock server. An in-process lockserver can only be stopped by the IPLS application that started it. Terminating anIPLS application before it stops its in-process lock server is equivalent to anabnormal lock-server failure, and any incomplete transactions will need recovery.




On Windows, you normally kill a standard lock server from an ObjectivityNetwork Services tool, rather than using ookillls.exe from a commandprompt.

oolicenseDisplays or updates a license in the specified federated database.

oolicense[-licensefile fileName | -fromdefault][-notitle][-quiet][-help][bootFilePath]

Options -licensefile fileName

File containing the new license. You may optionally include a path to thedirectory containing the file; if you specify a filename without a path, the filemust reside in the current directory.

-fromdefault

Obtains the new license from the default license file oolicense.txt. Thetool first looks for the default file in the bootFilePath directory. If thedefault file is not found there, oolicense looks in the following location:■ (Windows) Objectivity/DB installation directory installDir

■ (UNIX) Your home directory; otherwise, the Objectivity/DB installationdirectory installDir

oolicense reports an error and terminates if no license file is found.

-notitle


-quiet


-help


bootFilePath

Path to a boot file of the federated database to be licensed. You can omit thisargument if you set the OO_FD_BOOT environment variable to the correctpath. (HA) You can specify the boot file of any autonomous partition.

Discussion To display a readable (unencrypted) version of the federated database’s currentlicense to stdout, enter oolicense with just bootFilePath.




To update the license in a federated database, use either the -licensefile or-fromdefault option to specify the new license. The new license completelyreplaces the federated database’s previous license. oolicense reports theidentifiers of both the new and the replaced licenses.

Every federated database must have a license before you can access it with a toolor application. You can use the oolicense tool to:■ Update a licensed federated database with a renewed or changed license.■ Upgrade an unlicensed federated database that was created before

Objectivity/DB required licenses.

oolistwaitDisplays information about transactions waiting on any lockable Objectivity/DBobject, which can be a federated database, a database, or a container.

oolistwait[ -transaction id | ([-host hostName] [-user userId])][-notitle][-help][bootFilePath]

Options -transaction id

Checks the status of the specified transaction.

-host hostName

Lists the status of all waiting transactions started on the specified host,subject to filtering based on other options. This option defaults to all nodes.

-user userId

Lists the status of all waiting transactions started by the specified user,subject to filtering based on other options. This option defaults to all users.

-notitle


-help


bootFilePath

Path to a boot file specifying the lock server to be queried. You can omit thisargument if you set the OO_FD_BOOT environment variable to the correctpath.

Discussion This tool queries the specified lock server to check for waiting transactions startedby a specified user or host. You can also use this tool to find out whether a specified




transaction is waiting for a lockable object, and if so, which transactions currentlyhold the lock on that object. The displayed transactions may be waiting forresources in any of the federated databases or autonomous partitions serviced bythe specified lock server.

The following table summarizes how to use the various options to view differenttypes of transaction information.

You should ignore any latches reported in the output. Latches are internally usedlocks on containers whose identifiers appear to be out of range.

ooload(For backward compatibility only) Creates persistent objects in a federated database,using information from a text file created by oodump.

ooload[-abort | -db][-cont][-uncompress [tool]][-external][-resize][-hash hashFactor][-grow growthPercent]-infile fileName[-verbose][-standalone][-notitle][-quiet][-help][bootFilePath]

To View Use This Option

All waiting transactions (no options)

Waiting transactions started on a specific host system -host

Waiting transactions started by a specific user -user

Waiting transactions started by a specific user on a specific hostsystem

-host and -user

A specific transaction’s status, and any transactions that areusing resources that it needs

-transaction




Options -abort

Terminates without applying changes. You can use this option (with orwithout the -verbose option) to test the load operation without committingthe transaction. If you use this option you cannot use the -db option.

-db

Deletes any databases whose system name matches a database in the inputtext file. If you use this option you cannot use the -abort option. This optionsupersedes the -cont option when both are specified.

-cont

Deletes containers from the database whose object identifier or system namematches a container in the text file.

-uncompress [tool]

Pipes the input file through the specified data-decompression tool. If tool isnot specified, the standard UNIX uncompress tool is used.

-external

Allows external references within the text file, generating a warning for eachexternal reference it encounters.Warning: Use of this option can introduce semantic inconsistencies into thefederated database.

-resize

Ignores container size information in the input file and resizes containers asnecessary. Use of this option can result in a more compact federateddatabase.

-hash hashFactor

Overrides the hash-factor information in the input file with the valuehashFactor for all containers. hashFactor can be any nonnegative integer.

-grow growthPercent

Overrides the growth-factor information in the input file with the valuegrowthPercent for all containers. growthPercent can be any nonnegativeinteger.

-infile fileName

Input text file (previously created by oodump).

-verbose

Prints full status information during processing and a summary messageafter processing terminates. This tool sends all status messages to stdoutand all error messages to stderr.




-standalone


-notitle


-quiet


-help


bootFilePath

Path to the boot file of the federated database where the objects will beloaded; by default the federated database specified in the text input file. (HA)You can specify the boot file of any autonomous partition.

Discussion Although the oodump and ooload tools are still supported, you should useooexportfd and ooimport instead.

By default, ooload terminates upon encountering an external reference. Externalreferences are either relationships (associations) with, or object identifiers for,objects not in the specified text input file. Specify the -external option to allowooload to skip external references without terminating.

The federated database referenced by bootFilePath must have a schemaidentical to (or a superset of) that of the federated database from which the textinput file was dumped.

The ooload tool does not:■ Preserve object identifiers (OIDs), although the containment hierarchy is

preserved.■ Load indexing information.■ Call constructors when it creates objects.■ Call destructors when it deletes objects. If ooload deletes a database or

container whose object identifier or system name matches the objectidentifier or system name specified by the -db or -cont option, it does notcall the object’s destructor.

See also oodumpooimport




oolockmonLists all processes and locks currently managed by a lock server.

oolockmon-host hostName | [bootFilePath][-detail][-notitle][-help]

Options -host hostName

Host on which the desired lock server is running. If you specify this option,you must omit the bootFilePath argument. Specifying the -host option isconvenient when a boot file is not available or its location is not known.

bootFilePath

Path to the boot file of the federated database or autonomous partitionwhose lock server is to be queried. You can omit this argument if you specifythe -host option or if you set the OO_FD_BOOT environment variable to thecorrect path.

-detail

Displays intention locks. An intention lock is a special kind of lock placed ona database or federated database when you open it. An intention lock simplyindicates that the transaction may also hold a read, update, or exclusive locklower in the storage hierarchy.

-notitle


-help


Discussion This tool reports the state of the specified lock server. The lock server may be eithera standard lock server (which runs as a separate process) or an in-process lockserver (which runs as part of an IPLS application process). The oolockmon tooldisplays the requested information in a table that includes:■ The transaction identifier of the transaction that obtained the lock■ The lock mode—read or update■ The type of locked object—federated database, database, or container■ The federated database, autonomous partition, database, and container

identifiers (if relevant) of the locked object

You should ignore any latches reported in the output. Latches are internally usedlocks on containers whose identifiers appear to be out of range.




oolockserverStarts a standard lock server (a separate lock-server process) on the currentworkstation, optionally starting the lock server’s recovery monitor as well.

oolockserver[{bootFilePath} [-monitor [-timeout seconds]

[-interval seconds] [-testport port]]][-notitle][-help]

Options bootFilePath

Path to the boot file of the federated database or autonomous partition to berecovered when the lock server is started. You can specify one or more paths.If you omit a federated database or autonomous partition that is serviced bythe lock server, that federated database or autonomous partition is recoveredthe first time it is opened by an application.If -monitor is specified, bootFilePath also indicates the federateddatabase for which transactions are to be monitored. If bootFilePath listsmultiple paths, only the first path is used by the recovery monitor.

-monitor

Enables the lock server’s recovery monitor for the first (or only) federateddatabase specified by bootFilePath. If bootFilePath is not specified, the-monitor option has no effect.The recovery monitor is a thread within the lock server that periodicallyidentifies the transactions against the specified federated database andchecks whether these transactions still belong to processes on operationalclient hosts. If the recovery monitor determines that any client host has failed(for example, due to machine or network problems), the lock serverautomatically recovers all transactions started by processes on that host(equivalent to running the oocleanup tool with the -deadhost option). Therecovery monitor also recovers incomplete transactions started by processes(on any client host) that are known to no longer be running.The recovery monitor’s behavior is controlled by the -timeout, -interval,and -testport options.

-timeout seconds

Number of seconds that the recovery monitor should wait to receive aresponse from a client host before concluding that the host has failed (forexample, due to machine or network problems). If you omit this option, therecovery monitor waits 30 seconds.The specified value should be at least as long as the network timeout periodused by the client applications (see “Lock-Server Timeout” on page 99 and




“AMS Timeout” on page 108; see also the documentation for your Objectivityprogramming interface).This option has no effect unless both the -monitor option andbootFilePath are specified.The recovery monitor checks whether a client host is operational byattempting to make a network connection to the host and waiting for aresponse within the specified timeout period.

-interval seconds

Number of seconds that the recovery monitor should wait before it checksagain for dead client hosts. If you omit this option, the recovery monitorattempts to contact client hosts with active transactions every 60 seconds.This option has no effect unless both the -monitor option andbootFilePath are specified.

-testport port

TCP/IP port number through which the recovery monitor attempts tocontact each client host to check whether the host is operational. The sameport number is used on all client hosts.If you omit this option, the lock-server port is used. (This is the port numbercurrently used by remote applications when communicating with the lockserver.) This port number is normally sufficient, although at some sites youmay need to specify a different port number—for example, to get through anetwork firewall. The port is used only to establish contact; no data is read orwritten through it, and it is not necessary for a lock server to be running onthat port.This option has no effect unless both the -monitor option andbootFilePath are specified.

-notitle


-help


Discussion Restarting the lock server after a lock-server failure performs automatic recoveryon the federated databases specified by bootFilePath.

On Windows, you normally start the lock server from an Objectivity NetworkServices tool, rather than using oolockserver.exe from a command prompt.You need administrator privileges to use this tool because the lock server isstarted as a service, not as a user program.

A lock server grants locks on resources (containers, databases, or federateddatabases) to requesting transactions. Each transaction can lock multiple




resources, and a given resource can be locked by multiple transactions. A singlelock server can support:■ A maximum of 1031 concurrent transactions■ A large number of concurrently held locks, limited only by available virtual

memory

In general, a lock server cannot be started on a workstation that is alreadyrunning a lock server (either a standard lock server or an IPLS application—see“Types of Lock Server” on page 91). However, it is possible for a lock server fromthe current release of Objectivity/DB to run on the same workstation as a lockserver from certain older releases of Objectivity/DB. If a federated databasespecifies such a workstation as its lock-server host, you must guarantee that allapplications accessing that federated database have been built with the samerelease of Objectivity/DB (so that they will all contact the same lock server).

Warning: Data corruption will occur if two applications built with differentreleases contact different lock servers while accessing data in the same federateddatabase.

oonewdbCreates a new database in a federated database.

oonewdb-db dbSysName[-id dbId][[-host hostName] -filepath path][-weight weight][-standalone][-notitle][-quiet][-help][bootFilePath]


System name of the new database.

-id dbId

Integer identifier of the new database (for example, 78). This option alsoaccepts the identifier specified in D-C-P-S format (for example, 78-0-0-0). Themaximum database identifier is 65535. If you omit this option, the identifieris generated by Objectivity/DB.

-host hostName

Data-server host of the new database. If you omit this option, the default hostis:




■ The current host, if -filepath specifies a local path.■ The host implied by -filepath, if an NFS mount name is specified.■ The host of the system-database file, if -filepath is also omitted.If -filepath specifies a Windows UNC share name, hostName is set to theliteral string oo_local_host; any value you specify is ignored.

-filepath path

Path to the new database file on the designated host. If the -host optionspecifies a remote system, path must be full, not relative.The path may optionally include the filename for the database; if you omitthe filename, it is generated automatically (see “Database Files” on page 32).If you omit both the -filepath and -host options, the default path consistsof a generated filename in the directory of the system-database file.

-weight weight

(HA) Weight of the new database (useful only if you plan to create additionaldatabase images). weight must be a positive integer. The default is 1. If thevalue is 0, oonewdb reports an error.

-standalone


-notitle


-quiet


-help


bootFilePath

Path to the boot file of the federated database to which the new database is tobe attached. You can omit this argument if you set the OO_FD_BOOTenvironment variable to the correct path. (HA) Specify the boot file of theautonomous partition that is to control the new database.

Discussion If both the -host nor the -filepath option are omitted, the database is createdwith a generated name in the same directory as the federated database’ssystem-database file. You can use oochangedb to move the new database to adifferent location.




(HA) You use oonewdb to create the first or only image of a database in afederated database. To replicate the database (that is, to create additionaldatabase images), you must use oonewdbimage; see Objectivity/DB HighAvailability.

oonewfdCreates a federated database, including the system-database file and the boot file.

oonewfd[-fdfilehost fdFileHost] -fdfilepath fdFilePath-lockserverhost lockServerHost[[-jnldirhost jnlDirHost] -jnldirpath jnlDirPath][-fdnumber fdId][-pagesize pageSize][-licensefile fileName][-weight][-bootonly][-standalone][-notitle][-quiet][-help][bootFilePath]

Options -fdfilehost fdFileHost

Data-server host of the new system-database file. If you omit this option, thedefault host is:■ The current host, if -fdfilepath specifies a local path.■ The host implied by -fdfilepath, if an NFS mount name is specified.If -fdfilepath specifies a Windows UNC share name, fdFileHost is set tothe literal string oo_local_host; any value you specify is ignored.

-fdfilepath fdFilePath

Path (including the filename) to the new system-database file on thedesignated host. If the -fdfilehost option specifies a remote system,fdFilePath must be full, not relative.

-lockserverhost lockServerHost

Host of the lock server servicing the new federated database.


Host of the new federated database’s journal directory. If you omit thisoption, the default host is:■ The current host, if -jnldirpath specifies a local path.■ The host implied by -jnldirpath, if an NFS mount name is specified.




■ The same as fdFileHost, if -jnldirpath is also omitted.If -jnldirpath specifies a Windows UNC share name, jnlDirHost is set tothe literal string oo_local_host; any value you specify is ignored.


Path to the new federated database’s journal directory. If the -jnldirhostoption specifies a remote system, jnlDirPath must be full, not relative.If you omit both the -jnldirhost and -jnldirpath options, the defaultpath is the directory part of fdFilePath.

-fdnumber fdId

Federated-database identifier that identifies the new federated database tothe lock server. The default value is 1. The maximum identifier is 65533.

-pagesize pageSize

Storage-page size (the size of the unit of storage transferred betweenmemory and disk) in bytes. Allowable page sizes are integer multiples of 8between 512 and 65,536, inclusive. The default page size is 8192 bytes.

-licensefile fileName

File containing the license for the new federated database. You mayoptionally include a path to the directory containing the file; if you specify afilename without a path, the file must reside in the current directory.If you omit this option, oonewfd uses the default license file oolicense.txtin the directory implied by bootFilePath. If no default license file is foundthere, oonewfd looks for it in the following location:■ (Windows) Objectivity/DB installation directory installDir

■ (UNIX) Your home directory; otherwise, the Objectivity/DB installationdirectory installDir

An error is reported and oonewfd terminates if no license file is found.

-weight weight

(HA) Weight of the new federated database (useful only if you plan to createadditional autonomous partitions). weight must be a positive integer. Thedefault is 1. If you specify 0, oonewfd reports an error.

-bootonly

Creates only the boot file, not the system-database file.

-standalone

Nonconcurrent mode. Use this option only if the lock server for the newfederated database is stopped. If the lock server is running, the tool reportsan error and terminates.




-notitle


-quiet


-help


bootFilePath

Path (including the filename) to the boot file of the new federated database.The filename may optionally include a filename extension, such as .boot.You can omit this argument if you set the OO_FD_BOOT environment variableto the correct path.

Discussion The federated database’s system name is the simple name of the boot file specifiedin bootFilePath. Once a federated database is created, you cannot change itssystem name.

A lock server must be running on lockServerHost while you run oonewfd.

Normally, you set the storage-page size to be the disk’s page size. However, youmight want to set the storage-page size to be slightly larger than the size ofcommon objects. For example, you might increase the page size if commonobjects are larger than the default, or decrease the page size if common objectsare smaller than the default. For information about choosing an optimal pagesize, see the chapter on performance in the documentation for your Objectivityprogramming interface.

ooquerysetDisplays information about one or more full backups, along with any incrementaland subincremental backups based on them.

ooqueryset[-time dateTime | -set setName][-quiet][-standalone][-notitle][-help][bootFilePath]

Options -time dateTime

Time of the full backup whose information is to be displayed. You can omitdateTime value to specify the current time, which displays informationabout the most recent full backup. If no full backup corresponds exactly to




the specified time, ooqueryset selects the latest full backup that was startedprior to the specified time.You specify dateTime as you would for oorestore—as an integerYYYYMMDDHHmm containing up to 12 digits representing component times. Forexample, 2001051502 specifies May 15, 2001 at 2:00 A.M.If you specify this option, you may not also specify the -set option.

-set setName

Name of the backup set whose information is to be displayed.If you specify this option, you may not also specify the -time option.

-quiet


-standalone


-notitle


-help


bootFilePath

Path to the boot file of the federated database whose backup set is to bequeried. You can omit this argument if you set the OO_FD_BOOT environmentvariable to the correct path. (HA) You can specify the boot file of anyautonomous partition.

Discussion To display information about basic backups (backups taken with options such as-full, -incremental, -subincremental, or -destination), you specify thethe -time option. This causes ooqueryset to display information for the mostrecent full backup prior to the specified time, along with any incremental backupsbased on it.

To display information about customized backups (backups taken with theoptions -set, -backup, -device, and -volume), you specify the -set option.This causes ooqueryset to display information for the backups in the specifiedbackup set.

If you omit both the -set and -time options, ooqueryset displays informationabout the backups in all backup sets, including any backup sets you created




explicitly for customizable backups and any backup sets created implicitly forbasic backups.

For each backup listed, ooqueryset displays the backup event name, the level,the backup volume capacity, the time stamp, the volume name prefix, and thepath to the disk directory where the backup files were written.

The ooqueryset command displays information from the federated database’sbackup diary. Restoring a federated database to an earlier backup reverts thebackup diary to an earlier version. Consequently, the backups listed byooqueryset for a restored federated database may be a subset of the backupsthat actually exist.

See also oocreatesetoodeleteset

oorestoreRestores a federated database previously archived using oobackup.

oorestore([-time timeOfRestore] [-source backupDir])

| (-set setName -backup backupName -volume volName-device deviceSpecifier)

[-quiet][-exists ask | delete | quit][-procfilesbef befProgName][-procfilesaft aftProgName][[-newhost targetHost] -newdirectory targetDir [-failonly]

| -dbmap mapFile ][-dumpcatalog][-purgeAps][-standalone][-notitle][-help][bootFilePath]

Options -time timeOfRestore

Time of the backup from which the federated database is to be restored. Thedefault is the current time, which causes the most recent backup contained inbackupDir to be restored.If no backup in backupDir corresponds exactly to timeOfRestore,oorestore selects the latest backup in backupDir that was started prior tothe specified time. If the selected backup is incremental, oorestore restoresboth the selected backup and the full backup on which it is based. Similarly,




if the selected backup is subincremental, oorestore restores the selectedbackup along with the incremental and full backups on which it is based.You specify timeOfRestore as an integer YYYYMMDDHHmm containing up to12 digits representing component times as follows:YYYY YearMM Month of the year (01 to 12). For example, 02 is February.DD Day of the month (01 to 31).HH Hour of the day (00 to 23). For example, 00 is 12:00 midnight,

01 is 1:00 A.M., 13 is 1:00 P.M., and 23 is 11:00 P.M.mm Minute of the hour (00 to 59)Do not insert spaces or delimiters between the component digits. You cantruncate digits (or specify 0’s) from right to left, to omit any irrelevant (orunspecified) detail. For example:200105 Specifies 12:00 A.M. on May 1, 2001. You could use this

timeOfRestore to select the most recent backup inbackupDir that was started before May 2001.

20010515 Specifies 12:00 A.M. on May 15, 2001. You could use thistimeOfRestore to select the most recent backup inbackupDir that was started before May 15, 2001.

This option may be used with the -source option.

-source backupDir

Full path to the disk directory containing the files for the backup to berestored. The default is to search the current directory (the directory in whichyou are executing oorestore) for the backup to be restored.This option may be used with the -time option.

-set setName

Name of the backup set containing the backup event representing the pointof restore. This option must be used with the -backup, -volume, and-device options.

-backup backupName

Name of the backup event representing the point of restore. This option mustbe used with the -set, -volume, and -device options.

-volume volName

Volume name prefix of the backup volumes containing the data to berestored. This option must be used with the -set, -backup, and -deviceoptions.

-device deviceSpecifier

Full path to the disk directory containing the backup volumes to be restored.For example, if the value for deviceSpecifier is /dba/backups and the




value for volName is fdb020492, then the actual disk filename for the firstbackup volume is /dba/backups/fdb020492_1.This option must be used with the -set, -backup, and -volume options.

-quiet



Action to take if a database in the archive file already exists.ask Prompts whether to overwrite the existing database. If the

answer is No, the program terminates. No is the default.delete Overwrites the existing database.quit Terminates if the database already exists.The default value is ask.

-procfilesbef befProgName

Executes the shell script or program befProgName before each backupvolume is opened for read access by oorestore. befProgName can contain afull or relative path. The name of the volume to be read is passed to the scriptas a command-line argument. If befProgName exits with a nonzero status,oorestore reports an error and terminates immediately.

-procfilesaft aftProgName

Executes the shell script or program aftProgName after oorestore finishesreading each backup volume. aftProgName can contain a full or relativepath. If aftProgName exits with a nonzero status, oorestore reports anerror and terminates immediately.

-newhost targetHost

Restores files to the new host targetHost, except for the backup boot file,which is restored to the host on which you are running this tool. Thejournal-directory property of the federated database or every autonomouspartition is set to targetHost.

-newdirectory targetDir

Restores files to the new directory targetDir, except for the backup bootfile, which is restored to the current working directory. The journal-directoryproperty of the federated database or every autonomous partition is set totargetDir (as a separate operation, you should reset each property to anappropriate unique directory).If targetHost designates a remote system, targetDir must be full, notrelative. targetDir must already exist (oorestore will not create it).




-failonly

Restores files to the location specified by -newhost and -newdirectoryonly if the files’ original locations are inaccessible. The specified backup bootfile is restored to the current working directory if its original location isinaccessible.

-dbmap mapFile

ASCII text mapping file that specifies the destination hosts and directoriesfor system-database files, boot files, journal files, and database files. Themapping file must be local to the directory in which oorestore is running.You cannot use this option with the -newhost, -newdirectory, or-failonly option.The mapping file contains one line for each file or journal directory to beremapped. Each line has the format:keyword systemName targetHost targetPath

wherekeyword Kind of file or directory to be remapped; either:

FD—federated-database system-database fileFDJNL—federated-database journal directoryDB—database fileAP—autonomous-partition system-database fileAPBOOT—autonomous-partition boot fileAPJNL—autonomous-partition journal directory

systemName System name of a federated database, database, orautonomous partition.

targetHost Host of the restored file or directory.targetPath Path to the restored file or directory. The directory portion of

the path must exist (oorestore does not create newdirectories).

Any file not specified in the mapping file is restored to its original location.The backup boot file is always restored to the current working directory.

-dumpcatalog

Displays the system names and original locations of all system-database files,boot files, journal files, and database files. The files are first restored to thecurrent working directory (overwriting any files already there), and thendeleted.oorestore always runs in standalone mode when this option is used sinceno usable federated database is generated.Warning: Invoking oorestore with this option deletes any system-databasefiles in the current working directory. Do not use this tool in a directory thatalready contains such files.




-purgeAps

(HA) Restores the backup as an unpartitioned federated database (that is, afederated database that has only a single implicit autonomous partition).Specifying this option restores the boot partition, its system-database file,and one image of each database in it. An image is also created for eachdatabase that did not previously have an image in the boot partition; suchimages are created in the default directory and have default constructedfilenames. Partitions other than the boot partition are purged from the globalcatalog, and their system-database files are not restored.You must specify this option in each of the following cases:■ If you specified the corresponding -purgeAps option on oobackup

when you took the backup now being restored.■ If you are restoring the federated database in a different environment

that doesn’t have the same set of hosts, or in the original environmentwhen some of the hosts are not accessible.

After the restore is complete, you can re-create partitions and distribute orreplicate databases as desired.

-standalone


-notitle


-help


bootFilePath

Path to the backup boot file for the federated database to be restored. You canomit this argument if you set the OO_FD_BOOT environment variable to thecorrect path. The backup boot file is the boot file that was used to create thebackup.Note: You must specify the original backup boot file path to oorestore,even if the backup boot file no longer exists or is no longer accessible. Aslong as the necessary backup volumes are accessible and undamaged, thecondition of the boot file or the boot-file host does not affect the restore.

Discussion The oorestore tool will fail if you run it in a directory that contains a file namedbootFilePath. This restriction applies even if you specify -exists delete. This




restriction safeguards your current backup boot file from the possibility of beingoverwritten by a restored version of the file.

When restoring a basic backup (a backup taken with options such as -full,-incremental, -subincremental, or -destination), you must perform abasic restore. To do so, you simply specify a point of restore (-time) and thedirectory containing the backup to be restored (-source). If you omit theseoptions, the most recent backup in the current directory is restored.

When restoring a customized backup (a backup taken with the options -set,-backup, -device, and -volume), you must perform a customized restore. To doso, you must specify the backup set name (-set), the backup event name(-backup), the volume name (-volume), and the full directory path (-device) ofthe backup event representing the point of restore.

Unless you specify otherwise, oorestore restores files to their original locations.If the original locations are not accessible, you can restore files to a single locationby specifying the -newhost and -newdirectory options, or you can restorefiles to multiple locations by specifying the -dbmap option with a mapping file(in either case, the backup boot file is always restored to the current workingdirectory). If files are restored to one or more nonoriginal locations, oorestoreautomatically adjusts all journal-directory properties as specified; if you havemultiple autonomous partitions, you should reset each journal-directoryproperty to a unique directory. Journal files themselves are not restored.

Restoring a federated database automatically consolidates fragmented space, sothe restored files may be significantly smaller than the original files.

See also oobackup

ooschemadumpWrites a representation of a federated database’s evolved schema to the specifiedoutput file.

ooschemadump[-encode][-outfile fileName][-standalone][-notitle][-quiet][-help][bootFilePath]

Options -encode

Encodes the output file so that it cannot be read by end users. If you omit thisoption, the schema change information is written as text.




-outfile fileName

Name of the file to which the schema representation is to be written. If youomit this option, the output will be written to a default file calledschema.dmp in the current directory.

-standalone


-notitle


-quiet


-help


bootFilePath

Path to the boot file of the federated database with the evolved schema. Youcan omit this argument if you set the OO_FD_BOOT environment variable tothe correct path. (HA) You can specify the boot file of any autonomouspartition.

Discussion You normally perform schema evolution on a source federated database at yourdevelopment site. When you are ready to test or deploy the evolved schema, youcan use ooschemadump to write the schema changes to an output file. You (or yourend users) then use ooschemaupgrade to apply the changes in this file to thedestination federated database (for example, your end user’s production federateddatabase).

(Objectivity/C++) Some complex schema-evolution operations require that yourun a conversion or upgrade application between uses of the DDL processor.When this is the case, you need to use ooschemadump after each use of the DDLprocessor, and before you run a conversion or upgrade application or continuewith any other schema-evolution operations. When you deploy the schemachanges, you must distribute all such ooschemadump output files to your enduser.




ooschemaupgradeUpgrades the schema of the specified federated database by applying the schemachanges contained in the specified file.

ooschemaupgrade[-infile fileName][-standalone][-notitle][-quiet][-help][bootFilePath]

Options -infile fileName

Name of the file containing the schema changes to be applied. The file mustbe the output of ooschemadump. If you omit the -infile option,ooschemaupgrade looks for a default file named schema.dmp in the currentdirectory.

-standalone


-notitle


-quiet


-help


bootFilePath

Path to the boot file of the destination federated database whose schema is toreceive the schema changes. You can omit this argument if you set theOO_FD_BOOT environment variable to the correct path. (HA) You can specifythe boot file of any autonomous partition.

Discussion You normally perform schema evolution on a source federated database at yourdevelopment site. When you are ready to test or deploy the evolved schema, youuse ooschemadump to write the schema changes from the source federateddatabase to an output file. You (or your end users) then use ooschemaupgrade toapply the changes in this file to the destination federated database (for example,your end user’s production federated database).




The schema of the destination federated database must be identical to the schemathat existed in the source federated database before schema evolution wasperformed.

The ooschemaupgrade tool enables you to deploy schema changes toproduction federated databases without disclosing the schema to end users—thatis, without:■ (Objectivity/C++) Running the DDL processor at end user sites■ (Objectivity for Java and Objectivity/Smalltalk) Including a compiler

oostartamsStarts the Advanced Multithreaded Server (AMS) on the current system.

oostartams[-numthreads numthreads][-notitle][-help]

Options -numthreads numthreads

Number of threads (or processes) the server should use to process concurrentclient requests. The default value is 8.

-notitle


-help


Discussion If AMS is already running, an error is reported. Only one AMS process per versionof AMS can run on any one system.

On UNIX, this command is typically placed in a startup script that runs when theserver system is booted. However, it can be executed at any time.

On Windows, you normally start AMS from an Objectivity Network Servicestool. You need administrator privileges to use this tool because AMS is started asa network service, not as a user program.

See also oostopams




oostopamsTerminates the Advanced Multithreaded Server (AMS) on the specified hostsystem, provided that there are no client applications using it. If clientapplications are running, an error is reported.

oostopams[-notitle][-help][hostName]

Options -notitle


-help


hostName

Name of the host system on which the AMS process is to be terminated. Thedefault is to terminate any AMS process running on the local host (the hoston which you are running this tool).

See also oostartams

oosupportinfoGenerates a report containing information needed by Objectivity CustomerSupport when diagnosing a problem with the specified federated database.

oosupportinfo[-detail [-db dbSysName | -id dbId | -all]][-outfile filename

[-exists ask | delete | quit]][-help][bootFilePath]

Options -detail

Includes information extracted from the federated database’s systemdatabase. You can omit this option to report only the federated database’susage environment.(HA) If the federated database has multiple autonomous partitions,information about each partition is included.




-db dbSysName

System name of the database to be included in the information given by-detail. If you use the -db option, you cannot use the -id or -all option.

-id dbId

Integer identifier (for example, 78) of the database to be included in theinformation given by -detail. The -id option also accepts the identifierspecified in D-C-P-S format (for example, 78-0-0-0). If you use this option,you cannot use the -db or -all option.

-all

Includes information about all databases in the information given by-detail. If you use the -all option, you cannot use the -db or -id option.

-outfile filename

Name of the file in which to write the generated report. You can omit thisoption to send all output to stdout.




-help


bootFilePath

Path to the boot file of the federated database to be reported. You can omitthis argument if you set the OO_FD_BOOT environment variable to the correctpath. (HA) You can specify the boot file of any autonomous partition.

Discussion When you report a problem to Objectivity Customer Support, you should includethe output of this command for the federated database that has the problem.

By default, oosupportinfo reports only on the operating environment in whichthe federated database is used—for example, the operating system, processortype, environment-variable values, and so on. You can specify -detail toinclude information specific to the federated database, such as its properties,whether the schema has been evolved, and so on. In addition to -detail, youcan specify -db, -id, or -all to include information about one or all databases.




ootidyConsolidates a fragmented database or federated database.

ootidy[-db dbSysName | -id dbId][[-tmpdirhost hostName] -tmpdirpath dirPath][-standalone][-notitle][-help][bootFilePath]


System name of the database to be tidied. By default, this tool tidies alldatabases within the specified federated database.

-id dbId

Integer identifier of the database to be tidied (for example, 78). This optionalso accepts the identifier specified in D-C-P-S format (for example, 78-0-0-0).By default, ootidy tidies all databases within the specified federateddatabase.

-tmpdirhost hostName

Host on which to create temporary files. If you omit this option, the defaulthost is:■ The host on which you are running this tool, if -tmpdirpath specifies a

local path.■ The host implied by -tmpdirpath, if an NFS mount name is specified.If -tmpdirpath specifies a Windows UNC share name, hostName is set tothe literal string oo_local_host; any value you specify is ignored.

-tmpdirpath dirPath

Path to the directory on the designated host in which to create temporaryfiles. If the -tmpdirhost option specifies a remote system, dirPath must befull, not relative. If you omit both the -tmpdirhost and -tmpdirpathoptions, temporary files are created in the directory of each database filebeing tidied.

-standalone


-notitle





-help


bootFilePath

Path to the boot file of the federated database to be tidied. You can omit thisargument if you set the OO_FD_BOOT environment variable to the correctpath. (HA) You can specify the boot file of any autonomous partition.

Discussion To hold temporary database files created during its execution, ootidy requiresfree disk space equal to the size of the federated database or database you aretidying.

Warning: To prevent potential database corruption, make sure that no otherprocesses access a database or federated database being tidied. Do not run ootidyand oobackup concurrently, because ootidy may delete objects that oobackupreferences.

One way to guarantee that no processes access the database is to kill the lockserver and to run ootidy with the -standalone option.

Warning: Do not run ootidy if you suspect that the federated database has beencorrupted. It can make the problem significantly worse.

ootoolmgrTool for browsing objects, browsing types, and making queries on UNIX.

ootoolmgr[-standalone][-notitle][-help][bootFilePath]

Options -standalone

Nonconcurrent mode. No lock server is required.

-notitle


-help


bootFilePath

Path to the boot file of the federated database to be browsed. If you omit thisargument, you can open the federated database from within the tool. (HA)You can specify the boot file of any autonomous partition.




Discussion See Chapter 4, “Browsing Objects and Types,” for information about using thebrowser.

See also oobrowse

281

<6/11/2003, 12:40 PM; /wrld/mnt09/pubs/working/admin/admDebugCommandRef.fm>

DRAFT

15oodebug Commands

This chapter describes the commands you can use in an oodebug session. Youcan run oodebug as a separate process on any platform, or you can run it withina C++ debugger (dbx and its variants) on UNIX.

See:■ “Reference Summary” on page 283 for an overview of oodebug command

capabilities described in this chapter■ “Reference Index” on page 284 for an alphabetical list of oodebug commands■ “Reference Descriptions” on page 285 for complete syntax and usage

descriptions of oodebug commands

For more information about oodebug, see Chapter 5, “Debugging a FederatedDatabase” and oodebug in Chapter 14, “Tools.”

Using oodebug Commands

Modes

oodebug has two modes: read and update. These modes determine whichoodebug commands are available for use. You can safely use read mode to viewthe structure and contents of your federated database.

However, update mode can be dangerous—use it with care. For example, acommon technique used in C++ to maintain consistency between attributes in anobject is to declare the attributes as private and allow access to the attributes onlythrough access methods. In update mode, oodebug allows direct access to theseattributes, bypassing the protection of the access methods.

Abbreviating Command Names

You can abbreviate an oodebug command by typing the first characters of thecommand name. You need type only enough characters to distinguish your

DRAFToodebug Commands Command Parameters



intended command from all available commands. For example, you can run thewhatis command by typing what, wh, or w.

Command Parameters

oodebug commands use these parameters:

object

Object on which to operate, specified in any of the following forms:■ Object identifier (OID)—Enter the object identifier in the form: D-C-P-S.

Optionally, you can use this form: #D-C-P-S.■ Object name in the federated database scope—Enter the name in the

form fdbSysName.objScopeName, where objScopeName is the scopename of the object.

■ Object name in a database scope—Enter the object scope name in theform dbSysName.objScopeName, where dbSysName is the databasesystem name and objScopeName is the object’s scope name.

■ Object name in a container or basic object scope—Enter the object in theform D-C-P-S.objScopeName, where D-C-P-S is the object identifier ofthe scope object, and objScopeName is the object’s scope name.Optionally, you can use this form: #D-C-P-S.objectName.

■ Last object used specification—When you perform a series of commandson the same object, use the exclamation point character (!) instead ofrepeating the object identifier or object name.

container

Container on which you want the function to operate.

nameOfLink

Name of a relationship (association) between two objects.

persistentClass

Name of a class in the schema that inherits from class ooObj.

fieldExpression

Attribute on which to operate, specified in one of the following forms:■ Attribute name—Enter the name of the attribute.■ Attribute of a nested class—Enter in the form y.z, where y is the class

and z is the attribute name.■ Array element—Enter in the form variable[index], where variable

is the array’s name and index is an element’s position in the array.

dbSysName

System name (as a character string) of a valid database.

DRAFToodebug Commands Reference Summary



Reference Summary

The following table provides an overview of oodebug commands. Availability ofthese commands depends on which mode is turned on and whether you arerunning oodebug as a separate process or within a C++ debugger (dbx and itsvariants) on UNIX.

Function Command Mode

dbxRead Update

Show object contents printwhatis

✓

✓

✓

✓

✓

✓

Follow relationships(associations)

iternext

✓

✓

✓

✓

✓

✓

List contained objects listcontslistdbslistobjs

✓

✓

✓

✓

✓

✓

✓

✓

✓

Change mode readupdate

✓

✓

✓

✓

—

Manage transactions abortcommit

✓

✓

✓

✓

—

Manipulate object contents addassigndelsub

—✓

✓

✓

✓

✓

✓

✓

✓

Create and delete objects deletenew

— ✓

✓

✓

✓

Other commands helpquitstats

✓

✓

✓

✓

✓

✓

✓

✓

✓

DRAFToodebug Commands Reference Index



Reference Index

abort Cancels the current transaction’s changes, then starts a newtransaction.

add Adds a relationship (association) between two objects.

assign Assigns a constant value to an attribute.

commit Makes the current transaction’s changes permanent in the federateddatabase, then starts a new transaction.

del Deletes an entire to-one, to-many, unidirectional, or bidirectionalrelationship (association).

delete Deletes a basic object or container from the federated database.

help Describes and lists syntax for oodebug commands.

iter Initializes an iterator for a to-many relationship (association).

listdbs Displays a list of the databases contained in the federated database.

listconts Displays a list of the containers in a database.

listobjs Displays a list of the basic objects in a container.

new Creates an object.

next Iterates to the next object in an iterator and displays its contents.

oodebug Alias for invoking the oodebug tool within a UNIX C++ debugger (dbxand its variants).

ooprint Alias for viewing the contents of an object within a C++ debugger,without invoking the oodebug convenience function.

print Displays an object’s contents in the same format used by theObjectivity/DB data browser (with default settings for the View menu).Displays all attributes of this object unless you specify the name of aparticular attribute to display.

quit Terminates oodebug.

read Sets the mode to read mode.

stats Displays statistics about the federated database that are generatedduring the current session. For information about the individualstatistical measurements, see Chapter 25, “Monitoring Performance,”in Objectivity/C++ Programmer’s Guide.

DRAFToodebug Commands Reference Descriptions



Reference Descriptions

abortCancels the current transaction’s changes, then starts a new transaction.

abort

Discussion Use commit or abort when in read mode to free any locks acquired during thecurrent transaction.

Mode Available in read and update mode, but not from within dbx.

Example This example aborts the current transaction and starts a new one.(*update) aborttransaction aborted(update)(read)

addAdds a relationship (association) between two objects.

add object nameOfLink objectToAdd

Parameters See “Command Parameters” on page 282.

Discussion You can use this command to add an object to any type of relationship.■ Used on a to-many relationship, it is functionally equivalent to the

add_nameOfLink C++ member function.■ Used on a to-one relationship, it is functionally equivalent to the

set_nameOfLink C++ member function.

Mode Available in update mode only.

sub Removes a relationship (association) between two objects.

update Sets the mode to update mode.

whatis Displays an object’s class or struct declaration.




assignAssigns a constant value to an attribute.

assign object fieldExpression = constantValue


Discussion Assigns a constant value to an attribute of any of the following types:■ char

■ float32, float64■ int16, int32■ unit8, uint16, uint32■ enum (integer value)■ ooRef(ooObj) (using format #D-C-P-S or D-C-P-S)

■ ooShortRef(ooObj) (using format #P-S or P-S)

You can assign values to fundamental types that belong to aggregate types, suchas individual array elements or attributes of structures. However, you need tofully qualify the fundamental type name. For example, if w is an array of int16within an object named schedule, then the following is a valid assignment:

assign schedule w[1] = 1234 // Valid assignment

If y is a structure that contains attribute z within an object named schedule, thefollowing is also a valid assignment:

assign schedule y.z = 1234 // Valid assignment

The following types of assignments are not valid:

assign schedule w = … // Not valid assignmentsassign schedule y = …


Example This example assigns the value 12 to the numberOfFunctionsCalled attribute oftype int32, in the object main with name scope Functions.(update) assign Functions.main numberOfFunctionsCalled = 12assignment succeeded(*update)




commitMakes the current transaction’s changes permanent in the federated database,then starts a new transaction.

commit

Discussion Use commit or abort when in read mode to free any locks acquired during thecurrent transaction.


Example This example shows how to commit a transaction.(*update) committransaction committed(update)

delDeletes an entire to-one, to-many, unidirectional, or bidirectional relationship(association).

del object nameOfLink



deleteDeletes a basic object or container from the federated database.

delete object


Discussion Warning: The delete command does not call the destructor before deleting theobject. Thus, before you use this command, you must manually perform theoperations that a destructor would have performed: oodebug commands assign,add, sub, and del.





Example This example shows how to delete an object by object identifier.(update)delete 4-19-11-24-19-11-2 deleted(*update)

This example shows how to delete an object by object name.

(update) delete theObject4-19-11-2 deleted(*update)

helpDescribes and lists syntax for oodebug commands.

help [commandName]

iterInitializes an iterator for a to-many relationship (association).

iter object nameOfLink


Discussion Use this command with the next command to follow an object’s relationships.

Example This example shows how to initialize an iterator for an object identified by theobject identifier 4-3-42-11, in order to iterate through its unidirectionalrelationships named calledBy.(read) iter 4-3-42-11 calledByiterator initialized(read)

listdbsDisplays a list of the databases contained in the federated database.

listdbs

Example This example lists the databases in the federated database.(read) listdbsFunctionsFiles(read)




listcontsDisplays a list of the containers in a database.

listconts dbSysName


Example This example shows how to display a list of the containers in database MyDB.(read) listconts MyDB#2-2-1-1 (class ooDefaultContObj)#2-3-3-1 (class ooContObj)(read)

listobjsDisplays a list of the basic objects in a container.

listobj container


Example This example shows how to display a list of the basic objects in a containeridentified by the object identifier 2-3-3-1.(read) listobjs 2-3-3-1#2-3-3-3 (class ObjectA)#2-3-3-5 (class ObjectB)(read)

newCreates an object.

new persistentClassName nearObject


Discussion Use to create any object in the schema, except for ooFDObj or ooDBObj, whichrequire special creation semantics.

Warning: The new command does not call a constructor after creating an object.After the new command has been used to create an object, VArray attributes areof size 0, associations are empty, and all other attributes are undefined. Therefore,when you use this command, you must manually perform the operations that a




constructor would have performed: oodebug commands assign, add, sub, anddel.


nextIterates to the next object in an iterator and displays its contents.

next

Discussion Use in conjunction with the iter command to follow an object’s relationships(associations).

Example Within a CASE federated database, the database called Functions contains acontainer called Main of class FunctionRep, which inherits from ooContObj. TheMain function represents the main function of a C++ program, and calls threefunctions, openFiles, processTransactions, and closeFiles. Thesefunctions are also stored as containers of the same class. A relationship namedCalls helps locate the three functions called by the main program. To ask thedatabase to display all of the functions called by container Main, you initialize aniterator, and iterate through all relationships.(read) iter Functions.main Callsiterator initialized

(read) next(read) nextFunctionRep #2-3-3-1 = { %systemName = "openFiles" …}(read) nextFunctionRep #2-4-3-1 = { %systemName = "processTransactions" …}(read) nextFunctionRep #2-5-3-1 = { %systemName = "closeFiles" …}…(read) nextend of iteration

(read)




oodebug convenience function

Alias for invoking the oodebug tool within a UNIX C++ debugger (dbx and itsvariants).

In a UNIX debugger, enter the following at the debugger command prompt:

oodebug objectRef_or_Handle

Parameters objectRef_or_Handle

Object reference or handle within the program you are debugging thatidentifies the object you want to view or change. objectRef_or_Handleindicates the name of an active variable of the class ooRef(className) orooHandle(className).

Discussion The oodebug convenience function makes all of the oodebug commands availablefrom within the debugger except for those that manage transactions and changemodes (such operations are controlled by the application you are debugging).Once you start oodebug, the debugger’s commands are not available until youterminate oodebug.

Before you can run oodebug, you must link the application you are debuggingwith the debug-enabled Objectivity/DB library and define the conveniencefunction to your debugger (see “Running oodebug in a C++ Debugger” onpage 72).

ooprint convenience function

Alias for viewing the contents of an object within a C++ debugger, withoutinvoking the oodebug convenience function.

■ In the Windows Visual C++ debugger, use the following function prototype:ooprint(&objectRef_or_Handle)

■ In a UNIX debugger (dbx and its variants), enter the following at thedebugger command prompt:ooprint objectRef_or_Handle

Parameters objectRef_or_Handle

Object reference or handle within the program you are debugging thatidentifies the object you want to view. objectRef_or_Handle indicates thename of an active variable of the class ooRef(className) orooHandle(className).

Discussion The ooprint convenience function is identical to the print command usedwithin oodebug, except ooprint does not have the optional fieldExpressionargument.




Before you can run ooprint, you must link the application you are debuggingwith the debug-enabled Objectivity/DB library and perform setup stepsappropriate to your platform (see “Using ooprint in a C++ Debugger” onpage 73).

printDisplays an object’s contents in the same format used by the Objectivity/DB databrowser (with default settings for the View menu). Displays all attributes of thisobject unless you specify the name of a particular attribute to display.

print object [fieldExpression]


Example This example displays the contents of an object identified by object identifier2-3-3-3.(read) print 2-3-3-3OBJECT_A #2-3-3-3 = { %scopeNames = { [#2-3-3-1] "object_a_1" } int32 a_int = 10 STRUCT_W a_struct_w = { uint8 w_uint8 = 100 int16 w_int16 = -1000 pointer w_ptr = 0x0 } ENUM_Z a_enum_z = F_ZERO 0 ooHandle(OBJECT_B) b_assocs[] <-> a_assoc = { #2-3-3-7 #2-3-3-9 #2-3-3-11 } ooHandle(OBJECT_B) uni_b_assocs[] : prop(lock,delete), inhibit(delete), version(move) = { #2-3-3-7 #2-3-3-9 } ooHandle(OBJECT_C) uni_c_association : version(copy) = #2-3-3-17 ooHandle(OBJECT_D) d_assoc <-> a_assoc : prop(lock), version(drop) = #2-3-3-19}(read)




This example shows how to display the contents of the x attribute of the objectidentified by object identifier 5-3-3-3.

(read) print 5-3-3-3 x55(read)

quitTerminates oodebug.

quit

Discussion If no changes are pending, quit aborts the transaction that originated when youstarted oodebug or issued a previous commit or abort command. If changes arepending in the current transaction, you must explicitly save or ignore changes withthe commit or abort commands. Pending changes are indicated by an asterisk inyour command prompt: (*read) or (*update).

Example This example shows how to terminate oodebug if changes are pending.(*update) quitpending updates, please commit or abort(*update) committransaction committed(update) quit%

readSets the mode to read mode.

read

Discussion Read mode allows you to enter all oodebug commands, except those that changethe structure or contents of the federated database. Read mode is indicated by oneof two prompts: (read), or (*read), depending on whether there are pendingchanges to commit to the federated database.


Example This example shows how to select read mode.(*update) read(*read)




statsDisplays statistics about the federated database that are generated during thecurrent session. For information about the individual statistical measurements,see Chapter 25, “Monitoring Performance,” in Objectivity/C++ Programmer’sGuide.

stats


Example This example shows sample Database Statistics. (read) stats

***************************************************Object Manager Statistics Wed Aug 09 21:21:22 2000

** Number of federated DBs created => 0** Number of federated DBs opened => 1** Number of federated DBs closed => 1** Number of federated DBs deleted => 0**** Number of databases created => 0** Number of databases opened => 2** Number of databases closed => 0** Number of databases deleted => 0**** Number of containers created => 0** Number of containers opened => 9** Number of containers closed => 11** Number of containers deleted => 0**** Number of objects Created => 0** Number of objects opened => 8390304** Number of multiple opens => 892** Number of new versions => 0** Number of objects closed => 8390304** Number of multiple closes => 892** Number of objects deleted => 0**** Number of objects named => 0** Number of new OCBs => 256** Number of new associations => 0** Number of disassociations => 0** Number of associations resized => 0** Number of transactions started => 1** Number of transaction commits => 1




** Number of commit and holds => 0** Number of transaction aborts => 0** Number of system aborts => 0******************************************************************************************************Storage Manager Statistics Wed Aug 09 21:21:22 2000

** Page size => 32768** Number of buffers used => 500** Number of large buffer entries => 200** Number of SM objects opened => 8390241** Number of SM objects created => 0** Number of objects still opened => 0** Number of buffers read => 5** Number of disk reads => 33865** Number of old pages written => 0** Number of new pages written => 0** Number of openHash calls => 1** Number of hash overflows => 0** Number of times OCs extended => 0** Number of Pages added to OCs => 0** Number of SM objects resized => 0************************************************(read)

subRemoves a relationship (association) between two objects.

sub object nameOfLink objectToSubtract


Discussion You can use this function to subtract an object from any type of relationship.■ Used on a to-many relationship, this is functionally equivalent to the

sub_nameOfLink C++ member function.■ Used on a to-one relationship, this is functionally equivalent to the

del_nameOfLink C++ member function.


updateSets the mode to update mode.

update




Discussion Update mode allows you to enter commands that change the structure andcontents of the federated database. Update mode is indicated by one of twoprompts: (update), or (*update), depending on whether there are pendingchanges to commit to the federated database. Update mode is intended for use bydatabase administrators and advanced users only.

Mode Available in read and update modes, but not from within dbx.

Example This example shows how to select update mode.(read) update(update)

whatisDisplays an object’s class or struct declaration.

whatis object


Discussion The format is the same as shown by the Type Browser.

Example This example shows how to display the class or struct declaration of an objectwith an object identifier of 5-3-3-1.(read) whatis 5-3-3-1class filetree : ooContObj { int32 numfiles;};

297

<6/11/2003, 12:40 PM; /wrld/mnt09/pubs/working/admin/admNetInst.fm>

DRAFT

ARunning Objectivity Servers on Windows

Objectivity servers include the lock server, the Advanced Multithreaded Server(AMS), and the Objectivity/SQL++ ODBC server. On Windows platforms, youmanage these servers using the Objectivity Network Services tool that isprovided with Objectivity/DB. This causes each server to run even when no useris logged on, and to start automatically whenever the system boots.

This appendix describes steps for:■ Starting and stopping Objectivity servers■ Configuring Objectivity servers■ Uninstalling and reinstalling Objectivity servers

Starting and Stopping an Objectivity Server

You use the Objectivity Network Services tool to start and stop Objectivityservers. To start or stop a server:

1. Log on as administrator or as a user with equivalent privileges.2. If necessary, install the server as a system service (see “Installing and

Uninstalling an Objectivity Server” on page 299).3. Click Start and point to Programs. In the Objectivity submenu, select

Objectivity Network Services.4. In Objectivity Network Services, select the desired server and either:

■ Click Start to start the server. At this point, the server will run while yoursystem is running, and will continue to run until stopped.

■ Click Stop to stop the server. Before you stop an Objectivity server,consult the documentation for that server.

DRAFTRunning Objectivity Servers on Windows Configuring an Objectivity Server



Configuring an Objectivity Server

You use the Objectivity Network Services tool to configure an Objectivity server.To do this:


Objectivity Network Services.3. In Objectivity Network Services, stop the desired server.4. With the server selected, click Configure. Different options are available,

depending on the server you selected:■ You can assign a different TCP/IP port to any server.

Note: If you change the TCP/IP port for a server, you must assign the sameTCP/IP port to that server on every other host running a process thatinteracts with the server.

■ You can specify various arguments to the lock server to controlautomatic recovery.

■ You can specify a nondefault log directory for the Objectivity/SQL++ODBC server.

5. When you have finished entering options for the selected server, click OK.6. Restart the server.

Specifying a Service’s Logon Account

You must start each server under a logon account that has appropriate accesspermissions.

Windows NT

To specify a logon account for an Objectivity server on Windows NT:

1. Log on as administrator or as a user with equivalent privileges.2. If necessary, use the Objectivity Network Services tool to stop the server.3. In Control Panel, double-click Services.4. In Services, select the desired Objectivity service, and click Startup.5. Specify the desired logon account.6. Use the Objectivity Network Services tool to restart the server.

DRAFTRunning Objectivity Servers on Windows Installing and Uninstalling an Objectivity Server



Windows 2000 and Windows XP

To specify a logon account for an Objectivity server on Windows 2000 orWindows XP:

1. Log on as administrator or as a user with equivalent privileges.2. If necessary, use the Objectivity Network Services tool to stop the server.3. In Control Panel, open Administrative Tools and double-click Services.4. In Services, double-click the desired Objectivity service.5. In Properties, click Log On and specify the desired logon account.6. Use the Objectivity Network Services tool to restart the server.

Installing and Uninstalling an Objectivity Server

By default, Objectivity servers are installed as system services automaticallyduring product installation. If you do not plan to run a particular server on yourmachine, you can uninstall it. Conversely, if you chose not to install anObjectivity server during product installation, and you can later install it.

To install or uninstall an Objectivity server, you:


Objectivity Network Services.3. In Objectivity Network Services, select the desired server and either:

■ Click Uninstall to uninstall the server.■ Click Install to install (or reinstall) the server.

DRAFTRunning Objectivity Servers on Windows Installing and Uninstalling an Objectivity Server



301

<6/10/2003, 4:21 PM; /wrld/mnt09/pubs/working/admin/admThirdPartyLicense.fm>

DRAFT

BThird-Party Software Used by Objectivity/DB

XML Export and Import Tools

Objectivity/DB tools for importing and exporting Extended Markup Language(XML) documents include software developed by the Apache SoftwareFoundation (http://www.apache.org/).

** The Apache Software License, Version 1.1*** Copyright (c) 1999-2000 The Apache Software Foundation. All rights* reserved.** Redistribution and use in source and binary forms, with or without* modification, are permitted provided that the following conditions* are met:** 1. Redistributions of source code must retain the above copyright* notice, this list of conditions and the following disclaimer.** 2. Redistributions in binary form must reproduce the above copyright* notice, this list of conditions and the following disclaimer in* the documentation and/or other materials provided with the* distribution.** 3. The end-user documentation included with the redistribution,* if any, must include the following acknowledgment:* "This product includes software developed by the* Apache Software Foundation (http://www.apache.org/)."* Alternately, this acknowledgment may appear in the software itself,* if and wherever such third-party acknowledgments normally appear.** 4. The names "Xerces" and "Apache Software Foundation" must* not be used to endorse or promote products derived from this

DRAFTThird-Party Software Used by Objectivity/DB XML Export and Import Tools


<6/10/2003, 4:21 PM; /wrld/mnt09/pubs/working/admin/admThirdPartyLicense.fm>

* software without prior written permission. For written* permission, please contact [email protected].** 5. Products derived from this software may not be called "Apache",* nor may "Apache" appear in their name, without prior written* permission of the Apache Software Foundation.** THIS SOFTWARE IS PROVIDED ‘‘AS IS’’ AND ANY EXPRESSED OR IMPLIED* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF* SUCH DAMAGE.* ====================================================================** This software consists of voluntary contributions made by many* individuals on behalf of the Apache Software Foundation and was* originally based on software copyright (c) 1999, International* Business Machines, Inc., http://www.ibm.com. For more* information on the Apache Software Foundation, please see* <http://www.apache.org/>.*/

303

<6/11/2003, 12:57 PM; /wrld/mnt09/pubs/working/admin/administrationIX.fm>

DRAFT

Index

A

abbreviatingoodebug commands 281tool options 181

abort, oodebug command 285access permissions 33

AMS 33, 105database file 86lock server 33, 94, 95

access status of database 77add, oodebug command 285administration tasks

backup and restore 29, 109creating and modifying

databases 28, 75federated databases 27, 39

exporting and importing data 147getting information 28, 42, 63, 78maintenance and recovery 29, 135managing Objectivity servers 29, 89, 103,

297overview 26

administration tools (see tools)Advanced Multithreaded Server (see AMS)AMS 25, 103

access permissions 33, 105changing TCP/IP port

on UNIX 107on Windows 107, 298

checking if running 104, 205configuring on Windows 298guidelines for choosing 104, 170

logon account on Windows 298oostartams 105, 275oostopams 106, 276output on Windows 107setting network timeout period 108specifying files 35starting 275


stopping 276on UNIX 106on Windows 106, 297

timeout errors 108application

failures, recovery from 136, 144IPLS application 91processes 23

argument, tool 181assign, oodebug command 286assigning

AMS porton UNIX 107on Windows 107, 298

lock-server porton UNIX 98on Windows 98, 298

Assist 27, 28, 182, 185configuring your own Eclipse for 185starting 185

attachingdatabase file 81multiple database files 83

DRAFTIndex



attributes(see also properties)persistent object 150XML element 150

automatic recovery (see recovery)autonomous partition 21

boot file 21, 33, 41configuring with import 165copying a federated database and 47file 21, 41filename 31global-catalog component 148importing 52, 153, 162

configuring 165merging with existing 155

initial 41, 44installing a federated database and 52listing files 42lock server for 91properties 41

changing 48listing 42

system name 21, 33system-database file 21, 41

B

backup 109, 190(see also restoring)basic 110before software upgrade 113boot file 112, 193, 271creating a backup set 131customized 110database corruption and 116deleting a backup set 122diary 111event

defined 110listing 122

failures 116full 110history, obtaining 122incremental 110, 128levels 110, 128

basic and customized 129medium 110, 127performing 115, 131processing volumes during 123querying a backup set 122, 265schedules

examples 115, 129guidelines 114, 129

scripts on UNIX 124set

creating 131, 215customized backups 126defined 111deleting 122, 219querying 122

subincremental 110to tape 125tools for 29user access during 112volume 127

basic object 21, 147exporting 148importing 153, 155

single 152boot file 22

autonomous partition 21, 33, 41backup 112, 193, 271federated database 20name 33

format for automatic recovery 142placement for Windows clients 172

browser 193, 279data 64opening

on UNIX 68on Windows 67

query 66type 65

browser tool 63buffer page (see page)

C

cache (see Objectivity/DB cache)

DRAFT Index



case sensitivity 37changing

AMS porton UNIX 107on Windows 107

autonomous-partition properties 48database identifier 85database properties 85, 197database system name 85federated-database properities 194federated-database properties 48lock-server host 96lock-server port

on UNIX 98on Windows 98

checkingAMS 104, 205lock server 93, 205

classexporting 148, 237importing 153, 155

single 152internal 148

client host 25, 169failures, recovery from 137, 145

commit, oodebug command 287configuring

AMS on Windows 298autonomous partitions with import 165backup scripts on UNIX 124lock server on Windows 298

container 20, 148exporting 148identifier 58

appears out of range 255, 258importing 153, 154

single 152maximum number in database 60number of logical pages in 60

convenience functionoodebug 72ooprint 73

copyingdatabase file 80, 211

federated database 47, 213with import 159

corruptiondetecting during a backup 116ootidy 54, 87restoring after detecting 116

creatingbackup set 215database 28, 79, 261federated database 27, 43, 263mapping file for restore 120unattached database 80

customer support 15generating report for 276

D

data 21, 147exporting 148, 228importing 153packing 157

data browser (see browser)data replication (see database image)data-server host 25, 169

UNIX 172Windows 170

data-server software 25, 103AMS 103, 170best for automatic recovery 143choosing 104local files 25NFS 103, 170remote files 25Windows Network 103, 170

database 20access

permissions 86troubleshooting 87

attachingfile 81guidelines 83multiple files 83

copying to file 80, 211creating 79, 261

DRAFTIndex



defragmenting 86deleting 86, 216distributed (see distributed databases)duplicating in a federated database 82exporting 148, 201, 229file 21, 76filename 32format, finding 241getting file information 78getting properties 78global-catalog component 148identifier 21

changing 85displaying 78format 58, 76setting 79

image (see database image)importing 153, 154, 161, 162

filtering out 163specifying filenames and locations 164specifying identifier 164specifying system name 163

maximum number 60maximum size 61moving file 80moving to another federated database 81page size, displaying 78properties 76

changing 85listing 78

read-only 77, 199repacking data 161restricting access 77, 86system name 21

changing 85displaying 78

tidying 86tools 181

for creating and modifying 28for getting information 28

database image 21, 77importing 162, 165

D-C-P-S format 58DDL processor

creating 210debugging

federated database 216, 281ooprint 73

defragmenting (see tidying)del, oodebug command 287delete, oodebug command 287deleting

backup set 122, 219database 86, 216federated database 49, 218

deploying Objectivity/DB applications 173distributing libraries

UNIX 176Windows 175

distributing Objectivity executables 174installing a federated database 178

diary, backup 111directory

AMS 105journal 22Objectivity server 92

disk space requirements 59displaying

file informationdatabase 78federated database 42

license 51properties

database 78federated database 42

properties]sautonomous partition 42

support information 276distributed databases 25, 169

importing 164recovery considerations 142

distributing at deploymentlibraries

UNIX 176Windows 175

Objectivity executables 174drive mapping, virtual 171DRO (see Objectivity/HA)

DRAFT Index



dumping(see also exporting)evolved schema 272

duplicatingdatabase in a federated database 82global catalog 162schema 166

E

Eclipse Platform 185configuring for Assist 185

end-user site deployment 51end-user tasks

distributing runtime tools 174installing a federated database 178

environment variableOO_CONNECT_RETRIES 99, 108OO_FD_BOOT 37, 68OO_RPC_TIMEOUT 99, 108setting 37

estimating federated-database size 59exclusive lock 90exporting 147

basic objects 148, 228classes 148, 237commands 225, 228, 233, 237

overview 148containers 148, 228data 148, 228database 148, 168, 201, 229federated database 52, 147, 148, 159, 160,

233global catalog 148, 162, 225output files 151persistent objects 148, 228schema 148, 166, 237tasks

copying a federated database 159duplicating a schema 166duplicating database structure 162merging a federated database 160transferring data 168

Extensible Markup Language

(see XML document)external references, import and 158

F

failuresapplication 136, 144client host 137, 145lock server 140, 146

fault tolerance (see autonomous partition)federated database 20

backing up 109changing

lock-server host 96properties 48

copying 47, 213with export and import 159

creating 43, 263database format 241debugging 216, 281defragmenting 278deleting 49, 218destination, of import 153displaying license 51, 253dumping evolved schema 272estimating size 59exporting 52, 147, 148, 159, 160, 233file 20, 40filename 31garbage collection 242getting file information 42, 241getting support information 276global-catalog information 121identifier 57

setting 44importing 52, 159, 160, 243installing 51, 249journal directory 44license in 41, 49listing files 42, 223lock server for 89merging, with export and import 160moving 48OO_FD_BOOT environment variable 37properties 40

DRAFTIndex



changing 48listing values 42

reference number 57repacking data 159restoring from backup 116, 132source, of export 147storage-page size

changing 40, 48, 52, 159choosing 44displaying 43

system name 20, 31system-database file 20, 40tidying 53tools

for creating and modifying 27for getting information 28

updating license 50, 253file

(see also boot file)(see also journal file)(see also XML file)database 21, 76license, setting up 49listing

autonomous partition 42federated database 42

Objectivity/DB 19placement in mixed OS environment 172specifying local 34specifying remote

AMS 35NFS 35Windows Network 36, 171

system-databaseof autonomous partition 21, 41of federated database 20, 40

filenameboot file 33case sensitivity 37database file 32host format 34journal file 32spaces in 36system-database file

of autonomous partition 31

of federated database 31FTO (see Objectivity/HA)full backup 110

G

garbage collection tool 242generated filename

database 32journal file 32

getting information, tools for 28global catalog 20, 148

exporting 148, 162, 225importing 156, 162, 243

configuring partitions and images 165filtering out databases 163specifying database identifier 164specifying database system name 163specifying filenames and locations 164

listing files in 42, 223

H

HA abbreviation 14header page (see page)help, oodebug command 288high availability (see Objectivity/HA)host format filename 34

I

identifierautonomous partition

getting 43database 21, 58

getting 78setting 79

D-C-P-S format 58federated database 57

getting 43setting 44

impact of importing on 157image (see database image)importing 147, 152, 243

DRAFT Index



add-only policy 153autonomous partitions 153, 155, 159, 165basic objects 153, 168classes 153, 166, 167clustering and 156command 152configuring partitions and images 165containers 153, 168data 153, 168, 243databases 153

group of 161federated database 52, 159, 160, 243filtering out databases 163global catalog 156, 243

duplicating 162modifying 162

identifiers and 157install file 156, 163merging into existing destination 154object identifiers (OIDs) and 157packing data 157persistent objects 168, 243references and relationships 158schema 153, 166, 243specifying database identifier 164specifying database system name 163specifying filenames and locations 164structures created by 153tasks

copying a federated database 159copying a group of databases 161duplicating a schema 166duplicating database structure 162merging a federated database 160modifying global catalog 162specifying filenames and locations 164transferring data 168

incremental backup 110, 128in-process lock server (see lock server,

in-process)install file

produced by export 151used by import 156, 163

installing

a server on Windows 299end-user federated database 178federated database 51, 249

internal class 148IPLS abbreviation 14iter, oodebug command 288

J

journal directory 22specifying 44

journal file 22automatic recovery and 135federated database 44name 32

K

kernel, Objectivity/DB 23, 25killing a lock server (see stopping)

L

large objects 24latches 255, 258license 41, 49

displaying 51, 253file, setting up 49updating 50, 253

listconts, oodebug command 289listdbs, oodebug command 288listing

active transactions 56autonomous-partition files 42autonomous-partition properties 42backups 122database properties 78, 197federated-database files 42, 223federated-database properties 42, 194locks 258transaction information 57waiting transactions 57, 254

listobjs, oodebug command 289loading (see importing)

DRAFTIndex



local data server (see Objectivity/DB kernel)lock file, recovery 146, 210lock server 23, 89

access permissions 33, 94, 95, 142applications cannot connect 100automatic recovery 298

initiating 140changing TCP/IP port


checking if running 93, 205configuring on Windows 298crash recovery 146enabling

automatic recovery at startup 140recovery monitor thread 138, 259

failures, recovery from 140, 146host 25, 90, 169

changing 96UNIX 172Windows 171

in-process 91log file 92logon account on Windows 298output on Windows 98recovery error log 92recovery monitor thread 138, 259setting network timeout period 99standard 91starting 259

on UNIX 94, 95on Windows 93, 94, 297problems 99, 100

stopping 252on UNIX 96on Windows 95, 297problems 96

system directory 92timeout errors 99uninstalling on Windows 94

locksexclusive lock 90intention lock 258listing 258

problems 99read lock 90update lock 90

logical page (see page)

M

manual recovery 143, 206mapping drives, virtual 171mapping file

attaching multiple databases 83, 187specifying locations for restore 120, 270

Microsoft Windows (see Windows)monitoring for client-host failures 138moving

database file 80database to another federated database 81federated database 48

N

networkconsiderations 25impact on performance 169share names 171timeout period 99, 108

recovery monitor and 139Network File System (see NFS)new, oodebug command 289next, oodebug command 290NFS 25, 103

specifying files 35user ID of Windows application 171Windows client 171

O

objectbrowsing 63large 24

object identifier (OID)container 58database 58D-C-P-S format 58

DRAFT Index



import operation does not preserve 157persistent object 57

Objectivity license (see license)Objectivity Network Services 26, 29, 182, 186

using 297Objectivity server system directory 92Objectivity servers

AMS 103lock server 89Objectivity/SQL++ ODBC server 297tools for managing 29, 297

Objectivity/DBbackup 109basics 19cache 24files 19kernel 23, 25naming files 33processes 19recovery 135release and database format 241tools 181

Objectivity/DB High Availability (see Objec-tivity/HA)

Objectivity/DB In-Process Lock Server(see lock server, in-process)

Objectivity/DRO (see Objectivity/HA)Objectivity/FTO (see Objectivity/HA)Objectivity/HA 21, 41, 77

(see also autonomous partitions)(see also database image)

Objectivity/SQL++ ODBC server 297Objy.xsd file 149, 244ObjyTool 26, 30, 182objytool 186ODMG abbreviation 14OID (see object identifier)OO_CONNECT_RETRIES environment

variable 99, 108OO_FD_BOOT environment variable 37, 68oo_local_host 36OO_RPC_TIMEOUT environment variable

99, 108

ooams-xx service 107ooattachdb 28, 81, 82, 182, 186oobackf script 124oobackup 29, 115, 131, 182, 190

ootidy and 115oobrowse 28, 67, 182, 193oochange 27, 28, 42, 48, 97, 182, 194oochangedb 28, 78, 80, 85, 178, 182, 197oocheck 29, 55, 182, 201oocheckams 29, 104, 182, 205oocheckls 29, 93, 104, 182, 205oocleanup 29, 56, 96, 97, 139, 144, 182, 206ooconfig 30, 182, 210oocopydb 28, 80, 81, 182, 211oocopyfd 27, 47, 178, 182, 213oocreateset 29, 131, 182, 215oodbxx.dll 175ooddlx 44, 166

created by ooconfig 210schema, loading a 44

oodebug 30, 182, 216, 281aliases 291command parameters 282convenience function 72, 291modes

read 70, 281update 70, 281, 295

quitting 71, 73running

as separate process 70from UNIX C++ debugger 72

oodebug commandsabort 285add 285assign 286commit 287del 287delete 287help 288iter 288listconts 289listdbs 288listobjs 289

DRAFTIndex



new 289next 290oodebug convenience function 291ooprint convenience function 291print 292quit 293read 293stats 294sub 295terminate 73update 295whatis 296

oodeletedb 28, 81, 86, 182, 216oodeletefd 27, 49, 182, 218oodeleteset 29, 122, 182, 219oodump 182, 220oodumpcatalog 28, 42, 78, 182, 223ooendb script 124ooendr script 124ooexportcatalog 27, 148, 162, 183, 225ooexportdata 27, 148, 168, 183, 228ooexportfd 27, 52, 148, 159, 160, 161, 183, 233ooexportschema 27, 148, 166, 167, 183, 237oofile 28, 42, 78, 183, 241oogc 29, 183, 242ooimport 27, 52, 152, 159, 160, 161, 162, 166, 168,

183, 243ooinstallfd 27, 48, 51, 183, 249ookillls 29, 96, 183, 252oolicense 27, 183, 253oolistwait 28, 57, 96, 183, 254ooload 183, 255oolockmon 28, 29, 96, 97, 183, 258oolockserver 29, 94, 183, 259ools-xx service 98oonewdb 28, 79, 183, 261oonewfd 27, 44, 159, 162, 166, 183, 263ooprint convenience function 73, 291ooqueryset 29, 122, 183, 265oorecvr.LCK file 146, 210oorestfa script 124oorestfb script 124

oorestore 29, 116, 132, 183, 267ooschemadump 183, 272ooschemaupgrade 27, 183, 274oostartams 29, 105, 183, 275oostopams 29, 106, 183, 276oostrtb script 124oostrtr script 124oosupportinfo 28, 183, 276ootapebackup 125

configuring scripts 124ootaperestore 125

configuring scripts 124ootidy 29, 53, 184, 278

guidelines for using 54oobackup and 54, 87

ootoolmgr 28, 68, 184, 279option, tool 181

P

packing data 157page

buffer page 24header page, for large object 24logical page 24

in object identifier (OID) 58page size

changing 40, 48, 52, 159displaying 43, 78

storage page 23federated-database property 40

partition (see autonomous partition)permissions (see access permissions)persistent object 147

browsing 63exporting 148, 228importing 153, 168, 243iterating 290large 24

point of restore 111port

AMS 106conflict 97, 106

DRAFT Index



lock server 97print, oodebug command 292printing object contents in debugger 73properties

autonomous partitionchanging 48listing 42

database 76changing 85, 197listing 78

federated database 40changing 48, 194listing 42

property 150

Q

query browser (see browser)quit, oodebug command 293

R

read lock 90read, oodebug command 293read-only database 77recovery 135

application failures 136, 144, 145automatic 135, 206boot-file name format 142client-host failures 137, 145error log 92lock file for 146, 210lock-server failures 140, 146manual 143, 206monitor 138, 259oocleanup failure 146

reference number for federated database 57remote data server (see AMS)repacking data 157replicated database (see database image)report, for Objectivity Technical Support 276restoring 267

(see also backup)after detecting corruption 116

entire federated database 111, 129failure 121from backup 116, 132from tape 125mapping file 120point of restore 111

specifying 116, 132processing volumes during 123scripts on UNIX 124to multiple locations 119to original location 117to single location 118user access while 112, 119

restricting accessdatabase file 86read-only database 77

return status 26rolling back incomplete transactions 135RPC timeout period (see network, timeout

period)runtime tools 174

S

schedule, defining backup schedule 114, 129schema 20, 148

dumping after evolution 272exporting 148, 166, 237importing 153, 155, 166, 243loading with import 166loading with ooddlx 44upgrading after evolution 274

schema evolution 20applying changes 274dumping changes 273

scripts for backup 124server

(see data-server software)(see Objectivity servers)

setting upEclipse Platform for Assist 185

software upgrade, backing up before 113spaces in filenames 36specifying

DRAFTIndex



filenames 31local files 34remote files

AMS 35NFS 35Windows Network 36

standard lock server 91starting

AMS 275on UNIX 105on Windows 105, 297

in-process lock serveron UNIX 95on Windows 94

lock server 259on Windows 297

standard lock serveron UNIX 94on Windows 93

stats, oodebug command 294stopping

AMS 276on UNIX 106on Windows 106, 297

lock server 252on UNIX 96on Windows 95, 297

storage page (see page)sub, oodebug command 295subincremental backup 110support information 276system name

(see autonomous partition)(see database)(see federated database)

system-database filefilename 31of autonomous partition 21, 41of federated database 20, 40

T

TCP/IPconfiguration problems 101

portAMS 106conflict 97, 106lock server 97

tidyingdatabase 86federated database 53, 278

timeout period, network 99, 108tool

argument 181option 181overview 26return status 26

Tool Manager 68, 279tools 97

Assist 185graphical interface

Objectivity Network Services 186ObjyTool 186oobrowse 193

Objectivity Network Services 26, 186, 297ObjyTool 26objytool 186ooattachdb 81, 82, 186oobackup 115, 131, 190oobrowse 193oochange 42, 48, 97, 194oochangedb 78, 80, 85, 178, 197oocheck 55, 201oocheckams 205oocheckls 93, 104, 205oocleanup 56, 97, 139, 144, 206ooconfig 210oocopydb 80, 81, 211oocopyfd 47, 178, 213oocreateset 131, 215oodebug 216oodeletedb 81, 86, 216oodeletefd 49, 218oodeleteset 122, 219oodump 220oodumpcatalog 42, 78, 223ooexportcatalog 148, 162, 225ooexportdata 148, 168, 228

DRAFT Index



ooexportfd 52, 148, 159, 160, 161, 233ooexportschema 148, 166, 167, 237oofile 42, 78, 241oogc 242ooimport 52, 152, 159, 160, 161, 162, 166,

168, 243ooinstallfd 48, 51, 249ookillls 96, 252oolicense 253oolistwait 57, 96, 254ooload 255oolockmon 96, 258oolockserver 94, 259oonewdb 79, 261oonewfd 44, 159, 162, 166, 263ooqueryset 122, 265oorestore 116, 132, 267ooschemadump 272ooschemaupgrade 274oostartams 105, 275oostopams 106, 276oosupportinfo 276ootapebackup 125ootaperestore 125ootidy 53, 278ootoolmgr 68, 279

transactionaborting 285committing 287handling 71listing 56, 254recovering incomplete 135, 206

troubleshootingdatabase access 87getting support information 276listing active transactions 56listing transaction information 57listing waiting transactions 57solving lock problem 99starting lock server 99stopping a lock server 96

type browser (see browser)typographical conventions 14

U

UNC namesfor remote Objectivity/DB files 36, 171

uninstalling a server on Windows 299Universal Naming Convention

(see UNC names)UNIX

browser 68clients 35, 170, 172

setting up automatic recovery 140data servers 172

setting up automatic recovery 143lock-server host 172running oodebug in C++ debugger 72starting server

AMS 105lock server 94, 95

stopping serverAMS 106lock server 96

user account for Objectivity servers 94, 95,105

viewing objects in debugger 73update lock 90update, oodebug command 295upgrading

applying schema changes 274getting database format 241

utilities (see tools)

V

viewingclass definitions 65object contents in debugger 73objects 64

virtual drive mapping 171

W

whatis, oodebug command 296Windows

AMS output 107browser 67

DRAFTIndex



clients 35, 170setting up automatic recovery 140

data servers 170setting up automatic recovery 143

installing an Objectivity server 299lock-server host 171lock-server output 98logon account for Objectivity servers 94,

105, 298running Objectivity servers 297starting

AMS 297lock server 297

starting serverAMS 105lock server 93, 94

stoppingAMS 297lock server 297

stopping serverAMS 106lock server 95

UNC names and Objectivity/DB 36, 171uninstalling an Objectivity server 299viewing objects in debugger 73virtual drive mapping 171

Windows Networkfor accessing Objectivity/DB files 170specifying files 36

WSAEADDRINUSE error message 98

X

XML document 147condensing 151exporting 225, 228, 233, 237importing 243readability 150

XML element 147, 148form of 150top-level 149

XML filefor exported XML document 151install file

produced by export 151

used by import 156XML Schema for Objectivity/DB 148, 168xooddlx

created by ooconfig 211

Documents

Objectivity/DB Administration