John F.
What is the recommended setting for logvolmaxsize?
The initial size for log volumes is defined in the profile.be file, which defaults to 24 megabytes. These volumes expand automatically as required during database use.
Actian 9 .3 Versant Server User Guide
Versant Server 9 9.3 is a powerful object database management system designed to enhance performance in complex, distributed and heterogeneous environments. It simplifies the process of developing and deploying transactional, distributed applications.
PDF
Document
Advertisement
Advertisement
Versant Server Guide
Release 9
Versant Server Guide: Release 9
Versant Server 9.3
Copyright © 2001–2017 Versant Software LLC and Copyright © 2013–2017 Actian Corporation. All rights reserved.
The software described in this document is subject to change without notice. This document does not represent a commitment on the part of Versant or Actian. The software is furnished under a license agreement or nondisclosure agreement and may be used or copied only in accordance with the terms of the agreement. No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, or for any purpose without the express written permission of Actian.
Versant uses functionality provided in libraries supplied by third parties. License agreements for these third party libraries are provided along with the libraries in the lib directory in the Versant installation.
Versant, Versant Server, Versant Object Database and FastObjects are either registered trademarks or trademarks of Versant
Software LLC in the United States and/or other countries.
Java and all Java-based marks are trademarks or registered trademarks of Oracle Corporation in the United States and other countries.
Eclipse and Built on Eclipse are trademarks of Eclipse Foundation, Inc.
Microsoft, Windows, Visual C#, Visual Basic, Visual J#, and ActiveX are either registered trademarks or trademarks of Microsoft
Corporation in the United States and/or other countries.
All other products are a registered trademark or trademark of their respective company in the United States and/or other countries.
9.3.0.4_1943—2017.04.12
Table of Contents
Versant Server Guide iii
5.1.1.1. Database System Administrator—DBSA .................................................... 60
iv Versant Server Guide
5.3.1.3. DBA Authentication for Session Connection ............................................ 68
Versant Server Guide v
9.2.1. Maintaining the Warm Standby Database Up-to-date ........................................ 188
vi Versant Server Guide
10.10.6. -volume—Get Information About Storage Volumes ......................................... 230
10.10.8. -AT—Viewing Consistency and Maintenance of AT Table ................................. 236
10.10.10. -class—Get Information About All Classes in a Database ............................. 241
10.10.11. -dbalog—Get Information About Logging Activities ..................................... 242
10.10.12. -space, -AT—Get Information on Fragmentation and Free Space ................... 244
10.10.13. -schevol—Get Information About Schema Evolution .................................... 247
10.10.14. -schevol -evol—Evolve Instances to the Latest Schema ............................... 248
Versant Server Guide vii
viii
10.23.3.1. Fragmentation Effects on Performance ............................................... 313
10.23.3.3. When to Run a De-fragmentation? ..................................................... 314
10.23.3.4. How often to run a de-fragmentation? ................................................ 316
Versant Server Guide
List of Figures
Versant Server Guide ix
x Versant Server Guide
List of Tables
Versant Server Guide xi
xii Versant Server Guide
List of Examples
Versant Server Guide xiii
xiv Versant Server Guide
Contact Information for Actian
You can obtain the latest information about Actian products by contacting either of our main office locations, visiting our web sites, or sending us an email.
Actian Office Locations
Actian Corporation is headquartered in Palo Alto, California. Actian Versant products are developed in
Hamburg, Germany.
Actian Corporate Headquarters
Actian
2300 Geng Rd., Suite 150
Palo Alto, CA 94303
USA
+1.888.446.4737 [TEL—Toll Free US]
+1.650.587.5500 [TEL]
+1.650.587.5550 [FAX]
Actian Versant Development Center
Versant GmbH
Halenreie 42
D-22359 Hamburg
Germany
+49 (0)40 609 90 0 [TEL]
+49 (0)40 609 90 113 [FAX]
Actian Web Site
For the latest corporate and product news, visit the Actian web site at: http://www.actian.com/
Versant Server Guide xv
Actian Versant Products
For inquiries about Actian Versant products and services, contact: [email protected]
For help in using Actian Versant products, contact Technical Support at: [email protected]
The Actian Customer Portal provides all the essential information and valuable resources needed by developers using Versant Object Database. Visit the Actian Customer Portal at: http://support.actian.com/
(You will need an Actian ID to login. If you do not have an Actian ID, follow the Register link on that page to create one.)
Trial Evaluation Support
If you are using the Versant Trial Evaluation and have questions or need help, you can get quick answers.
Contact Trial Evaluation Support at: [email protected]
Please send feedback regarding this guide to: [email protected]
xvi Versant Server Guide
Chapter 1. Introduction
Sections
- Versant Storage Architecture
This chapter gives a brief overview of Versant, its architecture and data management. Versant is an
Object Database Management System (ODBMS). It has been designed to enhance performance in complex, distributed and heterogeneous environments and to simplify the process of developing and deploying transactional, distributed applications.
As a standalone database, Versant is designed to meet customers' requirements for high performance, scalability, reliability and compatibility with disparate computing platforms and corporate information systems.
Versant has established a reputation for exceeding the demands of mission critical enterprise business applications providing reliability, integrity and performance. The efficient multi-threaded architecture, internal parallelism, balanced client/server architecture and efficient query optimization of Versant delivers unsurpassed levels of performance and scalability.
Versant Server Guide 1
2
Versant Components
1.1. Versant Components
Versant 9.3 consists of the following standard and optional, add-on components (the add-on components listed below require an additional, separate license).
Table 1.1. Standard components
Component
Versant Server
Versant C++
Versant JDO
Java Versant Interface
Versant Management Center
Description
Versant server and database management component
C++ language interface
Java Data Objects—JDO interface
Versant proprietary Java language interface
Versant GUI database management tool
Table 1.2. Add-on components
Component
Versant AsyncReplication
Versant FTS
Versant HABackup
Description
Asynchronous replication for Versant
Fault-tolerant server (FTS) component for Versant
Backup solution for use with a high-availability server
All of the Versant add-on components require a separate license.
Versant Server Guide
Versant Features
1.2. Versant Features
Versant is an object database management system that includes all features needed for scalable production databases in a distributed, heterogeneous workgroup environment. Following is a brief overview of the
Versant features.
1.2.1. Data as Objects
Versant models data as objects. The Versant implementation of objects allows:
• Custom definition of complex data types
• Encapsulation of data and code
• Inheritance of data and code
• Code reuse
• Polymorphism
• Unique identification of objects
1.2.2. Database Features
Versant features include:
• Persistent storage of data
• Concurrent access by multiple users
• Concurrent access to a session by multiple processes or threads
• Multiple sessions, including sessions containing no processes
• Transaction management
• Recovery from system failures
• Navigational and search condition queries
Versant Server Guide 3
Versant Features
• Remote database connections
• Data versions
• User defined security
• Two-phase commits
• You can create a distributed database system containing a combined total of 2^16 databases
• Multiple standard language interfaces
• Heterogeneous platforms
• Use of multiple threads by the database server
• Use of multiple latches by the database server
• Unique indexes
1.2.3. Database System
Versant database system features support:
• Distribution of data, including the ability to migrate objects
• A client/server model of hardware utilization
• Query processing on servers
• Dynamic management of database schema
• Tuning options for applications and databases
• Object level locking
• Object caching on the client and page caching on the server
• Clustering of instances of a class
• Files for data storage
• Indexing for query optimization
4 Versant Server Guide
Versant Features
• Ability to turn locking and logging ON and OFF
• On supported platforms and interfaces, multiple process or multiple thread applications
• Data replication on numerous databases
• Independence from OS passwords for DBA
• Support for password authentication for database utilities
• Support for External User Authentication (Plugins)
• Support for Windows Terminal Server
1.2.4. Database Administration
Versant database administration utilities support:
• Creating, expanding and deleting databases
• Backing up data
• User authorization
• Custom system configurations
• Modification of data definitions
• Creation of classes at run time
1.2.5. Application Programming
Application programming features support:
• All features of access languages, including flow of control.
• Versant provides application programming interfaces for C++ and Java.
• Custom and third party libraries of code and data types
• Multiple kinds of atomic work units, including transactions, checkpoints and savepoints.
Versant Server Guide 5
Versant Features
• Predefined data types and management routines
• Proprietary and third party programming tools
• Control of process and shared memory, including explicit pinning of data.
• Error handling mechanisms
• Application debugging facilities
1.2.6. Physical Database
A Versant database system physically consists of:
• System files
• Executable utilities
• Header files
• Link libraries
• Class libraries for each language interface
• Application development tools
• At least one database consisting of storage and log volumes, which are files
1.2.7. Scalable Operation
Versant is scalable, which means that it uses distributed resources in such a way that performance does not decrease as the system grows. Versant is scalable because of the following features.
1.2.7.1. Client/server model
Versant uses a client/server model of computing. The terms client and server refer to roles and not machines or processes. The client and server can be on the same machine or on different machines.
6 Versant Server Guide
Versant Features
Figure 1.1. Client/Server Model
Your application is the database client and runs on a client machine. A client application can access multiple databases concurrently with other client applications.
The database that provides objects to an application is called the "server". One of the roles of the server is to process queries. A server can support concurrent access by numerous users.
The client and server communicate via a TCP/IP communication.
The queries are executed on the platform containing the data and the locks are set at the object level.
Because of this, the network traffic is reduced to a short query message from the client to the server and the return of only the desired objects from the server to the client.
Processing queries on servers balances the database processing responsibilities between the client and the server. It can result in major performance gains in a large distributed database environment, by taking full advantage of available platform and network resources including parallel and scalable processors.
By contrast, a file/server query causes all objects of a class to be locked and passed over a network even if only one object is desired.
1.2.7.2. Locks
The Versant locking model provides for a high concurrency of multiple users.
Versant Server Guide 7
Versant Features
1.2.7.3. Volumes
Objects are kept in one or more database volumes, which are storage areas on disk. Database volumes can be added incrementally either locally or at distributed locations.
1.2.7.4. Two-phase commits
To ensure data integrity when multiple, distributed databases are used, Versant performs updates with two-phase commits. Two-phase commits involve a procedure in which multiple databases communicate with each other to confirm that all changes in a unit of work are saved or rolled back together.
1.2.7.5. Lazy updates
Changes to class definitions do not paralyze operations. Instead, instances are updated the next time they are accessed, which is called a lazy update. You can create or drop leaf classes, rename leaf or non-leaf classes and create or drop attributes and methods in leaf or non-leaf classes.
1.2.7.6. Schema management
To facilitate the use of distributed databases, you can ask an object the name of its class and then inspect its class definition. Routines are also provided for creating and modifying classes at runtime and for synchronizing class definitions among multiple databases.
1.2.8. Distributed Databases
Versant supports distributed databases with the following features:
Object Migration
Objects can be migrated while applications still have transparent access to them. Object migration is possible, because objects have identifiers that stay with the object for its lifetime which means that the physical locations of objects are hidden from the application.
Recovery
To ensure data integrity when multiple, distributed databases are used, Versant performs updates with two-phase commits. Two-phase commits involve a procedure in which multiple databases communicate with each other to confirm that all changes in a unit of work are saved or rolled back together.
8 Versant Server Guide
Versant Features
Heterogeneity
Objects can be moved among heterogeneous platforms and managed in databases on numerous hardware platforms to take advantage of available resources in a network.
Schema Management
Class definitions can be managed at run time on both local and remote databases. Class definitions are stored with objects, which allow access to objects with applications that are running on different platforms and are using multiple interface languages.
Expansion
Databases can be created, deleted, and expanded on local and remote platforms. Database volumes can span devices and platforms.
Backup
Data on one machine can be backed up to remote sites, tapes, or files. Multiple distributed databases can be backed up to save their state at a given point in time. This gives transactional consistency across multiple databases.
Security
Access to databases and system utilities for security, is controlled through user authorization, which may be customized.
Session Database
Versant implements the concept of a session database, which can be local or remote, which handles basic record keeping and logging for a session.
Connection Database
Applications can connect to any number of local or remote databases and then manage objects in them as if they were local. You can work on objects in any number of databases at the same time in a distributed transaction.
Versant Server Guide 9
Versant Architecture
1.3. Versant Architecture
1.3.1. Client/Server Architecture
Figure 1.2. Client/Server Architecture
Versant has a balanced client/server architecture.
Both the client and server machines have limitations on resources and a balanced workload is necessary for optimal performance.
With Versant -
• Client and server can run on the same or different machines
• The client is part of an C++ or Java application and runs within the scope of this application
10 Versant Server Guide
Versant Architecture
• Client and server run in separate processes.
Versant balances workload between the client and server.
Versant Client Manages
• Database Connections
• Relevant Persistent Objects
Versant Server Manages
• Disk Files
• Data Storage/Retrieval
• Locking
• Logging
• Queries, Indexes
1.3.2. Versant Storage Architecture
Each database consists of a number of volumes, which are files on disk.
Database Volumes
The database volumes are:
System Volume
The system volume for each database is automatically created as a part of the initial process of creating a database. It is used for storing class descriptions and for storing object instances.
Data Volumes
Additional data volumes can be added to a database to increase capacity.
Logical Log Volume
The logical log volume contains transactions and redo information for logging recovery and rollback.
Versant Server Guide 11
Versant Architecture
Physical Log Volume
The physical log volume contains physical data information for logging and recovery.
The logical log volume and physical log volume are used to record transaction activities and provide information for roll back and recovery. Logical log and physical log volumes are created when a database is created. The basic storage architecture is as follows:
Figure 1.3. Basic Storage Architecture
The maximum number of databases that can be combined to form a distributed database system is 2^16.
12 Versant Server Guide
Versant Internal Structure
1.4. Versant Internal Structure
Internally Versant is composed of several software modules. To understand how Versant uses processes, you need to know that Versant is structured into several modules.
1.4.1. Versant Client
From a developer's viewpoint, programs using language interfaces drive all database and object management actions by communicating with a module called Versant Client. Versant Client then communicates with a module called Versant Server.
The portion of Versant that runs on the same machine as a client application is called Versant Client.
Versant Client performs object caching, object validation and management of queries, schema, links and versions. The Versant Client has the following features:
• It presents objects to an application
• It manipulates classes
• It caches objects in virtual memory
• It provides transaction management via a two-phase commit protocol
• It distributes requests for queries, updates, links and versions to server processes that manage databases.
• It manages database sessions
• It establishes connections to databases, which may be on the same machine or another machine.
• It converts objects from Versant database format to client machine format
Application programs communicate with the Versant Client through language specific interfaces. Versant
Client in turn communicates with one or more Versant Server modules, which manage databases. Versant
Client functionally consists of several subsidiary software modules.
The Versant schema manager, creates and manipulates class definitions. The Versant query processor supports queries for particular objects and iteration over classes of objects. Other modules cache objects and provide session and distributed transaction support.
Versant Server Guide 13
Versant Internal Structure
Versant Client is structurally divided into two parts. One part is associated with an application and an object cache, and the other part is associated with a Versant Server and a server page cache
The structural organization, like the functional organization, is transparent to developers and users, but it provides the internal basis for flexibility in system configurations.
To create an application capable of accessing a Versant database, you link Versant Client into your application. It then appears to your application that Versant Client moves objects from the database into and out of your application. This happens automatically, and your application need not explicitly control object movement, since objects will be supplied as your application accesses them.
1.4.2. Versant Server
The server performs object retrieval, object update, page caching, query support and management of storage classes, indexes, transactions, logging and locking.
The portion of Versant that runs on the machine where data is stored or retrieved from is called Versant
Server. Versant Server is the interface between Versant Client instances and operating systems.
Versant Server has the following features:
• It evaluates objects on disk or in the server page cache per queries sent by client applications
• It performs disk and storage management tasks such as object retrieval, object update, page caching, manages storage classes, indexes, transactions, logging, and locking
• It defines transactions and locks objects
• It maintains files that provide for logging and recovery
• It manages indexes
The term Versant Server refers to a software module and should not be confused with the term “server”, which refers to a machine running Versant Server software.
Versant Server is the base level of a Versant management system. It interfaces with the operating system to retrieve and store data in database volumes and communicates with Versant Server instances.
At the Versant Server level an object is a simple physical data structure consisting of a fixed number of fields. Each Versant Server accesses one or more databases.
14 Versant Server Guide
Versant Internal Structure
1.4.3. Network and Virtual Layers
Internal communications occur through network layers. The network layers translate messages as appropriate to the network protocol. Due to this form of internal communication, a Versant client may communicate transparently with all parts of a distributed database network.
To provide for heterogeneous hardware, Versant implements its client/server architecture with additional software modules called the Virtual System Layer and the Network Layer.
Between a Versant server and an operating system, is a virtual system layer specific to the hardware platform. The virtual system layer provides portability across hardware boundaries.
The virtual system layer isolates operating system code and provides portability across hardware boundaries. To allow portability, you must use Versant elemental and/or Class Library data types in your programs and recompile your programs as appropriate for each platform.
The network layer translates messages to the appropriate network protocol and moves objects as network packets.
Versant Server Guide 15
Language Interfaces
1.5. Language Interfaces
Versant databases are most commonly used with languages that implement the concept of either class or template and either delegation or inheritance. Versant provides language specific interfaces for C++ and Java.
Any action or data type that can be expressed in the interface language can become part of a database schema. This means that you use standard language statements to manipulate data. There is no special specific Versant database language.
Language-specific interfaces map the capabilities and styles of a programming language to the object database model.
Each language-specific interface consists of several libraries of pre-compiled routines and for typed languages and predefined data types. An interface can include its own development tool and can be used with other vendors' software development products.
16 Versant Server Guide
Naming Conventions
1.6. Naming Conventions
The following naming conventions apply when using Versant.
The Database Identifier
This completely identifies a given database. The identifier is in the form
databaseName@hostName:port
The complete database identifier is limited to a maximum length of 255 characters. Only characters from the US-ASCII character set are allowed. The parts of the identifier are described below.
databaseName
The name of the database. This is required.
The maximum length is 31 characters. Only characters from the US-ASCII character set are allowed.
hostName
This is the host name of the Versant Server. This is required. (An exception is if this is the local machine. In this case, the host name is not required.)
The maximum length, including the port designation (:port) if specified, is 223 characters. Only characters from the US-ASCII character set are allowed.
:port
This is the port to be used to establish a connection to the database. This is optional. If not specified, the configured port for the Versant Server is used.
Class Names
Class names should be unique to their database.
When objects are migrated, class names cannot conflict with existing class names in the target database.
Versant Server Guide 17
Naming Conventions
Attribute Names
Attribute names should be unique across the class hierarchy (the class and its derived classes).
18 Versant Server Guide
Chapter 2. Licensing
Sections
Versant Server Guide 19
License File
2.1. License File
The license file is a special file containing licenses for Versant components.
A license file must be present on each server in the network. This is a text file with XML-like tags.
The default license file is located at the installation directory and has the name license.xml. Thus the default license file for a Versant installation would be at $VERSANT_ROOT/license.xml.
It is possible to specify a different license file for the installation. In this case the environment variable
VERSANT_LICENSE_FILE should be set to point to the license file. This environment variable needs to be set for the backend server (for ss.d and VERSANTD.EXE) also.
The license file consists of specific tags and values. An example of the license file follows.
<versant-license>
<component>
<component-name>ODBMS</component-name>
<component-version>9.0</component-version>
<product-name>VERSANT</product-name>
<license-type>Runtime</license-type>
<ostype>Linux</ostype>
<arch>64-bit</arch>
<hostid>YourHostMachine</hostid>
<cpu-core>8</cpu-core>
<cpu>2</cpu>
<customer>Your Company</customer>
<contact-name>you</contact-name>
<contact-email>[email protected]</contact-email>
<component-usage>ODBMS license</component-usage>
<component-key>00112233445566778899AABB</component-key>
<expiry-date>03/25/2025</expiry-date>
<key-date>03/25/2015</key-date>
</component>
<component>
. . .
</component>
</versant-license>
The description of the various tags in the xml file is given below:
20 Versant Server Guide
License File
Keyword
versant-license component component-name component-version product-name license-type ostype arch hostid ipv4 ipv6 cpu-core cpu customer contact-name contact-email component-usage component-key expiry-date key-date
Description
Encloses all licensed versant products. May occur multiple times in each license file
Each licensed component is enclosed within a component tag
Licensed component name
Version number (most two significant digits) of the component, e.g.,
9.0
Name of product
Type of environment for the product, e.g., Runtime, Test,
Development
Operating system, e.g., Windows, Linux
Processor architecture, e.g., 64-bit
Machine identity. This can be specified as the host name (hostid) or the network IP address (ipv4 or ipv6 as appropriate). Only one of the three keywords is allowed.
Number of allowed cores
Number of allowed cpus
Customer name.
Name of the person requesting license.
Email address of the person requesting license. This is the address where the license will be mailed.
A string for use by the component.
The license key.
Expiration date of the license.
Date on which license was generated.
The license is node-locked and any change in the value strings would invalidate the license, causing the product to stop working.
The first license matching the following criteria, is used for performing the license check:
• Component name
• Component version
Versant Server Guide 21
License File
• Machine identification
Hence a new license needs to be inserted at the beginning of the license file. This will avoid the older license (if one exists) to be picked up for the license checks. The same license file can obtain licenses for different products and/or different versions of the same products and/or for different servers.
The license will be generated by Versant and normally sent to the customer-requesting the license through e-mail.
22 Versant Server Guide
CPU Core-based Licensing
2.2. CPU Core-based Licensing
Versant uses a core-based licensing mechanism. To be in accordance with your license agreement,
Versant Server needs to be licensed for the total number of CPUs and cores available on the machine on which the Versant server is installed. If the total number of CPUs and cores specified by your license is less than the total number for the server machine as reported by the vinstinf utility, then the server is not properly licensed. If this is the case, attempting to start a database (from an application or using any utility which must start the database) will result in an error message. A corresponding message is also logged in the Versant LOGFILE.
If you receive an error that your license does not support the CPU/core count of your machine, you can continue to use your current license for a period of up to thirty days. To begin this thirty day grace period you must explicitly start each database with the startdb utility with the special option
-withinGracePeriod
as shown.
startdb -withinGracePeriod DatabaseName
Once you have explicitly started a database and enabled the grace period with startdb you will be able to connect normally to the database from applications and utilities for thirty days. If, during the grace period, the database is stopped for any reason, you will, once again, need to explicitly start it as shown above. Once the grace period is over, the database will not start unless you provide a correct license.
You should, in that period, upgrade your Versant license.
Versant Server Guide 23
24 Versant Server Guide
Chapter 3. Database Creation
Sections
- Prerequisites For Database Creation
- Parameters for Creating Database Directories
- Step 1. Setting up the database directories and files
- Step 2. Editing the database profile (profile.be)
- Step 3. Creating the database
- Moving Just the Data Volumes
This chapter explains the database creation basics and outlines the procedures for creating a new database.
Versant Server Guide 25
Database Creation Basics
3.1. Database Creation Basics
Databases can be created on a local disk or on a server machine. The process of creating a database is the same for servers and local disks.
3.1.1. Prerequisites For Database Creation
3.1.1.1. Database Root Directory
Before you can create any databases, you need to designate a database root directory.
For each new database one sub-directory containing database specific information will branch from the database root directory.
The database root directory can be located anywhere. It does not have to branch from the Versant software root directory.
If you specify relative paths to the database volumes at the time each database associated with your installation is created (the default), you can easily move the location of the database root directory later.
The directory for each database must have the same name as the database.
Three volumes provide storage for each database: a system volume, a physical log volume, and a logical log volume. These volumes can be located anywhere. Additional storage volumes for the database can be created at any time.
To maximize performance, the system and data volumes, the physical log volume, and the logical log volume should be placed on separate disk drives. Placing the volumes on different drives minimizes disk seek time and thus maximizes throughput. If performance is not a critical issue, all volumes can be put on the same disk drive, which is simpler to do than separating them.
3.1.1.2. Database Owner
Each database requires a directory for its configuration and system files. The owner of this directory is the database administrator or DBA.
26 Versant Server Guide
Database Creation Basics
Only the DBA of a database can perform certain administrative tasks on a database, such as adding or removing users.
After a database has been created, you can change its database administrator by changing the ownership of its database directory.
3.1.1.3. Database System Identifier File (osc-dbid)
The name of the database system identifier file is osc-dbid.
The database system identifier file, osc-dbid, must exist and be accessible to your machine before you can create a database.
This file contains information about all databases that you and others might conceivably access during a particular database session.
The purpose of the database system file is to ensure that each database has a unique identifier number in a network system of databases. This is important, because the object model requires that each object have an identifier number unique among all other objects, regardless of database. When you create an object, the object is given an identifier number composed partly of the database identifier and partly of a number unique to the database.
You will not need to access the database system file when you create an object or connect to a database.
You will need to access the database system file when you create a database or ask for information about any or all databases in a network system of databases.
The osc-dbid file keeps track of all database identifiers in a network of distributed databases: the database name, the database id, the creator, and the creation date. It is automatically updated for each new database.
If you want to add a new database to a distributed database system, the machine creating the database must be part of the existing network of Versant databases when the new database is created.
If the osc-dbid file for a distributed database system is destroyed, you cannot create new databases or list existing ones until you recover the osc-dbid file from a backup copy or create a new osc-dbid file.
To create a new osc-dbid file, use the dbid utility.
To see the information in osc-dbid, run the Versant dblist utility.
$ dblist
VERSANT Utility DBLIST Version 9.1.0
Copyright (c) 2001-2015 Versant Software LLC and Copyright (c) 2013-2015 Actian Corporation.
Versant Server Guide 27
Database Creation Basics
All rig hts reserved.
ID
DB name creator
= 1
= test@lyra-win7
= nausicaa date created = Wed Dec 23 12:06:48 2015 db type = GROUP DATABASE db version = 9.0.0
ID
DB name
= 9
= pdb1@lyra-win7 creator = nausicaa date created = Fri Jan 22 14:51:38 2016 db type = GROUP DATABASE db version = 9.0.0
The location of the osc-dbid file is specified during the first installation of Versant in a particular database network.
For more information about the osc-dbid file, refer to
Section 4.1.1, “Database System Identifier File
3.1.1.4. Database Volumes
A database is more than just the stored user data; there is also system and logging information that is maintained in different database volumes. The follow lists the principal database volumes.
System Volume
The system volume contains database system catalogs and provides data storage space.
Storage Volumes
Optional storage volumes are added using the
utility to supply more storage space if the system volume is not large enough. The maximum number of storage volumes is limited to 2000.
Physical Log Volume
The physical log volume contains physical data information for logging and recovery.
28 Versant Server Guide
Database Creation Basics
Logical Log Volume
The logical log volume contains transaction undo and redo information for logging, recovery, and rollback.
Linux Volume Files
A database on Linux systems uses files for the database volumes, which need to be locally stored. We do not support accessing database files through NFS, as the NFS protocol does not guarantee that file writes are flushed to disk on invocation of a flush system call. This means that the use of NFS could result in database corruption!
3.1.2. Parameters for Creating Database Directories
While creating database directories, there are some mandatory parameters and some optional parameters which need to be set.
3.1.2.1. Database Directory Creation Parameters
When creating database directories with makedb you must specify the database name which is also the directory name. The database name must be no longer than 31 characters. When referring to a remote database, you must append a host name using the database@host syntax. Only characters from the
US-ASCII character set are allowed in database and host names. Additionally, the combined database name and host name (including the @ character) is limited to a length of 255 characters.
3.1.2.2. Optional Parameters
When creating a database with createdb, you can set the following optional parameters in the database server process profile file profile.be.
If you do not explicitly set any values, the defaults are used.
These parameters cannot be changed after the database has been created.
Database Size
The defaults are:
System Volume 1024 M
Versant Server Guide 29
Database Creation Basics
Physical Log Volume
Logical Log Volume
24 M
24 M
If the log volumes are files, they will expand as necessary during database use. The system volume does not grow. To increase storage for data after the database has been created, you can add more volumes by using the addvol utility.
Database Volume File Names
In the database server process profile file profile.be, you can specify paths and file names for the database volumes. The paths and names determine where the volumes are located.
Each database must have a directory branching from the database root directory. In this directory environment files for the database are located. The name of a database directory must be the same as the database name.
The directory for a database can also hold the database volumes.
If the path to the database volumes is specified in relative terms when the database is created, then the database volumes can be moved later. If the path is specified in absolute terms, the volumes can never be moved. The default is to specify a relative path to the database volumes.
You can change the following parameters after a database has been created, but because they are important it is recommended that you decide on their values earlier.
Each of these parameters may be set in the database server process profile file profile.be:
Locking
Whether locking is to be ON or OFF. The default for group databases is locking ON, and the default for personal databases (deprecated) is locking OFF.
Logging
Whether logging is to be ON or OFF. The default for all databases is logging ON.
30 Versant Server Guide
Database Creation Procedure
3.2. Database Creation Procedure
Following are the steps required to create a database:
1. Set up database directories and default profiles
2. Optionally edit database profile
3. Create the database
Versant does not allow spaces in names, including login and database names.
These are explained in detail in the following sections:
3.2.1. Step 1. Setting up the database directories and files
Before creating a database, you have to create a database directory, assign access privileges, and create database profiles.
You can use the Versant makedb utility to create the necessary default setup. The makedb utility will give the user an option to input a password to be associated with DBA.
The directory contains essential database files, such as the database profile. The database directory must branch from the database root directory as specified during installation of the system software, and it must have the same name as the database that you want to create.
If you are recreating a database previously removed with the removedb utility, you can use the old directories and profiles without having to rerun makeprofile or makedb unless you removed the database with removedb -rmdir.
You can set up a database either automatically by using the makedb utility or manually by performing the equivalent steps yourself.
3.2.1.1. Automatic Setup
To perform an automatic setup of database directories and files, do the following:
Versant Server Guide 31
Database Creation Procedure
• Login
If you have write privileges for the home database root directory (created during the installation of the Versant software) login with your user name. If you do not have write access to the database root directory login as root.
• Run makedb
Create the database directories and files with the makedb utility. The general syntax is makedb [options]
dbname
If it does not already exist, the makedb utility will create a database directory with the name given for dbname based on the options in the options parameter, and, if they do not already exist, create database support files. You must run makedb or create a database directory and profile files manually before creating a database with createdb.
For a remote database, append the node name to the database name using the syntax dbname@node.
For options you can substitute:
-g
Make the database a group database. This is the default option.
Group databases are accessible to many users at the same time.
-cpprofile db
Copy the profile file profile.be from the specified db directory to the directory for the new database.
A user can copy a database profile only if they are the owner of the database. Basically, that means that only the DBA is allowed to copy profiles.
This option works only if both databases are on the same machine.
If only a database name is used rather than a full path name,the database root directory is searched for the db directory.
-nofeprofile
Do not create an application process profile.
32 Versant Server Guide
Database Creation Procedure
-logging
Turn transaction logging on.
-locking
Turn transaction locking on.
-noprint
Do not display any messages while the command runs.
The directory created will be:
/dbroot/dbname
A directory for the database that branches from the database root directory. The name of the directory will be the same as the database name specified as dbname.
Database support files that will be created, if they do not already exist, are:
/.osc/dbname
An application process profile file, located in the .osc directory branching from your home directory. This file contains operating parameters used when this database is a session database.
profile.be
A database server process profile file, located in the database directory. This file contains database creation and operating parameters.
.lock
A lock file, which indicates whether or not the database has already been started.
.dbtype
A database type file, which indicates whether this is a personal (deprecated) or group database.
Versant Server Guide 33
Database Creation Procedure
3.2.1.2. Manual Setup
If database directories have already been set up, you can run the makeprofile utility to create the application process and server process profile files. The general syntax is: makeprofile [options] dbname
For a remote database, append the node name to the database name using the syntax database@node.
Options are:
-cpprofile db
Copy profiles from the specified db directory.
A user can copy a database profile only if it is the owner of the database i.e., only the DBA is allowed to copy profiles.
If only a database name is used rather than a full path name, the db directory under the database root directory will be used.
-nofeprofile
Do not create an application process profile.
-logging
Turn logging on.
-locking
Turn locking on.
-noprint
Suppress display messages while command runs.
For example, to make profiles for myDB: makeprofile myDB
34 Versant Server Guide
Database Creation Procedure
If you are recreating a database previously removed with the removedb utility, you can reuse the directories and profiles without having to run makeprofile or makedb.
3.2.2. Step 2. Editing the database profile (profile.be)
You have to edit the database server process profile profile.be if you want to change the system volume size from its default value or alter the default extent size.
The name of the database profile is profile.be, and it will be located in the database directory after you run the makedb utility.
Parameters for the sizes and names of database volumes cannot be changed after the database has been created.
• The default name of the System Volume is system, and its default size is 1024 megabytes. Edit the sysvol entry in profile.be to change the size of the System Volume.
• The default name of the Physical Log Volume is physical.log. The default initial size is 24 megabytes.
Edit the plogvol entry to change the size of the Physical Log Volume.
• The default name of the Logical Log Volume is logical.log. The default initial size is 24 megabytes.
Edit the llogvol entry to change the size of the Logical Log Volume.
• If files are used for the log volumes, the log volumes expand as needed; the system volume does not change. If you specify a size for the log volumes and the volumes are files, then the parameter will be used to pre-allocate space, but the files will still expand as needed.
• The default number of pages per extent on the system volume is 2. To change the number of pages per extent, edit the extent_size entry in the profile.be file.
There are other entries in the server process profile. They are performance related and can be changed before or after creating a database.
For more information, see
For a standard installation, the default system volume, physical log volume, and logical log volume entries are: sysvol plogvol llogvol
1024M
24M
24M system physical.log
logical.log
Versant Server Guide 35
Database Creation Procedure
The general syntax for each entry is: sysvol plogvol llogvol size [/path/]system size [/path/]physical.log
size [/path/]logical.log
where:
size
The volume size in bytes. Kilobytes can be specified with k or K, and megabytes can be specified with m or M. You can specify any size you want for the volume size.
/path
The path to the volume. It can be specified in relative or absolute terms. If the first character is /, then the path is absolute. The path for each volume can be different.
>system
Name of the system volume.
physical.log
Name of the physical log volume.
logical.log
Name of the logical log volume.
If only volume names are specified in the server process file, Versant will use the specifications in the
/etc/.osc090300
file or in environment variables to expand the volume names into full path names.
For example, assume the following settings
• your database name is dbname
• your /etc/.osc090300 file specifies your software root as /opt/versant/9
• your database root is set to the installation default location, /opt/versant/db
• you specify your volumes as
36 Versant Server Guide
Database Creation Procedure sysvol llogvol plogvol
1024M system
24M logical.log
24M physical.log
Then the system will expand your entries to: sysvol llogvol plogvol
1024M /opt/versant/db/dbname/system
24M /opt/versant/db/dbname/logical.log
24M /opt/versant/db/dbname/physical.log
3.2.3. Step 3. Creating the database
After setting up the database directories, setting database access privileges, and optionally editing the server process profile, you can create a database by running the Versant createdb utility.
The createdb utility will create the database including storage and log volumes and update the network database identifier file osc-dbid to register the new database as part of the database system.
The general syntax for createdb is: createdb [options] dbname
The createdb utility will create, format, and initialize a new database with the name dbname and either make the new database a part of an existing distributed database system or start a new database system.
The database name dbname must be unique for the distributed database system it will belong to.
You must be the owner of the database (the database administrator) or the super user to run this utility.
For a remote database, append the node name to the database name using the syntax database@node.
Options that may be specified in the options parameter are:
-i
Reserve space for the system volume.
Reserving space can prevent you from running out of space at runtime. For example, suppose you set the size of the system volume as 100 megabytes in your profile, but you really have only 60 megabytes physically available. In this case, if you use -i, you will immediately get an out-of-space
Versant Server Guide 37
Database Creation Procedure error, but if you do not use -i, you will get an error at runtime as the system volume dynamically expands.
If you have defined multiple storage volumes and the physical space in one volume is less than the logical space, you will get an out-space-error even though there is space available in the next volume.
Pre-allocating space may improve performance, because space will not have to be dynamically allocated. However, pre-allocating space will slow down the process of creating the database, and because the space is used immediately, it will prevent it from being used for other purposes.
Space for log volumes is always pre-allocated according to the parameters set for the plogvol and llogvol size specifications.
-il
Reserve and pre-format file system space for the logical log volume and the physical log volume.
-noprint
Suppress display messages while running.
The createdb utility will update the osc-dbid file to register the new database with the existing distributed database system. The file osc-dbid containing the path and name of all databases in the system must be visible from your machine when you run createdb.
Examples of using createdb: createdb mydb createdb -i mydb
Components of the newly created database will be:
System volume
A system volume is needed for catalog information and data storage, with a name, location, size, and device according to the specification in the server process profile file profile.be.
The default is a Linux file of 1024 megabytes named system and the location, for a database named dbname
, is:
38 Versant Server Guide
Database Creation Procedure
/opt/versant/db/dbname/system
Physical log volume
A physical log volume is needed for physical data information related to logging and recovery, with a name, location, size, and device as specified in the server process profile file profile.be.
The default is a Linux file of 24 megabytes named physical.log and the location, for a database named dbname, is:
/opt/versant/db/dbname/physical.log
Logical log volume
A logical log volume is needed for transaction undo-redo information related to logging and recovery, with a name, location, size, and device as defined in the server process profile file profile.be.
The default is a Linux file of 24 megabytes named logical.log and the location, for a database named dbname, is:
/opt/versant/db/dbname/logical.log
.sharemem
A shared memory file, which contains a shared memory identifier.
Versant Server Guide 39
Moving a Database
3.3. Moving a Database
After you have created a database, you can move the volumes of a database to a different directory, with some restrictions.
For example, on a particular machine, you might decide that you want to locate the system software on one disk and the databases on another disk. Or you might want to use the system software on a server while maintaining databases on a local disk.
You should not move a database after it has been created unless you are an experienced user.
3.3.1. Moving Just the Data Volumes
You can always move the data volumes by editing the system profile file (profile.be), even if you specified an absolute path when you created them. However, this is not true of the system, physical log, and logical log volumes.
To move the data volumes:
• Move the data volumes to a new location.
• In the server profile file, profile.be, create or change the datavol entry for each data volume you have moved.
For more information refer to
.
3.3.2. Moving All Volumes
You can create a database and later move all database volumes to a different directory if, before database creation, the volumes were specified in relative terms rather than absolute terms. This can occur in any of three ways:
• You originally placed the volumes under the database directory.
40 Versant Server Guide
Moving a Database
• Even if you specified the location of the database volumes in absolute terms, if they were placed under the database directory, they are internally stored in relative terms... which means that they can be moved at a later time.
• You created the database using the defaults.
• By default, volumes are stored under the database directory.
• Before database creation, you edited the server process profile file in such a way that the volume paths were specified in relative terms.
To move all volumes to a new location, do the following.
1. Move the database volumes to a new location, preserving their relative relationships.
2. Reset the location parameter VERSANT_DB to indicate the new database root.
For more information on location parameters, refer to
.
Versant Server Guide 41
42 Versant Server Guide
Chapter 4. Database Directories and Files
Sections
- Database System Identifier File (osc-dbid)
- Physical Log Volume—physical.log
- Logical Log Volume—logical.log
- Application Process Profile File
- Server Process Profile—profile.be
- Shared Memory File—.sharemem
During installation, you are asked for a location for the database root directory. This directory can be anywhere but is normally created on the same machine as the server. The database root directory serves as the container for the actual databases you will create and use. Databases themselves are sub-directories of the database root directory.
This chapter describes the makeup of these directories and the files they contain.
Versant Server Guide 43
Database Root Directory
4.1. Database Root Directory
The database root directory is the parent directory for individual database directories created by the database utility makedb.
This directory is separate from the Versant software root directory. You can use an existing database root directory, and the databases it contains, with a newer version of Versant (with conversion, if required).
The location of the local database root directory must be specified with the VERSANT_DB location parameter before you can access, create, or remove a database located in the root directory.
The database root directory can be either local or remote. If a remote directory is used, you must have access rights to the directory and the files it contains. The location of a remote database root directory must be specified with the VERSANT_DB@node location parameter before you can access, create, or remove a database on the remote machine named node.
Linux and NFS
We do not support accessing the database directories and files through NFS. The NFS protocol does not guarantee that file writes are flushed to disk on invocation of a flush system call. Using NFS could result in database corruption!
The default database root directory location is on the local server machine under the software root directory. This is /opt/versant/db for Linux and C:\Versant\db for Windows installations.
In addition to the database directories, described in detail
, the database root directory contains a number of files used by Versant. These files are described in the following sections.
4.1.1. Database System Identifier File (osc-dbid)
The database system identifier file is a special file that contains information about all databases in a network of databases.
A database system identifier file must exist and be accessible to your machine before you can create a database.
Normally, the database system identifier file will be on a machine acting as a server and will have already been created by the time you perform an installation.
44 Versant Server Guide
Database Root Directory
A Versant database system is a group of databases among which you can safely connect and share objects.
Versant also implements the concept of distributed database network systems in which:
• Any database in a system can safely interact with any other database in that system,
• Any database in a system can operate while completely disconnected from all network communications,
• Any number of databases can belong to a particular network system,
• Databases in a particular system can be located anywhere in a network,
• Any number of systems can be created.
During installation, you will be asked for the machine and path of the osc-dbid file for the database system that you want the new installation to join.
Typically, you will want to place the osc-dbid file not on the local machine but rather in a visible directory on a machine that you designate as a network server, because it must be able to be found by all machines in the network. Only if you have a standalone installation that will never use objects in databases on other machines, you can place the osc-dbid file on your local machine.
If you want your installation to join a system of distributed database, we strongly recommend that you install first on the machine that will act as your database system host, create a database system file at that location, and then specify the machine and path of that file when you install on each client machine.
Installing first on the database system host will ensure that when you install on a client machine you know the location of your database system file and do not have to make corrections later.
After a network of databases has been defined, you can move the location of the osc-dbid file. However, this is not recommended, because this would require your going to all machines in the network and revising the Versant environment variables and configuration files that point to the old location.
In any case, before you can create a database:
1. an osc-dbid database system file must exist at a location accessible to your machine, and
2. the location of the osc-dbid file must have been specified to your machine.
Since the osc-dbid database system identifier file is only used when databases are created, removed, and listed, you can connect to a database even when the node containing the osc-dbid file is down.
However, since the osc-dbid file is not read each time you make a database connection, you could conceivably create simultaneous connections to databases belonging to differing database network systems.
Versant Server Guide 45
Database Root Directory
You should avoid doing this! It's possible that databases in other database network systems could have the same identifier number, and as a result, there could be objects in the differing systems with the same logical object identifier.
If the osc-dbid database system file for a distributed database network system is destroyed, you have to recover the osc-dbid file from a backup before you can create new databases, remove existing databases, or list the databases in that system.
If you have no osc-dbid file backup, recovery procedures are complex. Although you can use the dbid utility to create a new osc-dbid file, creating a new osc-dbid file means that identifiers for new databases will probably duplicate the identifiers for existing databases. This means that you have to create a new network of databases, and then create new objects in the new databases that are copies of the old objects.
You need to be careful not to migrate the old objects.
If your osc-dbid file is destroyed, please call Versant Customer Support.
The default location for the osc-dbid file on a Linux installation is the /home directory on the local machine. The default location for the osc-dbid file on a Windows installation is the database root directory on the local machine.
The following explains what happens after the installation program asks for a path to an osc-dbid file:
No Path
If you do not specify an osc-dbid machine and directory, the installation program will create a new osc-dbid on your local machine in your home directory.
Same machine
If you specify that the osc-dbid machine is the same as the installation machine, the installation program will first look for an existing osc-dbid file in your home directory.
If an osc-dbid file already exists in the specified directory, you will join the existing system of databases.
46 Versant Server Guide
Database Root Directory
If an osc-dbid file does not exist in the specified directory, the installation program will create an osc-dbid file in the specified directory and a new database system will be started.
An osc-dbid file may not exist in the specified directory because this is the first installation of
Versant on this machine or because you want this installation to create a new database system.
Remote Machine
If you specify that the osc-dbid machine is different than the installation machine, the installation program will not look to confirm that an osc-dbid file exists in the specified directory and will not create a new osc-dbid file.
In all cases, the installation program will record the path of the new or existing osc-dbid file in the system information file sysinfo file if your installation will use local files and in the machine configuration file, .osc090300, if your installation will use remote files.
Because Versant does not check for the existence of an osc-dbid file if you specify a remote machine, during installation you do not have to be connected to a network and the first installation of Versant does not have to be on the machine that will eventually contain the osc-dbid file.
However, it is recommended that the first installation of Versant be on the machine that will contain the osc-dbid file in order to reduce the chance of an unintended outcome.
For example, if you specify a remote path to osc-dbid and then later decide on a different path for osc-dbid
, then you will not be able to create a database until you manually specify the correct path on each and every installation already made.
Or, if you do not specify a path to osc-dbid at all, there is the danger that before you get a chance to tell the local Versant installation about the remote osc-dbid file, you will create a database using the local osc-dbid file, which breaks the object model because unique object identifiers across the system of databases cannot be guaranteed.
Before installation, you can find the machine and path of the database system file by running the oscp system utility of an installation whose database system you want to join.
Or, if Versant files are local, you can inspect the local /db/sysinfo system configuration file. If you are using Versant files on a remote machine, you can inspect your /etc/.osc090300 machine configuration file. In a configuration file, the machine containing the osc-dbid file will be associated with the entry for VERSANT_DBID_NODE, and the directory will be associated with the entry for
VERSANT_DBID
.
For example, if osc-dbid is on a machine named server_machine and in the directory
/visible_directory
, you would see the following entries in a configuration file:
Versant Server Guide 47
Database Root Directory
VERSANT_DBID_NODE server_machine
VERSANT_DBID /visible_directory
4.1.2. Logging Files
The following files are used for server connection logging. The files are created at the first occurrence of a log entry.
Server connection log—vlog
The vlog file is the log file for the server connection program, ss.d (ss.exe on Windows). The file has a maximum size of 32MB and a copy of the previous file is kept to insure that the recent server connection history remains available. That is, when the active log file exceeds 32MB, it is moved to vlog_previous
(overwriting an existing “previous” file) and a new active vlog file is created.
Log file concurrency lock—.vlock
This file is used to synchronize concurrent access to the vlog file.
(The file is named vlock on Windows systems.)
48 Versant Server Guide
Database Directory
4.2. Database Directory
When you create a database by using the makedb utility, a database directory with the same name as the database is created. Database directories are contained in the database root directory. For example, if you create a database named mydb using the default-named database root directory, the database directory is /opt/versant/db/mydb on Linux and C:\Versant\db\mydb on Windows installations.
The database directory contains various files used by Versant, such as configuration and log files, and one or more database volume files that contain your data for that database.
These files are described in the following sections.
4.2.1. System Volumes—system
The actual data in the database—class descriptions and object instances— are stored in one or more system volumes. When you run createdb, a system volume file named system with the volume name sysvol is created. Additional data volumes can be added to a database to increase capacity.
You can get information about the system volumes with the utility command dbtool [-sys] -volume.
Additional volumes are created with the addvol utility. Refer to
Information About Storage Volumes” pg. 230 and
Section 10.2, “addvol” pg. 197, respectively.
4.2.2. Physical Log Volume—physical.log
The physical log volume, physical.log, contains physical data information for logging and recovery.
The logical log volume, logical.log, and physical log, physical.log, are files associated with a database that record transaction activities and provide information for roll back and recovery.
There is one physical.log and one logical.log file for each database.
The logical and physical log volumes for a database are created with the createdb utility. The physical.log
and logical.log files expand as needed.
4.2.3. Logical Log Volume—logical.log
The logical log volume contains transactions and redo information for logging recovery and rollback.
Versant Server Guide 49
Database Directory
The logical log volume, logical.log, and physical log volume, physical.log, are files associated with a database that record transaction activities and provide information for roll back and recovery.
There is one physical.log and one logical.log for each database.
The logical and physical log volumes for a database are created with the createdb utility. The physical.log
and logical.log files expand as needed.
4.2.4. Application Process Profile File
This section applies only to the Versant C++ and JVI interface.
A client application process contains the application, part of the Versant software module, a network layer, and an object cache. Additionally, an application profile file is created for each user of the application and for each database the application accesses. (Application profile files are generally only intended for use in environments where a single user is associated with the application such as an application server.)
Each application profile file is named for the database with which it is associated. By default, these application profile files reside in a subdirectory of the user home directory. For Linux this is $HOME/.osc/ and for Windows %HOMEDRIVE%%HOMEPATH%\osc\.
When an application starts a session, the operating environment will be set according to the settings in the application process profile file. You can customize the operating environment for an application process by modifying the application process profile. If there is no application process profile file, the system uses defaults.
For any Versant installation, there is one application process profile file per database. When you use either the makedb or makeprofile utility, Versant will check the .osc (Linux) or osc (Windows) directory to determine if a file with the same name as the database exists. If an application process profile file exists, Versant will not create a new one. If it does not exist, Versant will create one.
You can use the makeprofile utility to create several application process profiles, change their names, edit them, and then specify which one you want to use at run time by changing its name to the database name.
In the application process profile there are parameters that you can specify either before or after a database has been created. These parameters are read each time a session starts. In a session where multiple databases are connected, if you change the parameters in application process profile, the
50 Versant Server Guide
Database Directory changes will be reflected to other users only when they access the modified application process profile file.
Refer to
Section 6.1, “Application Process Parameters” pg. 74 for more information regarding the
application profile file including the descriptions of the parameters used in the file.
4.2.5. Log File—LOGFILE
This file logs database and system messages and errors. By default, this file is located in the database directory. You can can configure the location of this file using server profile parameter versant_be_logfile
. By default, error logging is enabled.
In addition to error number and error message, entries in the error log file also includes context information, such as operating system error number, file name and so on. The exact information varies from error to error.
4.2.6. DBA Utility Logging
The database log file, LOGFILE, is also used as the default file to log all DBA utility activities. You can specify an alternate file for logging DBA utility activity with the versant_be_dbaloggingfile database parameter. You can also specify a utility logging file with the dbtool utility using the call dbtool –dbalog
–setfile Filename DatabaseName
. (Refer to
Section 10.10.11, “-dbalog—Get Information About Logging
The general format of the messages that will be logged into the file used for logging DBA utility activity is as follows.
<PID:#####>; <HOST: hostname><START | END | INVOKED>; <Complete command line>; <Utility dependent extra information like “invoked directory”, effective user ID>
Each entry in LOGFILE will have one or more of the following fields:
PID
:
Process ID of the utility and not that of the process, which is logging this message into the file.
HOST
: Hostname of the machine where the utility is run.
START
:
Versant Server Guide 51
Database Directory
Indicates the start of the utility. On successful completion there will be a corresponding END entry.
END
:
Indicates the completion of the utility. This entry might include an error (see ERRCODE field). If a utility has run successfully, the START and END entries have to match up as pairs. This also means that if there is a START entry but no END entry, the utility has either not finished doing its job, is hung or has been killed with a signal that cannot be caught.
INVOKED
:
Indicates the invocation of the utility. This field and the combination of START and END fields are mutually exclusive.
ERRCODE
:
This may appear as part of the END entry. It indicates with what error the utility failed. If the utility succeeded, this value would be zero. If the error code is difficult/impossible to obtain, this field would not be present.
CWD
:
Directory from where the utility was invoked.
RUID
:
Real user ID. On platforms where this field is irrelevant, this field will not be present or it will have the string N/A.
EUID
:
Effective user ID. On platforms where this field is irrelevant, this field will not be present or it will have the string N/A.
Here are a few examples of entries in the per-database configurable file.
PID: 12345; HOST: mymachine; Wed Feb 7 12:56:23 2001
START; vbackup –dev /vol01/backup/dbname.020701.level0
–backup dbname; CWD: /vol03/versant;
RUID: srao; EUID: srao;
PID: 12346; HOST: ourmachine; Wed Feb 7 12:59:23 2001
START; vbackup –dev rf.0 –log dbname@yourmachine;
52 Versant Server Guide
Database Directory
CWD: /vol03/versant; RUID: srao; EUID: srao;
PID: 12345; HOST: hismachine; Wed Feb 7 19:37:23 2001
END; vbackup –dev /vol01/backup/dbname.081547.
level0 –backup dbname; CWD: /vol03/versant;
RUID: srao; EUID: srao;
PID: 12346; HOST: hermachine; Wed Feb 7 12:59:23 2001
END; vbackup –dev rf.0 –log dbname@yourmachine;
CWD: /vol03/versant; RUID: srao; EUID: srao;
PID: 12347; HOST: yourmachine; Wed Feb 7 12:56:23 2001
INVOKED; dbuser -add -n smartperson -defaultpasswddbname@ remotehost; RUID: srao; EUID: srao;
PID: 13567; HOST: theirmachine; Wed Feb 7 12:56:23 2001
INVOKED; dbuser -chpasswd -n username -opasswd
<notdisplayed> -passwd <notdisplayed> dbname@localhost; RUID: srao; EUID: srao;
An example of the vserver startup entries.
PID: 31699; HOST: somemachine; REAL HOST: somemachine; Thu Nov 17 13:47:18 2016
START; vserver -noprint -reportToPipe -fetype 15 -primdb 1 -nettype 5 -skip pdb -username radomait; CWD: /build/rad/rad_92/rhel6.5_gpp44_64bit-dbg/db/pdb; RUID: radomait; EUID: radomait; VERSION : 9.2.0.8
Process:31699 Thu Nov 17 13:47:19 2016
The database has been successfully started.
The entries for vserver shutdown.
Process:31699 Thu Nov 17 13:47:23 2016
The database is shutting down ...
PID: 31699; HOST: somemachine; REAL HOST: somemachine; Thu Nov 17 13:47:23 2016
END; vserver -noprint -reportToPipe -fetype 15 -primdb 1 -nettype 5 -skip pdb -username radomait; CWD: /build/rad/rad_92/rhel6.5_gpp44_64bit-dbg/db/pdb; RUID: radomait; EUID: radomait; ERRCODE: 0;
Versant Server Guide 53
Database Directory
4.2.7. Server Process Profile—profile.be
The database server process profile file. The server process profile file is named profile.be and is located in the directory for the database. The server process profile is created with the makedb utility.
When a database starts up, the database server process reads the server process profile to determine the location of the database volumes and to set the database operating environment. If a server process profile does not exist for a database, you cannot start that database.
The server process profile contains several kinds of parameters. Some are used only when a database is created, others are used each time a database is started.
For more information, refer to
Chapter 6, Database Profiles pg. 73.
4.2.8. Lock File—.lock
The lock file, .lock (Linux, lock on Windows), contains database state information and is created when you create a database with the makedb utility. Versant will use the .lock file to determine whether a database has already been started. If the .lock file is missing, you will not be able to start or recreate the database.
If the .lock (Linux) or lock (Windows) file is inadvertantly deleted, you can use the dbinfo utility to create a new one. Change to the appropriate database directory and run the dbinfo utility with the -c option (create lock file), i.e., dbinfo -c DatabaseName.
4.2.9. Password File—.pw
The password file, .pw (Linux, pw on Windows) is created only if DBA authentication is done using a password-based mechanism. The specified password is stored in this file and is accessed everytime a utility that requires DBA authentication is invoked, such as createdb, dbinfo, vmovedb etc.
If the DBA password is not known (lost, forgotten), a privelaged operating system user can delete the password file and recreate a new password using the dbuser utility.
For more information refer to
Section 10.11, “dbuser” pg. 251.
54 Versant Server Guide
Database Directory
Without this file, DBA authentication will not be performed.
4.2.10. Backup File—.vbackup
The file .vbackup (Linux, vbackup on Windows) contains data necessary for reporting the progress of the vbackup utility. Any modifications to the .vbackup file will result in incorrect reporting to the vbackup progress bar.
4.2.11. Shared Memory File—.sharemem
When you create a database with the createdb utility, Versant will create a file named .sharemem (Linux, sharemem on Windows) in in the database directory. The contents of the shared memory file are used as a key to get a unique identifier for the shared memory used by the database server process.
The createdb utility creates this file. The removedb utility removes this file. You should never remove the file yourself, because if this file is missing, you will not be able to start or recreate the database.
If the file is removed, in some cases shared memory used by the database will exist, but the stopdb,
startdb
, and removedb utilities cannot discover it. Then, when you recreate the database, a shared memory file may have the same memory identifier which causes problems when you try to start the new database.
If the file is inadvertently removed, you can recreate it as follows.
Linux
Remove outstanding shared memory associated with this database using ipcrm. Change to the database directoryand create an empty .sharemem file in the database directory with touch.
Windows
Create an empty sharemem file in the database root directory. After creating the empty sharemem file, you can then start the database with the startdb utility or, if it has been removed with removedb, you can recreate it with the createdb utility.
Versant Server Guide 55
Database Directory
4.2.12. Database Type File
The database type file indicates the database type, i.e., personal or group. The type file is created when you create a database with the makedb utility. If the file is missing, the database cannot be created or started.
For Linux installations the file is named .dbtype. The permission bits on the .dbtype file establish the database type: 0600 indicates a personal database and 0660 indicates a group database. If needed, the file can be manually recreated.
For Windows installations, the type file is a text file named PERSONAL.FLG or GROUP.FLG that contains the database owner name. If needed, recreate the file as a hidden file with the appropriate name in the database directory that contains the database owner name.
The “personal” database type designation is deprecated. All databases should be group databases. The database type file may not be present in later releases of Versant.
4.2.13. Trace Log File—.systrace
The trace log file, .systrace (Linux, systrace on Windows), contains the trace log when tracing is turned on. If tracing is enabled, this file will contain information and error messages. For more information, refer to
Section 10.10.9, “-trace—Trace Components of a Database” pg. 237.
4.2.14. Socket Files
The socket files are temporary files that coordinate socket connections between the server process, vserver
, and the ss.d process or between the server process and various Versant utilities. They exist only for Linux installations. The file associated with the vserver process domain socket has the name
VServerPID_vserver_pipe where VServerPID is the vserver process identifier. Additional domain socket files have the name
VServerPID_vserver_pipe_ssd_SSDPID for the ss.d process or
56 Versant Server Guide
Database Directory
VServerPID_vserver_pipe_1p_1pPID for a utility process. The filename parts SSDPID and 1pPID are the ss.d and utility process identifiers, respectively.
• These files may not be immediately cleaned up and can be visible for a short time even after the corresponding processes have terminated
• The naming scheme used for these files may change in later updates
Versant Server Guide 57
Configuration Files
4.3. Configuration Files
During installation, Versant will create two configuration files, a machine configuration file and a system information file. The contents of the machine configuration and system information files will vary depending upon the type of installation you perform.
For more information, on setting up environment parameters, refer to the Versant Release Notes.
4.3.1. Machine Configuration File
The machine configuration file is /etc/.osc090300 (Linux) or %HOMEDRIVE%%HOMEPATH%\vr090300.ini
(Windows). The contents of the file at least have the information of the following parameters.
VERSANT_ROOT
VERSANT_DBID_NODE
VERSANT_DBID
VERSANT_DB
4.3.2. System Information File
The system information file is named sysinfo. The installation program will create the system information file in your VersantInstallation/lib directory. For example, for the default software root, the location of the file will be /opt/versant/db/lib/sysinfo on Linux and C:\Versant\db\lib\sysinfo on Windows systems.
4.3.3. Statistics File
When it starts, the vstats utility will read a configuration file in which derived statistics expressions can be pre-defined and named. The file is named .vstatsrc on Linux and vstats.ini on Windows systems. The file is located in the /lib directory of your Versant installation. Refer to
58 Versant Server Guide
Chapter 5. Database Users and Authentication
Sections
• Utility Access Privileges for Database Users
- Database Administrator Authentication
- Database User Authentication
This chapter provides detailed information about configuring database users for Versant (Versant), their privileges, and their management. It also explains the built-in database user authentication mechanism and and how you can customize user authentication.
Versant Server Guide 59
Versant Users
5.1. Versant Users
Each Versant database user is identified by a unique user name that is stored in the database. A user name can be up to 31 characters in length. There are various types of users. The type defines the role associated with the user. Different roles are allowed different privileges, that is, whether they can, for example, create, administer, or access a database.
5.1.1. Types of Database Users
Versant has three types of database user. Their roles differ depending on the type. The following are the different types of users characterized by the database.
• Database System Administrator (DBSA)
• Database Administrator (DBA)
• Database User (DBUser)
5.1.1.1. Database System Administrator—DBSA
For Linux installations, the database system administrator or DBSA is a user who, as a superuser, installs
Versant on each machine in a network. The parameters which define the DBSA are as follows.
• There is only one DBSA for a system of Versant installations.
• The DBSA owns the osc-dbid file for a database system.
• The DBSA owns all Versant software root directories, including the bin, h, and lib subdirectories and all files under those directories, for all installations on a network. This ownership extends to all versions of Versant installed on a system of databases.
• The DBSA owns all Versant database root directories for all installations in a network.
• The DBSA owns all system information files for all installations in a network.
5.1.1.2. Database Administrator—DBA
Database administrators are responsible for the operation of Versant databases. There is a primary DBA and, possibly, additional secondary DBAs. The function of the primary DBA is to create databases, grant
60 Versant Server Guide
Versant Users and administer user access to databases, including creating secondary DBAs, and to use the various
Versant utilities to perform any and all administrative database tasks such as defragmentation, backup and restore, performance monitoring, etc. Secondary DBAs have elevated privileges, in comparison to normal database users, allowing them to run administrative tasks using the utility API calls in the Versant
SDKs.
5.1.1.2.1. The Primary DBA
In the discussion that follows, “DBA” refers to the primary DBA. A secondary DBA is always referred to as such.
The following is a list of parameters to define the DBA user.
• There can be only one DBA for any database.
• There may be any number of DBAs in a Versant system of distributed databases (there may be a different DBA for each database).
• The DBA should have an OS account. The DBA user name should correspond to the OS user name.
• The DBA owns the database and related files and directories. After a database has been created, you can change its DBA by changing the ownership of its database directory.
• The DBA has access to the database even if the DBA name is not in the database user list.
• Only a DBA can delete the files in a database directory.
Password Authentication for DBA
Versant introduces a password-based authentication for the DBA on top of the existing OS dependency.
The makedb utility will give the user an option to input a password to be associated with DBA. When a password is specified, it is stored in a new file .pw (Linux and Windows) in the respective database directory.
If the user does not specify a password for the DBA with the makedb utility, only the OS check is performed. The DBA can also be associated with a password later, by using the dbuser utility with the –chpasswd option.
For more information, please refer the
and
Versant Server Guide 61
Versant Users
Password Authentication for a Database
If the database is associated with a password, then some utilities will prompt the user to specify the
DBA password before making any changes to the database.
Users are allowed a maximum of three attempts at password entry. After three failed attempts, an error message will be returned.
The following utilities require password authentication.
addvol dbinfo removedb stopdb
5.1.1.2.2. Secondary DBA
comparedb dbtool removereplica vbackup createdb dbuser setdbid vcopydb createreplica ftstool startdb vmovedb
Often the need arises for a user other than the primary DBS to perform administrative tasks. The primary
DBA can create one or more secondary DBAs who have the rights needed to perform certain administrative tasks using the appropriate Versant API call. For example, only the primary DBA can run the addvol command line utility. But a secondary DBA is able to execute a program that calls, e.g., the V/C++ addvol()
API to perform the addvol function.
The API functionality permitted of a secondary DBA is indicated in
Privileges” pg. 64. Refer to the column “Secondary DBA”.
A secondary DBA user for a database may be created (by the primary DBA) using the dbuser utility as shown.
dbuser -add -n -rdba -password Password -role DBA DatabaseName
5.1.1.3. Database User—DBUser
The database user is a normal user, who has access to a particular database. The parameters which define this user are as follows:
• The database user can act only according to the account privileges that he has been given by the DBSA or DBA.
• The database user may or may not have a valid operating system user account.
• A database user can change their password using the database user management utility (dbuser).
62 Versant Server Guide
Versant Users
Versant maintains a list of users who have been given the access to a particular database by the DBSA or DBA.
Database User List
For all installations and all operating systems, Versant maintains a list of users who have access to a particular database, called the database user list. The following outlines the parameters which define the database user list:
The database user list for a particular database is created and maintained by the DBA of that database.
Each database has only one database user list. Each database can have a uniquely defined user list.
The members of the database user list can connect to, and use a particular database. Members of a user list can also execute utilities to retrieve information about a database system.
5.1.1.4. Root User—root (Linux)
For Linux installations a root user is the user with operating system root privileges for a particular machine on a network.
Being a root user with privileges deriving from operating system permissions provides only minimal privileges with respect to Versant. It is not required to use Versant as the root user.
Example 5.1. Root User for Linux
On a Linux system, if the database root directory is /Versant/db and a database has been created using
/Versant/db/db1 as a database directory, then the DBSA is the user that owns /Versant/db and the DBA for database db1 is the user who owns both /Versant/db/db1 and the database volumes that comprise the database.
5.1.1.5. Managing Database Users
The database users can be managed with the dbuser utility.
The dbuser utility has a variety of functions for performing user management. For example, to add and delete, or to list the users of a database, and to change password of a database user.
For more information please refer to
.
Versant Server Guide 63
Utility Access Privileges for Database Users
5.2. Utility Access Privileges for Database Users
The following are the utility access privileges for each database user. Also shown are utilities which can be executed remotely or by a secondary DBA.
These privileges are the same whether a system utility is executed from a command line or from the
Versant utility tool.
Table 5.1. Utility Access Privileges
Utility Name DBSA DBA DBUser
no no yes yes no no
Secondary DBA via utility API
a yes yes addvol comparedb compardb convertdb cnvrtdb createdb createreplica creatrep db2tty dbid dbinfo dblist dbtool dbuser dropclass dropcls dropinst ftstool makedb makeprofile makeprof no no no no no no no no yes no yes no no no yes yes yes yes yes yes yes yes yes yes yes yes yes yes no no no yes yes no yes no no b yes yes yes no no no yes yes yes yes yes yes yes yes yes yes no yes yes
64 Versant Server Guide
Utility Access Privileges for Database Users
Utility Name
oscp polling removedb removereplica removrep sch2db setdbid ss.d
startdb stopdb vbackup vbbadmin vcopydb verr verrindx vmovedb vstats vstream
DBSA
no no no no no no no no yes no no yes no yes no no no
DBA
yes yes yes yes yes yes yes yes yes yes yes yes yes yes yes yes yes
DBUser
yes yes no no no no no no yes yes yes yes no yes no yes no
Secondary DBA via utility API
a yes yes yes yes yes yes no yes yes yes yes yes yes yes yes yes yes
Note that the secondary DBA may only use the associated Versant utility API call to perform the operation.
Refer to
Section 5.1.1.2.2, “Secondary DBA” pg. 62.
A registered database user can change their password with dbuser -chpasswd.
Versant Server Guide 65
User Authentication
5.3. User Authentication
User Authentication is the means of identifying the database user in a unique way.
User identification is the basis of Versant's authorization mechanism. The users are allowed access to the system only when identified as 'authorized' users by the system.
To prevent unauthorized use of a database, Versant provides different methods of user identification:
• Database Administrator Authentication
• Database User Authentication
• Customized User Authentication
5.3.1. Database Administrator Authentication
When Database Administrators (DBAs) have valid operating system account, Versant relies on operating system mechanisms to verify the DBA's identity.
Versant provides password-based authentication for the DBAs on top of the existing OS authentication mechanisms.
The utility makedb will give the user an option to specify a password for the DBA.
When a password is specified, it is stored in a new .pw file in the respective database directory. The password file will be created with READ/WRITE permission for the DBA only.
If the DBA does not specify a password with the makedb utility, no additional authentication check, other than the OS mechanism, is performed for the DBA. A DBA can specify a password later using dbuser with the –chpasswd option.
A password is a literal string which may not exceed 255 characters. There should be no spaces (' ' characters) in the password.
The null string is reserved for a null password. If the DBA does define a password, they can specify the string "" as the password (or not specify a password at all).
66 Versant Server Guide
User Authentication
5.3.1.1. DBA Authentication for Specific Utilities
Some utilities in Versant require DBA authentication.
The following utilities will prompt the user for a password when the database is password protected.
addvol dbinfo removedb stopdb comparedb dbtool removereplica vbackup createdb dbuser setdbid vcopydb createreplica ftstool startdb vmovedb
Versant users, including DBAs, are allowed a maximum of three attempts at password entry. After three failed attempts, an error message will be returned.
5.3.1.2. DBA Authentication for Utility APIs
For some utility APIs, you can specify the password with the -password option.
These utility APIs are o_makedb, o_createdb etc.
Here the caller can specify the DBA password through the -password option if DBA user has a password protected.
For the DBA utility API o_setdbid, the caller specifies the DBA user name and password through the o_setuserlogin
API.
Versant Server Guide 67
User Authentication
Example 5.2. DBA Utility APIs with Passwords
The following examples illustrate the usage of the DBA utility APIs with passwords:
1. Using o_createdb: o_nvlist nvlist; o_createnvlist(&nvlist); o_addtonvlist(nvlist, “-password”, “mypassword”); o_createdb(dbname, nvlist);
2. Using o_setdbid with o_setuserlogin: o_userInfo userinfo; strcpy(userInfo.username, “DBA’s name”); strcpy(userInfo.password, “DBA’s password”); o_setuserlogin(&userinfo); o_setdbid(dbid, dbname);
The utility APIs will not use the information set by the o_setuserlogin API, and o_setdbid is an exception.
The o_setdbid API gets the information of user set from the o_setuserlogin API. Regardless of whether or not the thread is in a session, the user must provide the DBA password to the utility API when the database is password protected.
5.3.1.3. DBA Authentication for Session Connection
Applications that connect to the database remotely should provide a password to the user connecting to the database. This is also applicable to a DBA connecting to the database remotely. The application should provide the password using the o_setuserlogin API as described in the Versant CReference.
When connecting to a password protected database, authentication will fail if the password is not provided.
In Versant, a session connection to the server implicitly starts the server even if the user calling the session connection is not the DBA. After the database has started, and if the user performs any database administration tasks, the password should be supplied as part of that API for verification.
68 Versant Server Guide
User Authentication
5.3.1.4. DBA Authentication for Versant FTS
For V/FTS, the DBA must ensure that the same password is used for the replica pair.
If the passwords are different, the utility createreplica will return an error while connecting to the database.
5.3.1.5. Changing the DBA Password
The dbuser utility can be used to change the DBA password. The user must be logged into the OS as the
DBA to run this command.
dbuser -chpasswd -n dbaname -passwd newpassword -opasswd oldpassword
Failed Authentication Errors
If the password verification fails, the SM_E_INVALID_PASSWORD error is returned.
If the user is not logged into the OS as the DBA while changing the password for DBA, the
UT_ER_USER_NOTDBA error is returned.
Password Recovery
If the DBA forgets the password, the DBA can login as an OS user and delete the password file.
Once the password file is deleted, the DBA authentication will bypass the password check and the
DBA can gain access to the database.
When a new password files needs to be created, the DBA creates a new password using the dbuser utility to protect against any remote DBA activities.
5.3.2. Database User Authentication
Versant authenticates users attempting to connect to a particular database by using the information stored in that database.
Versant utilizes password-based authentication for users with a valid password and operating system based authentication for users without a password. During operating system based authentication, passwords are not checked. The only requirement is that the user be a valid OS user.
Versant Server Guide 69
User Authentication
The DBA can choose to add a user without a specified password, in which case the authentication mechanism at the server-side is operating system based. For users with a password, password based authentication is followed at the server-side.
The client is authenticated at the server during the initial connect. Once the connection has been established, no further authentication is done for the duration of that connection.
The client has a secret password, known only to the client and the server, and this password cannot exceed 255 characters. The client sends the password to the server to prove it's identity. The server verifies the client's password based on the information stored in the database.
User Authentication Procedure
If the user information is not set by the application before connecting to a database, the user name from the operating system will be picked up as the default user name.
When the user entry in the database doesn't have a password, the server assumes operating system authentication and performs the corresponding check for that user during the initial connect. When performing operating system level authentication, the user must already exist as a valid OS user, both on the client and the server side. Failing to satisfy both these conditions would result in an authentication failure. When the user entry in the database has a valid password, only password-based authentication is performed. Failing to provide the correct password will result in an authentication failure.
The following outlines the authentication process mechanism.
• dbuser -add -n user1 -passwd "" dbname
This creates a new user, user1, with no password.
• dbuser -add -n user2 -passwd user2-password dbname
Another user, user2, with a password.
• db2tty -D dbname
If the user invoking the db2tty process is user1, this command will be authenticated based on the OS.
• db2tty -D dbname
70 Versant Server Guide
User Authentication
If the user invoking the db2tty process is user2, this command will fail when it performs password based authentication.
• dbuser -ch passwd -n user1 -passwd user1-password
The user invoking this command must be user1 for successful authentication.
• db2tty -D dbname -u user1 -p user1-password
Will succeed from any machine and as any OS user.
Versant Server Guide 71
72 Versant Server Guide
Chapter 6. Database Profiles
Sections
• Application Process Parameters
- Application Process Profile Parameter Types
- Server Process Profile Parameter Types
- Database Creation Parameters
- Event Notification Parameters
• Online Database Configuration
- TCP/IP Keep Alive Parameters
This chapter describes the database profile parameters for application processes, the server process and operating system.
Versant Server Guide 73
Application Process Parameters
6.1. Application Process Parameters
This section applies only to the Versant C++ and JVI interface.
6.1.1. Overview
When you use the makedb or makeprofile utilities, if an application profile file does not already exist,
Versant will create an application process profile with the same name as the database you are creating.
When you start a database session and specify a database to be used as the session database, Versant reads the application profile for that database and uses the parameters it finds there to set the operating environment for the application.
At any time, you can edit the contents of an application profile to change the operating environment for your application process. The parameters are read each time a session starts. The existence of an application process profile file is optional, if one does not exist, default values will be used.
It should be noted that different users use different application profiles while connecting to the database even if they are running the same program because the application process profile will be read from different locations.
If you want the changes in application process parameters to be reflected for all the users, you need to distribute the modified application process profile file to all the users of the database.
When setting parameters involving bytes, specify the size using a
To create a comment line in the profile file, you must use the pound sign (#) as the first character of the line.
Application Process Profile Location
The Versant installer will create a subdirectory named .osc (Linux) or osc (Windows) under your home directory. This directory will contain application process profiles for the databases that you create. For example, for a database named MyDatabase, the application process profile is $HOME/.osc/MyDatabase on Linux machines and %HOMEDRIVE%%HOMEPATH%\osc\MyDatabase on a Windows machine.
74 Versant Server Guide
Application Process Parameters
Refer also to
Section 4.2.4, “Application Process Profile File” pg. 50 for information regarding this file.
6.1.2. Application Process Profile Parameter Types
The application process profile can understand and use the following parameters.
Functional Parameters
The parameters listed below are described in detail in the section
.
Parameter
genericObject loose_schema_mapping
Parameter
dbconnect_timeout estimated_connections estimated_objects
Description
Aliases for local and remote databases
Automatic connections to group databases each time a session starts
Turns on or off the use of the generic version object. This is not used anymore but left here for backward compatibility.
Allows inconsistent class definitions
When using multiple databases, determines whether objects are written to the databases in parallel or serially.
Blocks unwanted signals, such as Ctrl-C, that might otherwise damage shared memory.
Tuning Parameters
The parameters listed below are described in detail in the section
Description
Overrides the Operating System TCP/IP driver connect() timeout settings
Sets the maximum number of database connections that can be made in a database session
Sets the estimated number objects that will be accessed in a session
A pre-allocation hint for the size of the application heap, which includes cached objects, the cached object descriptor table, and other data structures.
Expansion increment of application heap
Sets initial cod table size
Versant Server Guide 75
Application Process Parameters
Parameter
preload_schema schema_cache_size
Description
Enables the loading of the entire schema to the session cache during transaction inititation
Controls the size of the schema cache index
Swaps threshold. If less than this amount of the application heap is used, object swapping will not be attempted by the system.
6.1.3. Functional Parameters
In the parameter descriptions below, database_name refers to the application process file belonging to a database of the same name.
alias
alias alias_name database_name[@node]
Sets the alias alias_name for the database database_name.
Only lower-case alphabetic (a-z) and numeric (0-9) characters are allowed in alias names.
For a remote database, append the node name to the database name using the syntax database@node.
Aliases are kept throughout a session. Each alias must be entered on a separate line. Setting aliases is optional.
Aliases have two purposes, convenience and performance tuning.
Convenience
The primary purpose of aliases is to simplify application syntax and to allow later changes of alias references without having to change applications that use the aliases.
When an application uses a remote database, specify the remote database name in such a way that it indicates that the database is on another machine. You do this with database_name@location syntax. This syntax can either be used in each reference made to the remote database in an application
76 Versant Server Guide
Application Process Parameters or by creating an alias in the Application Process parameter file for the database you are using as your session workspace.
For example, if your application uses two group databases named groupdb_1 and groupdb_2 located on machines machine_1 and machine_2, you can add the following lines to the file
$HOME/.osc/personaldb
: alias gdb1 groupdb_1@machine_1 alias gdb2 groupdb_2@machine_2
After setting these aliases, you can then refer to the group databases in your application with the names gdb1 and gdb2. If you later change the location of either database or decide to use different group databases in your application, you only have to change the aliases rather than editing your program.
Performance tuning
Aliases allow the use of different database parameters for one database depending upon the application using it. For example, for one application you might want a large heap size, while for another one you might want a small heap size.
To use of several sets of database parameters for one database, first create several sets of profiles with differing names. For example, you might create profiles named profile_one and profile_two.
To specify which application process file to use for a particular application, use database aliases. In each of the profiles you create, specify an alias for the database that you want to use as your session workspace.
Suppose, you have a database whose real name is db and you have two application process parameter files, $HOME/.osc/db1 and $HOME/.osc/db2. The db1 file should have the alias entry alias db1 db, and the db2 file should have the entry alias db2 db. Then, in your program, if you specify beginsession(db1,..)
, the database db will be started using the entries in the application profile file db1. If you specify beginsession(db2,..), the values in the file db2 will be used.
If there is no application process parameter file with the name specified in a "begin session" method, then a session is started in the database of the same name using default values of the parameters.
connect
connect group_db access_mode
Automatically connect to the group database group_db when you begin a session.
Versant Server Guide 77
Application Process Parameters
Access modes are READ_ONLY, READ_WRITE or WRITE_ONLY.
You can make multiple connect entries to connect automatically with multiple group databases.
Specify remote databases with db@node syntax.
Connections to databases made using the connect parameter can be disconnected by calling a
"disconnect database" routine from within a session. Otherwise, the connections will be terminated when you end the session.
For example, if you wish to connect to a group database named groupdb1 on machine1 and groupdb2 on machine2 every time you begin a session, add the following statements to your application process parameter file.
connect group1@machine1 READ_WRITE connect group2@machine2 READ_WRITE
genericObject
This setting is not used any longer and is left here for backward compatibility.
genericObject ON | OFF
Turn use of the generic object OFF and ON.
The default is OFF.
loose_schema_mapping
loose_schema_mapping ON | OFF
Turn loose schema mapping ON or OFF.
The default state is OFF.
When the loose schema mapping is OFF, an application compiled with an old class definition can continue to use a database even if class definitions differ.
When the loose schema mapping is ON, whenever an application accesses a class in a database,
Versant compares the database definition of the class with the definition expected by the application.
If the database and application definitions of the class differ, an exception is raised.
78 Versant Server Guide
Application Process Parameters
The following tables summarize the behavior.
Table 6.1. Loose Schema Mapping Is ON
Condition
attribute is the same in application and database attribute exists in database only
Create Object
OK attribute is set to zero when object is written to database attribute exists in application only attribute type has been changed attribute is not written to database exception is raised: types do not match
Read Object
OK attribute is not seen attribute is set to zero exception is raised: types do not match
Write Object
OK attribute is not modified when object is written to database attribute is not written to database exception is raised: types do not match
Table 6.2. Loose Schema Mapping Is OFF
Condition Create Object
attribute is the same in application and database attribute exists in database only
OK exception is raised: signature mismatch wrong layout or
Read Object
OK exception is raised: signature mismatch wrong layout or
Write Object
OK exception is raised: signature mismatch or wrong layout attribute exists in application only exception is raised: signature mismatch or wrong layout attribute type has been changed exception is raised: types do not match exception is raised: signature mismatch wrong layout exception is raised: types do not match or exception is raised: signature mismatch or wrong layout exception is raised: types do not match
parallel_write
parallel_write ON | OFF
Use a write optimization that writes objects in parallel, to a group of databases and thereby improves the overall write performance.
Versant Server Guide 79
Application Process Parameters
The default option for this parameter is ON.
It is important to understand how object writes normally work in order to understand the influence of this parameter.
The write consists of two main phases; first, writing the objects to the destination database server and second, waiting for a confirmation from the server that the write was successful. The first phase of writing to the server is resource intensive as it involves logging and other activities and the client usually blocks while waiting for a response from the server. It is more efficient if the blocking-time is better utilized to write out the other objects to other databases. This is the fundamental design philosophy behind parallel write.
If parallel_write is OFF and an application explicitly or implicitly flushes / writes objects to multiply connected databases in a session then both phases of the write is performed on one database at a time.
If parallel_write is ON then the Versant client object manager performs the first phase of the write on all the respective databases and then the second phase is performed.
Enabling the parallel_write feature is important to V/FTS performance, since V/FTS also involves multiple connections to databases (an explicit connection to a primary database and an implicit connection to the secondary database).
signal_block
signal_block ON | OFF
Blocks unwanted signals. The default is OFF.
When signal_block is ON, the following signals are blocked:
SIGHUP
SIGALRM
SIGTSTP
SIGWINCH
SIGINT
SIGTERM
SIGCONT
SIGLOST
SIGQUIT
SIGURG
SIGCHLD
SIGUSR1
SIGPIPE
SIGSTOP
SIGIO
SIGUSR2
6.1.4. Tuning Parameters
Versant has many parameters that you can configure to optimize database performance. Following are descriptions of these database tuning parameters.
80 Versant Server Guide
Application Process Parameters
dbconnect_timeout
dbconnect_timeout number
This parameter can be used to override the Operating System TCP/IP driver timeout settings of connect() calls. The values accepted for this parameter is an integer in seconds. Non-integer values will result in error OM_PROF_SYNTAX.
A client issues a connect() whenever a o_beginsession() or o_connectdb() is called. The session database settings for dbconnect_timeout will be used to connect to all the databases in the session.
The default value is -1. When the default value is set, the TCP/IP driver settings for connect() timeout is used. Any non-negative value will override the TCP/IP driver timeout settings of connect() calls. The value is limited to the maximum value of a signed integer. The value 0 indicates zero timeout and is not recommended as the connection would most certainly timeout. All negative values indicate a value of -1.
estimated_connections
estimated_connections number
Set the maximum number of database connections that can be made in a transaction.
Despite the use of “estimated” in its name, the estimated_connections parameter sets a hard limit on the number of databases being accessed within the scope of a transaction (irrespective of whether they are connected or disconnected).
The default value of this parameter is 4.
This parameter is useful in reducing memory requirements.
estimated_objects
estimated_objects number
Explicitly specify the estimated number of objects that you will access in a database session.
The default value is 32K objects.
You can set this number higher if you will access more than 32K objects in a session.
Versant Server Guide 81
Application Process Parameters
This parameter affects the size of system information tables, such as the cached object descriptor table, that are created when you start a database session. If your application creates and uses multiple, concurrent database sessions and, in each session, accesses only a few objects, you can set this parameter low to reduce memory use. On the other hand, if you are using a single session at a time and accessing a large number of objects in the session, you can set this parameter high to improve performance.
See also,
heap_size
(application)
heap_size size
A pre-allocation hint for the size in bytes of the application heap. The applications heap contains cached objects, the cached object descriptor table, and other data structures.
If your swap space is too small, you may run out of swap space while your application is running. If you know that a session will require a lot of memory, you can pre-allocate space for the application process heap by setting the initial heap size. If more memory than the initial amount specified by this parameter is needed, the heap size is dynamically increased as needed.
If your application requires more heap space than is available, an error will indicate that you have run out of swap space.
Normally you do not have to set this parameter since the application process heap is expanded dynamically as needed, and Versant can determine an appropriate initial value.
See also,
heap_size_increment
(application)
heap_size_increment size
Set the size by which the application process heap will be expanded as needed.
The default increment is 1M.
See also,
82 Versant Server Guide
Application Process Parameters
max_objects
max_objects size
Specify a minimum initial size in bytes for the cached object descriptor table. This initial size also becomes the increment by which the size of the cached object descriptor table increases as needed.
The default value is 32K.
The cached object descriptor table is dynamically allocated and will increase in size as needed.
This parameter is relevant if you are accessing only a few objects in a session, which might be the case when, say, you are using a large number of concurrent sessions. If you are going to access only a few objects, then you might want to decrease this value in order to reduce memory costs. If you are going to access a large number of objects, you might want to increase this value in order to improve performance.
See also,
preload_schema
preload_schema ON | OFF
Setting this parameter to ON (the default is OFF) causes the entire database schema to be brought into the session cache during transaction initiation, rather than lazily, on an as-needed basis. This can help to reduce the cost associated with retrieving individual schema objects that may be needed in the client cache during the life of the transaction, for C+ class management, query parsing, etc.
Using preload_schema on enables code that tracks when schema objects are removed from the cache, such as by object swapping, transactional activity and database connection/disconnection operations, and reloads the schema objects for each connected database when a new database connection is established or a new transaction is started. When a rollback, or an explicit cache purge (o_resetoct
API) or other transaction boundary operation results in clearing this cache, the schema objects will be reloaded again upon completion of the responsible API call.
schema_cache_size
schema_cache_size size
This parameter controls the configured size of the hash index used by the cache of schema objects.
Using a larger number reduces the likelihood of a lookup collision, which requires extra cycles when
Versant Server Guide 83
Application Process Parameters comparing names of classes in the cache with the items in the cache. The parameter value is a numeric argument which can also be specified using scaled notation such as nnnK (nnn times 1000) or other numeric scale shorthand. In order to simplify hash key computation, the specified schema_cache_size value is rounded to the next single-bit power of 2. The default value is 512. The maximum useful value is the total number of schema objects in all the databases you will connect to in the same session.
swap_threshold
swap_threshold size
Specify the point at which object swapping begins.
Object swapping is the process in which objects residing in an application object cache are returned to their databases. When the object cache tries to grow beyond the swap threshold size, object swapping will occur.
The default swap size is 512M.
The swap threshold is a hard limit on the size of the cache, so swapping will begin as soon as the size of the cache exceeds the value of the swap threshold parameter.
An object chosen for swapping will be written to its database if it has been marked as dirty or discarded if it is clean. When objects which have been swapped out are accessed, they must be retrieved from the server.
Object swapping is not as good as keeping the objects cached in physical memory, but it is far better than virtual memory thrashing.
The optimal value of this parameter depends on your application and environment. If objects are always referenced in the same order, then objects which are used together are stored in contiguous memory addresses, and virtual memory will perform well. In this case, swap_threshold should be set much higher than physical memory, so that virtual memory is used instead of object swapping.
If, on the other hand, objects are accessed in an unpredictable order, object swapping is preferred and the parameter should be set low enough to prevent thrashing.
In any event, you should set the swap threshold high enough so that as much of physical memory as possible is used.
The following error messages may indicate that you are running out of swap space:
84 Versant Server Guide
Error Code
0054
1100
3002
4161
6009
Error Message
VSL_MEM_NOMEM
SM_E_NOMEM
NET_ENOMEM
OM_HEAP_NOMEM
SCH_NOMEM
This parameter affects the logical log.
Application Process Parameters
Description
Out of process memory
Out of back-end heap memory
Unable to allocate memory
Out of front-end heap memory
No heap memory in schema management
A low swap threshold can cause the logical log file to grow because the writing of dirty objects to a database generates logical log records. Consider the following scenarios.
Scenario 1
An object is modified only once during the course of a transaction and the swap_threshold value causes it to be swapped out at some point. In this case, there is no relative impact on the logical log, because a record would be written to the logical log anyway when the transaction committed.
Scenario 2
An object is modified several times during the course of a transaction, but is swapped only once at the end of all these modifications. In this case, there is still only one group-write operation, and one set of logical log records for the object.
Scenario 3
This is the worst case. The object is modified several times during a transaction and also swapped several times because of the swap threshold kicking in. In this case, there is "thrashing" of the object cache. Now there would be several logical log records for the same object, with a new set of logical log records being generated each time a swap occurred. If the object is a "hot" object, which needs to be referenced and updated frequently, it could cause the logical log file to grow dramatically and exceed its limits.
Scenario 3 shows that if your cache is too small as defined by the swap_threshold parameter, you may see unexpected growth in your logical log file. The fix is to either increase the size of your object cache by increasing the swap threshold value or else to increase the space available for your logical log file to grow.
Versant Server Guide 85
Application Process Parameters
As a rule of thumb, we recommended that if you have a large database application, you should allocate at least 96M of swap space.
86 Versant Server Guide
Server Process Parameters
6.2. Server Process Parameters
6.2.1. Overview
The server process parameters determine many aspects of database behavior. The parameters are broadly catagorized by their action—parameters used when creating the database; functional parameters for control of logging behavior, locking, etc.; tuning parameters to specify such items as caching behavior and log volume sizes and parameters for controlling reporting behavior using tracing, the BlackBox, event notification, query monitoring and database size reporting. The parameters and parameter groups are listed in
.
The parameters are associated with a particular database. Each database directory contains the process
parameter profile file, named profile.be. When you call the makedb utility, the database directory is created and along with it the profile.be file. (You can also create a process parameter profile file with the makeprofile utility. Refer to
Section 10.15, “makeprofile ” pg. 263.) The file content is a list of
parameters with their values. The following example parameter entry shows the general form.
# Specify whether server process buffers are flushed to disk
# after commits.
commit_flush off
Here, the parameter name is commit_flush and the value is off. The name and value are separated by one or more spaces (or tab characters) and must be on the same line. In the file, the parameters are usually introduced by a short description. Lines beginning with the # character are comments. In a newly created parameter profile, all parameters are set to their default values.
File and memory sizes—byte specifiers
For profile parameter values such as a file or memory allocation sizes, the value is given as a number of bytes—256 kilobytes, 64 megabytes, 4 gigabytes, etc. These byte specifiers are given as a positive integer followed immediately by a letter signifying the magnitude. The letters are K for kilobyte, M for megabyte and G for gigabyte. For example, the three sizes mentioned above are specified as parameter values as
256K
, 64M and 4G. Parameter values that use this from are named as “byte specifier” in the parameter descriptions.
Parameter scope—when is the value applied
Versant Server Guide 87
Server Process Parameters
The parameter values in the parameter profile are applied at specific times. When the parameter value is applied is referred to as the scope in the parameter descriptions. The following scope descriptions are used.
• Parameters that only apply—that are only read—when the database is created with the createdb utiltity. This allows you to modify these parameters, if desired, after the parameter profile file has been created with makedb.
scope: read at database create
• Most parameters are read and their values take effect when the database is started.
scope: read at database start
• Parameters that take their initial value from the profile file when the database is started but may be modified “on-the-fly” while the database is in use. (Refer to
scope: configurable at runtime
List the profile parameters
You can list the process profile parmeters along with their current value, next startup value, and default value with the command dbtool -config -get DatabaseName. In the list, the column “Change Online” refers to the parameter having the “scope: configurable at runtime” as described above.
6.2.2. Server Process Profile Parameter Types
The different types of Server process profile parameters are:
Database Creation
Versant uses these parameters only when you create a database with createdb. If you change these parameters after you create the database, the system just ignores your changes.
The parameters listed below are described in detail in the section
Database Creation Parameters .
Parameter
Description
The number of pages per extent on the system volume
The maximum size of the system volume
88 Versant Server Guide
Server Process Parameters
Functional Parameters
Versant uses these each time you start the database. You can edit these parameters to affect the performance of your database.
The parameters listed below are described in detail in the section
.
Parameter
auto_addvol_threshold auto_addvol_aggression
versant_be_dbaloggingfile versant_be_logfile
Description
Set implicit database start up on or off.
How cache flushing is performed
How log flushing is performed
Enable automatic addvol feature
Specify when an add volume should be triggered by the server
Checks the overall used space in the database volumes and decides whether to add a volume or not
Whether object deleted at commit
Whether buffer is flushed after a commit
Location of storage volumes
Control whether the legacy connector is enabled, i.e., whether earlier client versions (Versant 9.1 and earlier) can connect to the Versant Server release 9.2 or later
Turn short locking on or off
Turn logging on or off
Specify executable name that will be run at database startup
Set DBA logging level as 0 or 1 for a database
File used to log DBA utility activity
Specify location of the per-database LOGFILE
Control system logging
Tuning Parameters
Versant uses these each time you start the database. You can edit these parameters to change the operating parameters of your database.
Versant Server Guide 89
Server Process Parameters
Most of these parameters are optional, as the default values are appropriate for most situations.
However, the parameter class is crucial to databases containing a large number of classes - if more than the default number of 2000 classes will be accessed during the time a database is running, you will need to specify a new value for class.
The parameters listed below are described in detail in the section
Parameter
lock_wait_timeout max_page_buffs
max_sorting_memory_per_query max_sorting_memory_total
plog_buf_size polling_optimize
Description
Perform cache flushing periodically
Perform a sync every time the cache is flushed
When the cleaner thread starts flushing dirty pages
When the cleanup thread stops flushing dirty pages
The number of cached user defined classes
Database timeout
The number of cached user defined indexes
The size and location of the logical log volume
The maximum size the logical and physical log volumes can acquire
Use buffered or direct I/O for log file access
Size of the logical logging buffer in bytes
Time to wait for a lock
The number of cache buffers
Control client transaction processing speed during the Versant
FTS re-syncing operation. Refer to Section 3.5.2, “Adjusting
Client Transaction Performance” in the Versant FTS User's
Guide
The maximum size the sorting memory for each query can grow
The maximum size the sorting memory areas of all on-going queries put together can grow
The size of the physical log volume
Size of the physical logging buffer in bytes
Strategy for V/FTS recovery
Time a schema evolution waits for active transactions to commit/rollback
90 Versant Server Guide
Server Process Parameters
Parameter
Description
Time a schema read waits in case a schema evolution is taking place
Spin lock busy wait loop count
The maximum number of concurrent transactions
Initial size of user names list
The number of cached data volumes
Heap Memory Parameters
Parameter
heap_arena_size heap_size_increment
heap_arena_size_increment heap_max_arenas
heap_arena_trim_threshold heap_arena_segment_merging
Parameter
Description
A hint for the initial size of server heap
A pre-allocation hint for the initial size of an arena in the heap
Size by which server heap can be expanded
Set the size by which an arena will be expanded as needed
Specify the maximum number of heap arenas
Enable/disable the multi-region heap
Determines the minimum amount memory to keep in an arena
Controls whether segments should be traversed (and possibly merged) or not
Statistical Parameters
Versant can collect statistics and vary assertion levels using these parameters.
The parameters listed below are described in detail in the section
Description
Turn collection of connection and database statistics on or off
Type of assertions
Query Monitoring Parameter
Reports a query plan, i.e., information about queries, on the server.
Versant Server Guide 91
Server Process Parameters
The parameter listed below is described in detail in the section
.
Parameter
Description
Reports a query plan, i.e., information about queries, on the server
Tracing Parameters
Versant has tracing facilities. You can set the number of traces and the file in which the system stores the traces by using these parameters.
The parameters listed below are described in detail in the section
Parameter
Description
Database components to be traced
Number of trace entries to be maintained in the trace file
Name of the trace file
BlackBox parameters
Versant black box tracing parameters.
The parameters listed below are described in detail in the section
.
Parameter
blackbox_trace_entries blackbox_trace_comps
Descriptions
Specifies the maximum number of entries in the BlackBox
Specifies the database server components that are traced with the BlackBox
Event Notification Parameters
Versant can save event registrations and generated events by using these parameters.
The parameters listed below are described in detail in the section
Event Notification Parameters .
Parameter
Description
Code path and parameters for an event delivery daemon.
Notification type when event daemon goes down.
92 Versant Server Guide
Server Process Parameters
Parameter
event_msg_transient_queue_size event_registration_mode
Description
Persistent or transient messages
Maximum number of per-transaction events held in the transient event queue
Persistent or transient registrations
Database Space Parameters
Versant parameters to configure messaging relating to the space remaining in the database.
The parameters listed below are described in detail in the section
.
Parameter
out_of_space_warning_threshold
Description
Threshold value that triggers generation of system messages
out_of_space_warning_threshold_increment
Indicates the increment at which a warning message should be generated
6.2.3. Database Creation Parameters
extent_size
extent_size number_of_pages
The extent_size parameter specifies the number of pages per extent on the system volume.
An extent is the minimum unit of allocation of pages in the database. The number of pages per extent tunes time versus space tradeoffs. In general, setting a low number of pages per extent causes less space to be wasted by fragmentation and decreases the initial size of an empty database. It also makes it more likely that, over time, objects will be broken up and placed in different physical locations on the disk, thus slowing down access to the data. Setting a high number of pages per extent decreases the likelihood that objects will be broken up and placed in different physical locations on disk, but it also increases use of disk space.
The default extent size is two (2) pages. Depending on the database volume size, Versant adjusts this parameter at the time of database creation.
allowed values:
Versant Server Guide 93
Server Process Parameters positive integer
default value:
2
scope:
read at database create (createdb)
See also,
sysvol
sysvol size name
The size and location of the system volume that contains database system catalogs and objects. This parameter is read when the database is created. The default values for size and name are 1024M (1024
Megabytes) and system, respectively. To change either of these, edit the database profile, profile.be, before calling createdb. (The profile.be file is created by the makedb utiltity
You cannot change the size or name for the system volume once a database has been created. To add space to a database, you must either add additional database volumes (with the addvol utility) or remove and recreate the database with a larger value specified for the sysvol parameter.
Parameters size
The size of the system volume.
allowed values:
(minimum 2M, maximum 65535M)
default value:
1GB
(with default extent_size of 2)
The extent_size is internally increased to the appropriate value to fit these requirements. For example if the extent_size specified in the profile is 2 and the system volume is size of 65535M.
The extent size is internally increased to 64.
94 Versant Server Guide
Server Process Parameters
name
Either the absolute or relative path (including name) of the system volume.
allowed values:
valid file name
default value:
system
If you specify an absolute path, you will not be able to move the database once it has been created.
The createdb and addvol utilities will raise an error if you create or add a database volume smaller than the minimum size. (The minimum size is dependent on the setting of extent_size, approximately the extent size times 2K.)
If you run out of space in the system volume, you will receive the error message “1083
SM_E_OUT_OF_VOL_SPACE all volumes exhausted
” during the execution of an application program.
If you get this message, you should use the addvol utility to create additional database space.
Occasionally, you may get a panic message if a database is out of space inside a critical region. The panic message may be error message 1083 as shown above.
scope:
read at database create (createdb)
6.2.4. Functional Parameters
allow_implicit_startdb
allow_implicit_startdb off | on
The allow_implicit_startdb parameter is on by default, i.e., an application connect will implicitly start a database if it is not already started. Setting allow_implicit_startdb off ensures that the database can be started only by explicitly calling startdb.
allowed values:
Versant Server Guide 95
Server Process Parameters off
, on
default value:
on
scope:
read when attempting database start
Disabling implicit database startup will cause some features/addons, for example, Versant FTS, to not work as expected.
async_buffer_flusher
async_buffer_flusher number
If this parameter is set to an integer greater than zero, a separate thread will be used to asynchronously flush the database server cache to disk. This is the default behavior (the default value is 1).
If this parameter is set to zero, the database server process itself will flush the database server cache
(no separate thread will be started.)
allowed values:
0
, 1 (or positive integer)
default value:
1
scope:
read at database start
This was previously named async_buffer_cleaner. The previous name is deprecated but may still be used. Instances of the previous name are replaced by the new name whenever the server triggers a rewrite of the profile file.
96 Versant Server Guide
Server Process Parameters
async_logger
async_logger number
If this parameter is set to an integer greater than zero, a separate thread will be used to asynchronously flush the database logging cache to disk. This is the default behavior (the default value is 1).
If this parameter is set to zero, the database server process itself will flush the database logging cache (no separate thread will be started.)
allowed values:
0
, 1 (or positive integer)
default value:
1
scope:
read at database start
auto_addvol
auto_addvol volname_prefix size volpath
This parameter enables the automatic addvol feature. It also allows you to specify the prefix string for the volume name, locations of the new volumes as well as their size.
Parameters volname_prefix
The prefix string for volume names. The complete volume name is generated dynamically by appending a unique constant (typically the new volume ID) to volname_prefix.
allowed values:
valid file name
default value:
Versant Server Guide 97
Server Process Parameters none
size
The size of data volume. Refer to the description of the
parameter for information regarding setting the volume size.
allowed values:
default value:
none
All new volumes that are added will be of this size. To change the volume size(s) of new volumes when they are added, modify this profile parameter and restart the database.
98
volpath
Actual location/directory of data volume. All the new volumes will be placed here. Versant does not check if this location has sufficient space before adding the new volume. It is the responsibility of the DBA to make sure that this path has sufficient disk space to hold the volumes.
allowed values:
valid path name
default value:
none
• If this path needs to be changed, then you have to modify the profile and restart the database.
• On Linux, the volpath directory should be owned by the DBA.
• The automatic add volume feature is currently not supported on databases that require the
DBA to provide a password for access.
scope:
Versant Server Guide
Server Process Parameters read at database start
auto_addvol_threshold
auto_addvol_threshold
value
This parameter specifies when an add volume operation should be triggered by the server. The value may be expressed as an absolute size or as a percentage. An absolute value would trigger an addvol call when the database has the specified value of space free. A percentage value will trigger an addvol call when the database has the specified percentage of free space remaining.
Specify absolute sizes using a
byte specifier . For percentage values, use the percent-sign, for example,
10%, 30%, etc. The default value is 10%.
For example, if you want to add a volume automatically when the database has 1024 Megabytes space free, you would specify 1024M or 1G as the value of this parameter. If you want add a volume automatically when the database is 30% free, you would specify 30% as the value of this parameter.
allowed values:
(absolute free space); 1% - 100% (percent free space)
default value:
10%
scope:
read at database start
Specifying a number meaning percentage full is now obsolete. Any existing profiles with such a value must be updated with a value in absolute size or a percentage referring to free space (and not full space).
auto_addvol_aggression
auto_addvol_aggression number
The database server periodically checks the overall used space in the database volumes and then decides whether to add a volume or not.
Versant Server Guide 99
Server Process Parameters
Free space calculation involves examination of the existing data volumes and some computation that can take some extra CPU cycles. If your data volumes get filled up gradually over time then the server need not check the used space very frequently. This parameter allows you to specify the time interval (in seconds) after which the server checks for database used space.
Default value for this parameter is 60. This should suffice for most databases.
allowed values:
1
- 100
default value:
60
scope:
configurable at runtime
Optimal Automatic Add Volume Settings
If your clients still get the Versant error 1083 - SM_E_OUT_OF_VOL_SPACE despite having enabled automatic add volume then you may need to either decrease the value of auto_addvol_aggression or increase the value of auto_addvol_threshold or both. The optimal setting really depends on the size of your database and the type of transactions that generally run on your database.
If you encounter problems with the automatic addvolume feature or need help to tune your database settings, contact Versant Support.
commit_delete
commit_delete on | off
Specify whether the physical deletion of objects should be delayed till commit. If commit_delete is disabled (the default), the physical deletion of the object is done immediately when the operation is sent to the database.
If commit_delete is enabled, a delete operation on an object will set the status of the object in the database as “marked for deletion”. The object will be physically deleted at commit. In the case of a rollback, the object will be unmarked and the original status is restored. Enabling commit_delete is only effective if logging is enabled. If logging is disabled, immediate deletion is performed regardless of the value set for commit_delete. (Refer to
100 Versant Server Guide
Server Process Parameters
Note that using commit_delete does not affect transaction isolation. Objects marked for deletion are unavailable to other sessions and are not included in the results sets of queries. Using commit_delete may be used to avoid problems in a rollback scenario where unique indexes are used.
This parameter is applicable to normal objects, i.e., non-schema objects only.
allowed values:
off
, on
default value:
off
scope:
read at database start
commit_flush
commit_flush off | on
When off (the default), all changes are flushed to the logical and physical logs and the changes can be recovered following an abnormal termination. Setting commit_flush on causes all changes, including dirty pages in memory, to be flushed to disk after each commit. This can increase the efficiency of a recovery.
allowed values:
off
, on
default value:
off
scope:
read at database start
datavol
datavol
volume_name size path
Versant Server Guide 101
Server Process Parameters
The profile file (profile.be) will contain a datavol entry for each additional data volume (other than the system volume). These are volumes added with the addvol utility or automatically added volumes. These entries are created by the add volume process and require no action from you.
The datavol parameter is relevant only to added data volumes and not to the system, physical log, or logical log volumes.
If you use makedb to create a server profile file, you can manually create one or more datavol entries for data volumes. Running createdb will create the additional storage volumes as well as the system, physical log, and logical log volumes. If you run createdb with the -i option, the volumes will also be initialized.
For more information refer to
and
Parameters volume_name
The logical name of the data volume. The length of the name is restricted to 31 characters. (This is the name given by the addvol -n parameter.)
size
The size of the data volume. (This is the value given by the addvol -s parameter.)
path
The physical name, including path, of the data volume. The path may be relative or absolute.
A relative path is relative to the database directory. (This is the value given by the addvol -p parameter.)
For absolute paths, ensure that the paths are not referred to by any other database server process profile file (profile.be) that is on the same machine on which the target database directory will be created. Failure to check this can result in severe database corruption or deleted volumes.
legacy_connector
legacy_connector 0 | 1
Legacy clients—clients based on Versant releases 9.1, 9.0 and 8.0.2—connect to the Versant Server via a legacy connector thread. (Refer to
for a list of Versant Server
102 Versant Server Guide
Server Process Parameters processes and threads.) If there are no legacy clients, you can disable the legacy connector server thread by setting this parameter to 0 (the default is 1, i.e., legacy client connections are enabled).
If the legacy connections are disabled and a pre-9.2 client attempts to connect, the client receives the error 7179 UT_LEGACY_CONNECTOR_DISABLED.
allowed values:
0
, 1
default value:
1
scope:
read at database start
locking
locking off | on
The locking parameter specifies whether short locking is enabled. If locking is off, setting of short locks is disabled. Setting locking on, the default, enables the setting of short locks.
Locking controls concurrent access to objects by different processes, providing data integrity with a small cost in performance. It is safe to turn short locking off if you are running only one application process. If multiple applications are accessing a database, locking should always be on to ensure orderly concurrent access to objects.
allowed values:
off
, on
default value:
on
scope:
read at database start
Versant Server Guide 103
Server Process Parameters
logging
logging off | on
Specifies whether logical and physical logging are enabled. Logging guarantees that a database can be restarted and accessed after a system failure. It also keeps track of the status of transactions and savepoints, and logging ensures database consistency. All recovery processes can recover from crashes that occur during recovery.
Logging must be turned on to perform transaction rollbacks and/or to use savepoints. All transaction commits are two-phase, which ensures the consistency of a committed transaction across a distributed database system.
Do not use logging without locking.
allowed values:
off
, on
default value:
on
scope:
read at database start
startup_script
startup_script script_file_name [output_logfile_name]
The startup_script parameter specifies the executable that should be launched at database startup.
The startup executable can either be a binary or a script.
Parameters script_file_name
Name of the executable. It is relative to the database directory. Specifying an absolute path is not allowed. This executable will be launched at the time of the database startup.
For security reasons, only the DBA should have write permissions to modify this file.
104 Versant Server Guide
Server Process Parameters
On Windows, the extensions .bat and .exe are the only ones considered to be valid executables.
On Linux, there is no such restriction.
output_logfile_name
An optional path to the output log file. An absolute (actual location) or relative (to the database directory) path can be used.
The startup executable starts running at database startup. The database server redirects the
STDOUT and STDERR of the startup executable to this log file. The output is always appended to the startup executable log file.
If output_logfile_name is not specified, then it will be created in the database directory and the name of this log file will be obtained by appending the script_file_name with .log extension.
For example if script_file_name is startupscript.sh, then the output of the script will be saved in the database directory in a file named startupscript.sh.log.
There could be problems executing the startup script due to the access or execute permissions.
In such cases the database startup will return with appropriate errors. After the startup executable has been launched successfully, the DBA may need to periodically check the startup executable log file for the error status, if any.
Use notes
The following needs to be kept in mind when using a startup executable.
• The executable should not use any system call or command that could create a new process.
• It should not use any commands that stop the database, for example, removedb or stopdb.
• Starting any background processes should be avoided. If a background process is started, then the user should keep track of that process(s).
• The following environment variables are available for the user within the startup executables.
• VERSANT_STARTUP_DBNAME: The name of the database. This could be used for executing any
Versant utilities that require the database name as a parameter.
• VERSANT_STARTUP_LOG: The name and path of the startup executable log file.
• Calling stopdb will not terminate the startup executable. A message Startup executable running after database down. process-id 12103 will appear in the database LOGFILE stating that the startup executable is not terminated.
Versant Server Guide 105
Server Process Parameters
• If database startup detects that a previous startup executable is active, then the database startup will fail.
Monitoring the startup executable
To know whether the startup executable is running, get the process id in either of the following ways.
1. Checking the output of dbtool -sys -info -resource <dbname>
The output of dbtool -sys -info -resource gives the process id of the startup executable if it is executing. (For more information, refer to the description of the command option
Section 10.10, “dbtool” pg. 215.)
2. Reading from LOGFILE
Whenever the startup executable is launched the process-id is written to the database LOGFILE.
Sample output would be:
PID: 5812; HOST: everest; Tue May 2 02:27:35 2006
INVOKED; /…/db/t.sh; CWD: /…/db; RUID: yphadke; EUID: yphadke;
Process:5812 Tue May 2 02:27:35 2006
Startup executable running with process-id 5906
The process id in the LOGFILE would be useful to find and track the startup executable (if required).
106 Versant Server Guide
Server Process Parameters
Example 6.1. Startup Executable Example
The following is a sample Bourne shell script that can be used as a startup executable to take a level
0 backup and start roll forward archiving.
#!/bin/sh
# take a level 0 backup and start roll-forward logging vbackup -device $VERSANT_STARTUP_DBNAME.backup -rollforward
-backup
$ VERSANT_STARTUP_DBNAME if [ $? -ne 0 ] then echo "level 0 backup failed" exit 1 fi
# start the roll-forward archiver and create files of size 2MB with auto filename generation vbackup -device $ VERSANT_STARTUP_DBNAME.roll -noprompt
-capacity 2M
-log $ VERSANT_STARTUP_DBNAME if [ $? -ne 0 ] then echo "roll forward logging failed" exit 1 fi
>exit 0
versant_be_dbalogginglevel
Specifies whether DBA utility logging is enabled. Setting this parameter to 1 (one), the default, enables DBA logging. To disable DBA utility logging set this to 0 (zero).
allowed values:
0
, 1
Versant Server Guide 107
Server Process Parameters
default value:
1
scope:
configurable at runtime
versant_be_dbaloggingfile
Specifies the name of the file used to log DBA utility activity. This file will be created if it does not exist. If it already exists, the file will not be overwritten, new logging messages will be appended to the end of the file. (For Linux, relevant OS permissions are always required to create or open a file.)
If no file is specified (the default), the per-database configurable LOGFILE in the individual database directory will be used. For more information refer to
Section 4.2.5, “Log File—LOGFILE” pg. 51.
allowed values:
valid file name
default value:
""
scope:
read at database start
versant_be_logfile
Specify the location of the per-database configurable LOGFILE. All information (database and system and error messages) is logged here.
The default value is the LOGFILE in the database directory under the database root directory. If a different file is specified in the profile.be, then that file name will be used. Note that Windows will ignore this setting and use the default value (i.e., LOGFILE).
allowed values:
valid filename
default value:
108 Versant Server Guide
Server Process Parameters none
scope:
read at database start
be_syslog_level
This parameter controls system logging for critical database operations. Setting this parameter to
1
(one), the default, enables logging. To disable logging set this to 0 (zero).
The logging is directed to the system logger on Linux (i.e., syslog()) and to the application event log on Windows. The events that are logged are starting and stopping of a database and crashes of the vserver process.
allowed values:
0
, 1
default value:
1
scope:
read at database start
6.2.5. Tuning Parameters
async_buffer_flusher_interval
async_buffer_flusher_interval number
The async_buffer_flusher_interval parameter is used to modify the behavior of the async_buffer_flusher
, and therefore requires it to be enabled.
If the this parameter is set to -1, the default, the async page buffer cleaner operates normally and is activated once the high water mark (bf_dirty_high_water_mark) is reached. Setting async_buffer_flusher_interval to a positive value specifies a time interval, in seconds, when the async page buffer cleaner will flush dirty pages. Pages are flushed until the amount specified by the low water mark (bf_dirty_low_water_mark) is reached. This is useful when flushing should be more aggressive or take place at deterministic intervals.
Versant Server Guide 109
Server Process Parameters
This parameter requires that async_buffer_flusher is enabled.
allowed values:
-1
, 1 - 32767
default value:
-1
scope:
configurable at runtime
This was previously named async_buffer_cleaner_interval. The previous name is deprecated but may still be used. Instances of the previous name are replaced by the new name whenever the server triggers a rewrite of the profile file.
async_buffer_flusher_sync
async_buffer_flusher_sync off | on
If this option is off (the default), the buffers will be flushed from the page buffer cache only, but the thread does not wait for the storage device to actually write (“sync”) the data to the physical medium.
Setting this parameter on forces the async page buffer cleaner thread to automatically sync the volumes after flushing the dirty page buffers. Enabling this option moves part of the heavy lifting to an existing asynchronous thread and reduces part of the work for checkpoints and commits.
Using this parameter may or may not improve performance depending on the kind of filesystem/hardware configuration that you are using
This parameter requires that async_buffer_flusher is enabled.
allowed values:
off
, on
default value:
off
110 Versant Server Guide
Server Process Parameters
scope:
configurable at runtime
This was previously named async_buffer_cleaner_sync. The previous name is deprecated but may still be used. Instances of the previous name are replaced by the new name whenever the server triggers a rewrite of the profile file.
bf_dirty_high_water_mark
bf_dirty_high_water_mark number
Specify, in number of pages, when an asynchronous page cleaner thread will start to flush to disk dirty pages in the buffer pool.
The default value of bf_dirty_high_water_mark is 512 pages.
Together, the high water mark and lower water mark parameters influence when the asynchronous buffer cleaner writes dirty buffer pages to disk.
Without the lower water mark concept, pages that are repeatedly set to dirty are flushed over and over again. With no gap between the high and low water marks, a page that is repeatedly set to dirty does not get flushed in time. The range in between ensures proper flushing.
Pages are flushed in priority order, and pages with a numerically lower priority are flushed first.
Root and branch pages of an index have priority 3, leaf pages of an index have priority 2, and data pages have priority 1. A time algorithm will decrement less used pages to priority 0. However, when you dirty a page, its priority is set back to its correct priority number (for example, a data page will be set to priority 1.)
The asynchronous buffer cleaner wakes up whenever the number of dirty pages in the buffer cache reaches the high water mark. When the number of dirty pages in the buffer cache reaches the high water mark, dirty pages of all priority are flushed until the number of dirty pages reaches the low water mark. The buffer cleaner then flushes all remaining dirty pages of priority 0 and then goes to sleep. Without the low water mark concept, pages that are repeatedly dirtied would otherwise get flushed over and over again, which would degrade performance. Without there being a gap between the high and low water marks, a page that is repeatedly dirtied might go for a long time without being flushed.
For example, suppose that the high water mark is 512 pages and the lower water mark is 204 pages.
When the number of dirty pages reaches 512, the buffer cleaner writes dirty pages of any priority
Versant Server Guide 111
Server Process Parameters until there are only 204 dirty pages left in the buffer cache. From that point on, only pages of priority
0 are flushed.
allowed values:
max_page_buffs
>= positive integer > bf_dirty_low_water_mark
default value:
512
scope:
configurable at runtime
bf_dirty_low_water_mark
bf_dirty_low_water_mark number
Specify, in number of pages, when an asynchronous cleanup process or thread will stop clearing the buffer pool of pages containing dirty objects.
allowed values:
positive integer < bf_dirty_high_water_mark
default value:
204
scope:
configurable at runtime
class
class number
Specify the integer number of cached user defined classes.
If not specified, the default number of cached user defined classes is 2000.
112 Versant Server Guide
Server Process Parameters
If more than the specified or default number of classes are accessed during the time a database is running, the cache gets resized automatically. For optimal performance you should set this parameter equal to or higher than the number of user defined classes.
allowed values:
positive integer (minimum 480)
default value:
2000
scope:
read at database start
db_timeout
db_timeout delay
Specify that the database is to be automatically shut down if there have been no active transactions for delay number of minutes.
By default, this parameter is set to -1 and automatic shut down is disabled.
For example, the following specifies automatic shutdown after one hour.
db_timeout 60
allowed values:
-1, positive integer
default value:
-1
scope:
configurable at runtime
Versant Server Guide 113
Server Process Parameters
index
index number
Specifies the number of cached user defined indexes.
If not specified, the default number of cached user defined indexes is 4000.
If more than the specified or default number of indexes are accessed during the time a database is running, the cache gets resized automatically. For optimal performance you should set this parameter equal to or higher than the number of user defined indexes.
allowed values:
positive integer (minimum 480)
default value:
4000
scope:
read at database start
llogvol
llogvol size name
The size and location of the logical log volume used for transaction undo-redo information for logging and recovery.
Parameters size
An optional allocation size.
The default size is 24 megabytes. The minimum size is 256K. If you specify a value smaller than the minimum, 256K will be allocated.
114 Versant Server Guide
Server Process Parameters
If the logical log volume is a file, it will be expanded if necessary. If the logical log volume is expanded beyond the stated soft limit out of necessity, it will be shrunk back after recovery has been done.
allowed values:
(minimum 256K, maximum 64G)
default value:
24M
name
Either the absolute or relative path (including name) of the logical log volume. The default is to use the name logical.log and then search for path specifications.
If you specify an absolute path, you will not be able to move the database once it has been created. The volume path can be either a file path or a raw device path. For raw devices, you must specify an absolute path.
You cannot change the name for the logical log volume once a database has been created. When a transaction commits, a commit log record is written to the logical log file and the state of the transaction is guaranteed. In the case of a system crash, the committed transaction is reconstructed by re-executing all of its actions from the log.
allowed values:
valid file name
default value:
logical.log
scope:
read at database create (createdb)
logvolmaxsize
logvolmaxsize size
Versant Server Guide 115
Server Process Parameters
Specify the maximum amount of disk space that would be available for the logical and physical log volume to grow.
This parameter will remain effective until the database is shutdown. To change the value of the parameter DBA should shutdown the database and then restart it.
Consider the following scenarios.
Scenario 1
The size of the logical log file at database startup time is already greater than the value specified for logvolmaxsize in profile.be. In such a case the size of the logical log file at startup time (which is larger than the specified logvolmaxsize parameter) will be used as the max size, and the value specified in the logvolmaxsize parameter will be ignored.
Scenario 2
If the value of logvolmaxsize is less than the size of the llog or plog volume (as specified in the llogvol/plogvol parameters) then the value of logvolmaxsize will implicitly get increased to the larger of llogvol and plogvol sizes.
Scenario 3
If a value of 0 is given for the logvolmaxsize parameter, then it is equivalent to not specifying this parameter at all in profile.be. If the DBA has set the logvolmaxsize parameter to a value that is more than the actual space available on disk, then the server may still crash if the disk itself runs out of space. Negative values are not allowed and will result in an error.
allowed values:
0
,
default value:
0
scope:
read at database start
log_direct_io
log_direct_io off | on
116 Versant Server Guide
Server Process Parameters
Use buffered or direct I/O for log file access.
The default value is off for buffered access and can only be changed by restarting the database.
Setting this parameter on enables direct I/O for accessing the logical and physical log files. The exact mechanism used differs between operating systems, but in all cases this means that reads from and writes to the logical and physical log files bypass the caches of both the operating system and the storage device. This causes all writes to be immediate, unlike the regular buffered I/O where write operations have to be flushed and synced to make sure that they reach the device.
This option requires all read and write operations to cover a multiple of the physical device's sector size. For many current HDDs this is 512 bytes, for many flash drives it is 2048 bytes. This matches with the log file page size of 2048 bytes.
allowed values:
off
, on
default value:
off
scope:
read at database start
For devices that have larger sector sizes (i.e., HDDs with native 4096 byte sectors that have no emulation layer for 512 bytes) this option will cause log reads and writes to fail.
llog_buf_size
llog_buf_size size
Specify the logical log buffer size in bytes. The larger the logical log buffer, the less frequently the system needs to flush the buffer to disk. Decreasing this parameter will save some memory but increase the frequency of disk writes. Increasing this parameter will slightly reduce the frequency of disk writes but may waste memory and cause paging. The default of eight megabytes should work well for most cases.
The logical log buffer is dynamically divided into two units. This allows use of a double buffering strategy to allow parallel execution of disk input/output and CPU execution.
Versant Server Guide 117
Server Process Parameters
allowed values:
(minimum 161K, maximum 2G)
default value:
8M
scope:
read at database start
lock_wait_timeout
lock_wait_timeout number_of_seconds
The number of seconds the server waits for a lock on an object to be released before generating an object locked error.
The default is to wait for 60 seconds.
Use the value -1 to specify waiting forever and use 0 to specify immediate return.
If a lock cannot be acquired in the specified number of seconds, the error message “2903
SM_LOCK_TIMEOUT Lock wait timed out.
” is returned.
allowed values:
-1
(infinite), 0 (immediate), positive integer (seconds)
default value:
60
scope:
configurable at runtime
max_page_buffs
max_page_buffs number_pages
Specify the maximum number of 16K pages that can be cached in the buffer cache.
118 Versant Server Guide
Server Process Parameters
This parameter strongly influences system performance. If you set it too low, the disk input/output increases. If you set it too high, the physical memory becomes exhausted and virtual memory swapping to disk takes place, which defeats the purpose of caching disk pages. If you have a large database you can sometimes increase performance by increasing this parameter. If you have a small database, you may want to decrease it to save memory.
One way of finding the optimum value for your use case is using database statistics. For more information refer to
Section 10.31, “vstats” pg. 332 and especially the statistic db_cache_hit_ratio.
allowed values:
positive integer
default value:
8192
scope:
read at database start
max_replication_throttle
max_replication_throttle -1 | 0-1000
In certain situations where the server must process large numbers of modifying transactions, it is possible that the Versant FTS re-syncing process can fall behind in propagating the transaction changes to the failed database. The max_replication_throttle parameter determines whether a throttle is placed on client transaction processing during V/FTS re-syncing. Specifying a max_replication_throttle value of -1 disables throttling (the default). Specifying an integer value in the range 0 to 1000 determines the maximum sleep time in milliseconds; 0 specifies the minimum possible sleep time. A value less than -1 will default to -1. Values greater than 1000 default to 1000.
Refer to Section 3.5.2, “Adjusting Client Transaction Performance” in the Versant FTS User's Guide for information regarding the use of this parameter.
allowed values:
-1
(disable), 0 - 1000
default value:
-1
Versant Server Guide 119
Server Process Parameters
scope:
configurable at runtime
max_sorting_memory_per_query
max_sorting_memory_per_query size
This parameter indicates the maximum size to which the sorting memory for each query can grow.
The amount of memory can is specified with a
If max_sorting_memory_per_query is specified, then there will be no limit for total memory used for sorting. But an individual query cannot use more than the size specified for sorting memory.
If the memory used for sorting a particular query exceeds the size of memory specified by max_sorting_memory_per_query in profile.be, the error QRY_SORT_MEMORY_EXCEEDED_QUERY_MAX is returned and the query will be aborted.
The following example limits sorting memory per query to 5 megabytes.
# The maximum size to which the sorting memory for each thread can grow max_sorting_memory_per_query 5M
allowed values:
default value:
0
(no limit)
scope:
read at database start
max_sorting_memory_total
max_sorting_memory_total size
120 Versant Server Guide
Server Process Parameters
This parameter indicates the maximum size to which the sorting memory areas of all on-going queries put together can grow. The amount of memory is specified as a
If the max_sorting_memory_total is specified, there will be no limit for individual query. But the total memory consumed for sorting cannot exceed the size specified.
If the total memory used for sorting exceeds the size specified by the parameter max_sorting_memory_total in profile.be, the query that is trying to allocate memory for sorting will be aborted and the error QRY_SORT_MEMORY_EXCEEDED_TOTAL_MAX will be returned.
The following example limits the total memory used for sorting to 10 megabytes.
# The maximum size to which the sorting memory areas of all threads put together can grow max_sorting_memory_total 10M
allowed values:
default value:
0
(no limit)
scope:
read at database start
plogvol
plogvol size name
The size and location of the physical log volume used for physical data information related to logging and recovery.
Versant Server Guide 121
Server Process Parameters
Parameters size
An optional allocation size. The default is 24 megabytes. The minimum size is 256 kilobytes. If you specify a value smaller than the minimum, 256K will be allocated.
If the physical log volume is a file, it will be expanded if necessary. If the physical log volume is expanded beyond the stated soft limit, it will be shrunk back when a checkpoint occurs.
It is recommended that the size for plogvol is at least as large as the llogvol in order to ensure optimum performance.
allowed values:
(minimum 256K, maximum 64G)
default value:
24M
name
Either the absolute or relative path (including name) of the physical log volume. The default name is to use physical.log and then search for path specifications.
If you specify an absolute path, you will not be able to move the database once it has been created.
The volume path can be either a file path or a raw device path. For raw devices, you must specify an absolute path.
You cannot change the name for the physical log volume once a database has been created. If logging is ON, the physical log file should be at least twice the size of the largest object. A guideline for setting the minimum size of plogvol is: guideline = 2 * (max_o_size + 1K) + 32K
In the above formula, substitute the size in bytes of the largest object in the database for max_o_size
.
allowed values:
122 Versant Server Guide
Server Process Parameters valid file name
default value:
logical.log
scope:
read at database create (createdb)
plog_buf_size
plog_buf_size size
Specify the physical log buffer size in bytes.
The larger the physical log buffer, the less frequently the system needs to flush the buffer to disk.
The default is eight megabytes which should work well for most cases. Decreasing this parameter will save some memory but increase the frequency of disk writes. Increasing this parameter will slightly reduce the frequency of disk writes but may waste memory and cause paging.
The physical log buffer is dynamically divided into two units. This allows use of a double buffering strategy to allow parallel execution of disk input/output and CPU execution.
allowed values:
(minimum 161K, maximum 2G)
default value:
8M
scope:
configurable at runtime
polling_optimize
polling_optimize off | on
Set Versant FTS recovery strategy.
Versant Server Guide 123
Server Process Parameters
The default is off, which prevents applications from getting polling induced deadlock errors. The
Versant FTS polling process, when resynchronizing the replica pair after a failure, applies changes one object at a time. Each object is first locked, then the update is applied, and then the lock is released. This prevents polling induced deadlock.
However, the default technique of applying changes one at a time is inefficient. With polling_optimize on, objects are group read, then changed, then released. This greatly improves performance. However, this might cause a polling induced deadlock error. If polling_optimize is set, applications should be written to handle deadlock errors.
allowed values:
off
, on
default value:
off
scope:
read at database start
schema_evol_timeout
schema_evol_timeout number_of_seconds
The number of seconds a schema evolution will wait for other active transactions to commit/rollback.
The default is to wait for 30 seconds.
Use the value -1 to specify waiting forever and use 0 to specify immediate return (non-blocking).
If a schema evolution could not proceed because the active transactions did not commit/rollback within the timeout period, the error “6083, SCH_CANT_MODIFY_CLASS Cannot modify schema for class $(class) because there are other active clients that may be using it
” is returned.
For more information on how schema evolution is synchronized, refer to Section 5.7, “Schema
Evolution Synchronization” in the Versant C++ Programmer's Guide .
allowed values:
-1
(infinite), 0 (immediate), positive integer (seconds)
124 Versant Server Guide
Server Process Parameters
default value:
no
scope:
configurable at runtime
schema_read_timeout
schema_read_timeout number_of_seconds
The number of seconds a schema read should wait when there is a schema evolution taking place or about to take place.
The default is to wait for 60 seconds.
Use the value -1 to specify waiting forever and use 0 to specify immediate return (non-blocking).
A schema read can happen implicitly or explicitly from a user transaction. An implicit schema read can happen when an object is retrieved from the database server whereas an explicit schema read can happen when a class schema is read from the application e.g., with the locateclass API.
Sometimes an implicit schema read can also take place during a begin transaction. If a schema read could not proceed because at least one other transaction was evolving or waiting to evolve a schema, one of the errors is returned to the application.
“6084 SCH_CANT_BEGIN_TR Cannot begin transaction because there is at least one active transaction modifying the database schema
”
“6085 SCH_CANT_READ_CLASS Could not read the schema for class $(class) (timeout occurred).
Another transaction is probably evolving the schema.
”
For more information on how schema evolution is synchronized, refer to Section 5.7, “Schema
Evolution Synchronization” in the Versant C++ Programmer's Guide .
allowed values:
-1
(infinite), 0 (immediate), positive integer (seconds)
default value:
no
scope:
Versant Server Guide 125
Server Process Parameters configurable at runtime
spin_count
spin_count number
The Versant Server uses spin locks to protect access to certain critical sections. The spin lock is implemented using a busy wait loop for a certain number of iterations, after which the threads sleep for a while before trying again. The ideal value for these iterations or “count” depends on the number of requests for the critical section/thread scheduling/processor architecture.
The spin count parameter allows you to adjust this count to the best suited value for your server.
The default value is 2000 and the minimum allowed value is 1. Keeping the value too low will put the contending threads to sleep too soon and keeping it too high might waste unnecessary CPU cycles.
Determining the optimal spin count for your server can be complicated. For this purpose the statistic db_spinlock_misses has been provided. This statistic gets updated every time a thread goes to sleep after a busy wait loop in the spin lock. Ideally, this statistic should be zero but if you see it increasing on your production system you might want to increase the spin count and re-monitor this statistic.
This will help you achieve the ideal spin count.
allowed values:
positive integer (minimum 1)
default value:
2000
scope:
configurable at runtime
transaction
transaction number
The maximum number of concurrent transactions allowed for this database. The default value is
200. If more than the specified number of transactions are used during the time a database is running, you will get an error.
126 Versant Server Guide
Server Process Parameters
allowed values:
positive integher
default value:
200
scope:
read at database start
user
user number
Specify the initial size of the named users list and use as a hint during the database startup phase.
The default initial size is 20. For very small databases this might be reduced. If there are more users then the size will be automatically adjusted.
The user list can be viewed with the command dbuser -list.
allowed values:
positive integer (minimum 8)
default value:
20
scope:
read at database start
volume
volume number
Specify the integer number of cached data volumes.
If not specified, the default number of cached data volumes is 64.
If more than the specified number of data volumes are used, the size is automatically adjusted.
Versant Server Guide 127
Server Process Parameters
allowed values:
positive integer (minimum 16)
default value:
64
scope:
read at database start
6.2.6. Heap Memory Parameters
The following parameters relate to heap memory management. These should generally be used under the direction of Versant support. Improper settings can negatively affect performance or may even make the database unstartable.
heap_size
(database)
heap_size size
A pre-allocation hint for the initial size of the server process heap in shared memory. The total heap memory is regarded as a pool from which the arenas grab their memory segments.
Indicate kilobytes with a K. If you do not specify a value, Versant will determine a value.
The server process heap is memory from which internal data structures and server process buffers are allocated, and its size sets a limit on the maximum size of regular object instances.
If you know that a server process will require a lot of memory, you can increase this parameter in order to preallocate space.
If more memory than the initial amount specified by this parameter is needed, the heap size will be dynamically increased as needed. If heap_size is too large, you may not be able to allocate shared memory when the database is started.
See also,
allowed values:
128 Versant Server Guide
Server Process Parameters
default value:
0
(value determined by Versant)
scope:
read at database start
heap_arena_size
heap_arena_size size
A pre-allocation hint for the initial size of an arena in the heap. For example, heap_arena_size 2M
Arenas are regions within the heap that facilitate concurrent access to the heap manager. A database startup results in the creation of one arena. More arenas are dynamically allocated at run-time if the database server detects a bottleneck with the existing arena(s). This parameter controls the initial size that is allocated to the arena region whenever it is created. The default is 128 kilobytes.
allowed values:
default value:
128K
scope:
read at database start
heap_size_increment
(database)
heap_size_increment size
Set the size by which the server heap will be expanded as needed.
The default increment is two megabytes.
Also refer to,
Versant Server Guide 129
Server Process Parameters
allowed values:
default value:
2M
scope:
read at database start
heap_arena_size_increment
heap_arena_size_increment size
Set the size by which an arena will be expanded as needed. For example, heap_arena_size_increment 1M
allowed values:
default value:
64K
scope:
read at database start
heap_max_arenas
heap_max_arenas n
Specify the maximum number of heap arenas. The default value, -1, allows an unlimited number of arenas.
allowed values:
-1
, positive integer
130 Versant Server Guide
Server Process Parameters
default value:
-1
scope:
read at database start
heap_multi_region
heap_multi_region off | on
This parameter is used to enable/disable the multi region heap feature.
This is on by default
This parameter applies to Windows operating systems only. On Linux operating systems, use of this parameter is invalid and is considered an error.
The multi region heap feature allows Versant to split its server heap across multiple regions in the virtual address space of the process.
This has the following advantages.
• It avoids memory conflicts with DLL’s that get loaded into the virtual address space of the server process
• It allows for the creation of a much larger heap than what was possible earlier
• The multi region heap feature is scalable when 3GB large memory addressing is configured on the system.
For more details on 3GB configuration, refer to Microsoft help and support resources.
allowed values:
off
, on
default value:
on
scope:
Versant Server Guide 131
Server Process Parameters read at database start
heap_arena_trim_threshold
heap_arena_trim_threshold size
This determines the minimum amount of memory to keep in an arena. Memory over this value that is not used is released back to the common pool. Memory returned to the common pool can be given to other arenas. For example, heap_arena_trim_threshold 3M
The default value is 2M.
The advantage of trimming is that it can keep the arena footprint low and can possibly avoid bloated arenas in situations where large memory allocations may happen only infrequently and for a short amounts of time. Without trimming, these large allocations of memory are kept for the lifetime of the arena. However, keeping this value relatively low can impact performance as the heap manager will try to trim more often thereby resulting in longer execution times.
allowed values:
default value:
2M
scope:
read at database start
heap_arena_segment_merging
heap_arena_segment_merging off | on
This parameter controls whether segments should be traversed (and possibly merged) or not. This is on by default. An arena consists of a list of segments and each segment is a block of contiguous memory. Keeping segment merging on can allow space within existing segments to be reused more effectively thereby reducing fragmentation. There may, however, be an adverse affect on execution times.
132 Versant Server Guide
Server Process Parameters
allowed values:
off
, on
default value:
on
scope:
read at database start
6.2.7. Statistical Parameters
stat
stat [ stat_name ] off | on
Turn collection of the named connection and/or database statistics on or off for this database. The stat_name parameter must be provided. Statistics collection continues until explicitly stopped using vstats
(or an appropriate API method if provided by your Versant SDK).
By default, statistics collection is off. You can use the stat parameter to turn on or off individual named statistics or turn off all statistics collection by specifying all for stat_name.
The names of connection statistics have the prefix be_. The names of database statistics have the prefix db_. You cannot use stat to collect function, application, or session statistics. (For a list of statistic names, use the vstats -summary command or refer to
Section 10.31, “vstats” pg. 332.)
You can create multiple stat entries in the server process profile to specify the statistics collection behavior that you want.
Collection of database statistics begins when the database is started. Collection of connection statistics begins with the database connection.
Statistics are stored in memory where they may be viewed with the vstats utility. (Depending on your Versant SDK, you may be able to read the statistics within your appplication.)
When using database replication, statistics collection tools and mechanisms operate only on the named databases and not on replica databases. To collect statistics for a replica database, you must apply statistics collection mechanisms specifically to the replica database.
Versant Server Guide 133
Server Process Parameters
For more information on statistics collection, refer to
Section 10.31, “vstats” pg. 332 and your Versant
SDK documentation.
assertion_level
assertion_level number
Type of assertion.
You can set this parameter to levels between 0 and 3.
If set to 0 (the default), the system performs only simple assertions. The higher the level, the more expensive the checking.
Assertion level 3 is the debug assertion level which generates a great deal of output and therefore should be avoided unless troubleshooting or when specifically directed by Versant support to do so.
allowed values:
0
- 3
default value:
0
scope:
configurable at runtime
6.2.8. Query Monitoring Parameter
query_debug_level number
You can create a query plan for the server. This reports information about queries used, results, indexes, etc. The information is written to a file named console.txt in the appropriate database directory.
The following is a brief list of the type of information reported for a given monitor level. Higher levels include the lower-level information.
1 Query or Cursor condition
134 Versant Server Guide
Server Process Parameters
5
9
Type of scan: sequential, b-tree, or hash
Index(es) used by the query
Index evaluation
allowed values:
0
- 9
default value:
0
scope:
configurable at runtime
A sample output using monitor level 9 (query_debug_level=9).
[30] -------------------- 2011-07-19 16:33:41 --------------------
FROM: PtAddress
WHERE: PtAddress::state == "Berlin" AND PtAddress::city LIKE "*den" AND PtAddress::street
LIKE "P*"
Use Index: StateCityStreetIdx
Using btree cursor on class PtAddress boundaries: >= { Berlin } && <= { Berlin } number of scanned candidates : 64 number of mismatches on key data : 62 number of mismatches on record data: 0 number of successful matches : 2
[30] -------------------- 2011-07-19 16:33:41 --------------------
FROM: PtAddress
WHERE: PtAddress::state == "Berlin" AND PtAddress::street LIKE "P*"
Use Index: StateCityStreetIdx
Using btree cursor on class PtAddress boundaries: >= { Berlin } && <= { Berlin } number of scanned candidates : 64 number of mismatches on key data : 56 number of mismatches on record data: 0 number of successful matches : 8
[30] -------------------- 2011-07-19 16:33:41 --------------------
FROM: PtAddress
Versant Server Guide 135
Server Process Parameters
WHERE: PtAddress::state == "Berlin" AND PtAddress::street LIKE "P*"
Index Evaluation of StateCityStreetIdx: 50
Index Evaluation of StateStreetIdx: 540
Choose Index: StateStreetIdx
Reordered OR-term: PtAddress::state == "Berlin" AND PtAddress::street LIKE "P*"
Using btree cursor on class PtAddress boundaries: >= { Berlin, P } && <= { Berlin, Q } number of scanned candidates : 9 number of mismatches on key data : 1 number of mismatches on record data: 0 number of successful matches : 8
[32] -------------------- 2011-07-19 16:33:42 --------------------
FROM: PtAddress
WHERE: EXISTS( a in PtAddress::phoneNumbers ; ==( a ; 123 ) )
Using sequential cursor on class PtAddress number of scanned candidates : 100000 number of mismatches on record data: 99997 number of successful matches : 3
6.2.9. Tracing Parameters
trace_comps
trace_comps options
Database server components to be traced.
The options parameter can contain one or all of the following elements. If multiple elements are specified, the list must be delimited by commas with no spaces.
Element
am at bf
Description
Trace the current state of queries or cursors.
Trace entries created, updated, and deleted in the internal AT table.
Trace the buffer manager.
Element
tr net sl
Description
Trace transaction operations
Trace the network layer
Trace the system layer
136 Versant Server Guide
Server Process Parameters sd si sm hs io lg
Element
bt dr ps rc
Description
Trace the B-tree manager
Trace the file directory
Trace the Hash-Indexing module
Trace the I/O module
Trace logging and recovery.
Element
vsl ut om qry lk
Trace process/thread operations.
rcv
Trace object creation, modification, and deletion.
csr
Trace the system segments
Trace the storage manager interface
Trace the storage manager ev api rpc
scope:
read at database start
trace_entries
Description
Trace the Virtual System layer
Trace utilities
Trace the object manager
Trace the query APIs
Trace the lock manager
Trace the recovery manager
Trace the cursor APIs
Trace the Event Notification
Trace the Kernel APIs
Trace RPCs trace_entries number
Number of trace entries to be maintained in the trace log file.
The default is 100000 entries. When the specified number of entries is reached, older entries drop off as new entries are added.
The maximum number of trace log file entries is limited and platform specific. The following table shows the maximum number of entries for the supported platforms.
Windows
Linux
32-bit
8386560
8380416
64-bit
33551360
33546240
Entering a value larger than the maximum results in the maximum value indicated for the appropriate platform being used.
allowed values:
Versant Server Guide 137
Server Process Parameters positive integer (refer to table, above)
default value:
100000
scope:
configurable at runtime
trace_file
trace_file name
Name of the trace log file.
By default, the trace log file is created in the database directory. On Linux the default name of the trace log file is .systrace. On Windows the default name of the trace file log is systrace.
If the entry begins with a forward / (Linux) or a backwards slash \ (Windows) the name parameter is treated as the full path, including the file name. Otherwise, the name parameter is assumed to be just the file name, and the file will be created in the database directory.
For more information, refer to
.
allowed values:
valid file name
default value:
systrace
scope:
read at database start
6.2.10. BlackBox Parameters
Versant blackbox tracing parameters are explained below.
138 Versant Server Guide
Server Process Parameters
blackbox_trace_entries
blackbox_trace_entries number
Specifies the maximum number of entries in the BlackBox. The default value is 100000.
allowed values:
0
, positive integer (minimum 1000)
default value:
100000
scope:
read at database start
blackbox_trace_comps
blackbox_trace_comps options
Specifies the database server components that are traced with the BlackBox.
The options parameter can contain one or all of the following elements. If multiple elements are specified, the list must be delimited by commas without any spaces.
Element
all rpc llg om pf pm
Description
All available BlackBox trace components
RPC messages
Logical logging
Object modification
Page flushes
Page modification
The BlackBox will be started implicitly during database start up and recording of the specified components will be started. By default no components are specified and the BlackBox recording has to be started explicitly with the vbbadmin tool.
Versant Server Guide 139
Server Process Parameters
scope:
read at database start
6.2.11. Event Notification Parameters
Versant JPA
The event notification parameters described in this section are not used by Versant JPA.
event_daemon
event_daemon code_path [parameters]
The full path name and optional parameters for code that will start an event delivery daemon.
You must separately write this code, which is operating system specific. This code must be on the same machine as the database.
When a database invokes the executable at code_path, it inserts the database name as the first parameter and then follows it with your parameters. If you wish to use multiple parameters, you must enclose them in double quotes and then parse the parameters yourself.
The default entry, event_daemon MANUAL, means that no event daemon will be started when the database starts. You must manually start an event delivery daemon after the database starts.
allowed values:
(application specific)
default value:
MANUAL
scope:
read at database start
140 Versant Server Guide
Server Process Parameters
event_daemon_notification
event_daemon_notification off | on
Set the type of notification strategy when the event daemon is down. If set to off, the default, errors are written to the database LOGFILE but do not abort the commit. If on, abort the commit and throw the error to the client in addition to writing the error to the database LOGFILE.
For more information, refer to Chapter 16, Event Notification in the Versant C++ Programmer's Guide .
allowed values:
off
, on
default value:
off
scope:
configurable at runtime
event_msg_mode
event_msg_mode persistent | transient
Specify the persistence of generated events when using event notification features.
Event notification modes persistent
Store generated events in the database.
transient
Keep generated events in the memory. This is the default mode.
allowed values:
persistent
, transient
Versant Server Guide 141
Server Process Parameters
default value:
transient
scope:
read at database start
event_msg_transient_queue_size
event_msg_transient_queue_size size
The maximum number of per-transaction event messages that can be held in the transient event queue.
The default transient event message queue size is 20480 bytes. You can set it to any value between
0 and 2
32
, non-inclusive.
The persistent event message queue size is 232, and it cannot be changed.
Versant does not use the operating system message queue.
On Linux, the event message size is unlimited.
allowed values:
1
- 4294967295
default value:
20480
scope:
read at database start
event_registration_mode
event_registration_mode persistent | transient | old_transient
Specify the persistence of registrations when using event notification features.
142 Versant Server Guide
Server Process Parameters
Event registration modes persistent
Store registrations in the database.
transient
Keep registrations in the memory.
old_transient
Maintain backward compatibility with applications using Versant releases prior to 6.0.5.0
This is the default mode.
allowed values:
persistent
, transient, old_transient
default value:
transient
scope:
read at database start
6.2.12. Database Space Parameters
Versant parameters to determine disk free space reporting.
out_of_space_warning_threshold
out_of_space_warning_threshold
percent
This threshold triggers the generation of system messages when the database volume space for a specific class reaches this threshold limit. The default value for this parameter is 90, i.e., if the database volume space is 90% full. Thereafter the system will log system messages into the file at every user-specified increment until the database volume space is exhausted. The space is measured in terms of extents.
Versant Server Guide 143
Server Process Parameters
allowed values:
1
- 100 (percent)
default value:
90
scope:
read at database start
out_of_space_warning_threshold_increment
out_of_space_warning_threshold_increment
percentage
This parameter indicates the increment at which a warning message should be logged into the per-database configurable LOGFILE. This parameter is defined in terms of percentage and has a valid range from 1 to 100. The space is measured in terms of extents.
For more information refer to
allowed values:
1
- 100 (percent)
default value:
5
scope:
read at database start
144 Versant Server Guide
Online Database Configuration
6.3. Online Database Configuration
Online database configuration is a feature that allows you to reconfigure certain components of the
Versant server without shutting it down. This is ideal for high availability environments where, a certain tuning is desired without any downtime.
Each component can be tuned through one or more configuration parameters. For example, the database buffer cache can be configured through parameters such as max_page_buffs (which configures the buffer cache size), bf_dirty_high_water_mark (which controls the page flushing behaviour) etc. These parameters
Each parameter has three kinds of values:
• a factory default—which is the default value compiled into the Versant kernel
• a next startup value—which is the value that will take effect on the next database startup
• a current value—which is the value currently in use by the Versant server
Using the online database configuration tool you can,
• configure the next startup value (this will write the parameter in the backend profile)
• configure only the current value, which will affect only the current running instance of the Versant server (this is called online tuning)
On a restart of the database, the values will default to the next startup value or the factory default. If you want the changed value to persist across restarts, you will also need to change the startup value.
Online tuning is not available for all the configuration parameters. Each configuration parameter has a property which identifies whether it is tunable online or not. To get a list of all the configuration parameters, run the following command. The last column displays whether online tuning is available for a parameter or not.
dbtool –config –get <dbname>
The current value in use could be the factory default or, a startup value specified in the server process profile or, an explicit runtime value set by the DBA.
A configuration parameter can be reconfigured using the following command
Versant Server Guide 145
Online Database Configuration dbtool -config -set -name <name> -value <value> -type <current|startup>
The name can be one of the names returned by dbtool –config –get. The value can be either numeric or string type. You can change the runtime value and the startup value by using the types “current” and
“startup” respectively. If you specify a string value with whitespaces then the whole string should be quoted in double quotes.
Example: dbtool -config -set -name llogvol -value "48M logical.log" -type startup <dbname>
You can also specify a remote database using the syntax dbname@node.
146 Versant Server Guide
Operating System Parameters
6.4. Operating System Parameters
The operating system parameters help prevent connections of unexpectedly terminated clients from being alive for hours. Versant relies on TCP/IP keep-alive mechanism to see if a TCP/IP socket connection is still intact or not.
6.4.1. TCP/IP Keep Alive Parameters
With the TCP/IP keep-alive mechanism, an obe server thread is created for every session. It uses a dedicated TCP/IP socket connection to communicate. The Server terminates an obe thread as soon as its socket connection is closed.
Normally a socket connection is closed when the session which created the connection calls endSession().
In the case that no calls to endSession() are executed, the TCP/IP keep alive mechanism terminates the connection assuming that the client session has died.
Depending on your TCP/IP keep-alive setting, it can take up to several hours (default being approximately
2 hours) for the TCP/IP keep-alive mechanism to close an inactive connection.
This is the reason why when a client session is terminated without the opportunity to call endsession(), the corresponding obe server thread continues to exist and potentially block resources until the TCP/IP keep-alive period is completed. The server obe thread does not terminate as soon as the client session is killed.
To solve the problem, you can do the following:
1. Make sure that sessions always call endSession() before terminating. (But endSession() will not be called in the case of abnormal termination of the session.)
2. Change the TCP/IP keep alive settings accordingly.
The TCP/IP keep-alive settings are platform dependent. Refer to your operating system documentation for information on setting them. Below is a sample of the typical settings and their description when using LINUX.
tcp_keepalive_intvl
The number of seconds between TCP keep-alive probes. The default value is 75 seconds.
Versant Server Guide 147
Operating System Parameters
tcp_keepalive_probes
The maximum number of TCP keep-alive probes to be sent before giving up and killing the connection if no response is obtained from the other end. The default value is 9.
tcp_keepalive_time
The number of seconds a connection needs to be idle before TCP begins sending out keep-alive probes. The probes are only sent when the SO_KEEPALIVE socket option is enabled. The default value is 7200 seconds (2 hours). An idle connection is terminated after approximately an additional 11 minutes (9 probes an interval of 75 seconds apart) when keep-alive is enabled.
148 Versant Server Guide
Chapter 7. Configuration Parameters
Sections
• Resolving the Configuration Parameters—Search Order
• Configuration Parameters Reference
- Using Versant Server Behind a Firewall
• Database Server System Parameter—Linux Only
The Versant configuration parameters define your Versant environment. Both the client and server use these parameters to locate the files and databases that make up your particular installation. All of the necessary parameters are set for you when you install Versant. However, in certain circumstances you may need to modify one or more parameters. This may be necessary if, for example, you did not let the installation do the configuring for you, you later move your databases or other Versant files, you want to use multiple Versant installations on the same machine, etc.
This chapter introduces the configuration parameters and describes how they are set for various situations.
In addition to the configuration mechanism and parameters described here, Versant also uses profile
files to define aspects of the Versant environment. Refer to
Chapter 6, Database Profiles pg. 73 for
information about these additional profiles.
Versant Server Guide 149
Background Information
7.1. Background Information
Installing Versant involves:
Run the Versant installation
Refer to the Versant Installation and Deployment Guide for further information.
Setting the following configuration parameters
• VERSANT_ROOT, which specifies the software root directory
• VERSANT_DBID_NODE, which specifies the machine that contains the osc-dbid file
• VERSANT_DBID, which specifies the directory that contains the osc-dbid file
• VERSANT_DB, which specifies the database root directory
The Versant installation creates two configuration files, the machine configuration file,
/etc/.osc090300
(Linux) or %HOMEDRIVE%%HOMEPATH%\vr090300.ini (Windows), and the system
information file, VersantInstallation/lib/sysinfo. The installation program sets the configuration parameters for you in the machine configuration file and in the system information file. After installation, these are the two files that define the Versant environment. The only additional environmental change made during installation is to place the VersantInstallation/bin directory in your path.
On Linux, Versant does not depend on environment variables, although they optionally can be used to define the Versant environment.
Besides these Versant parameters, you should also add the Versant executables directory to your machine's existing PATH environment variable.
Altering the TCP/IP configuration file
Altering the TCP/IP configuration files to point to the server connection program in the Versant
/bin directory for the release being installed. After installing Versant, you need to modify the TCP/IP configuration files manually. You will need to update the /etc/services and /etc/inetd.conf files to point to the server connection program ss.d in the ../bin directory of the new release. Doing this, however, does not stop you from using a previous installation of Versant.
150 Versant Server Guide
Background Information
Converting existing databases
Converting any existing databases to be compatible with the installed release. In order to use new features provided with a new Versant release, all databases must be converted to the current release using the convertdb utility provided in the new release.
Deleting previous installations
Deleting any previous installations of Versant software (but not the existing databases). This must be done manually, although you should not delete the previous installation if you do not convert all of the existing databases to the new release.
Once you have installed the new version of Versant, when an application client process requests a database connection, the following happens:
1. The connection request is sent to the TCP/IP inetd daemon on the machine on which the database resides, which forwards the request to the server connection program specified in its configuration files.
2. The server connection program starts and looks for values for VERSANT_ROOT, VERSANT_DB,
VERSANT_DBID_NODE
, and VERSANT_DBID. The ss daemon will search in the following order: a. Environment variables b. User configuration file c. Machine configuration file d. System information file
If the required information is not found in the environment variables or in a user configuration file, then the server connection program will use the machine configuration file associated with its own release number. However, if you have asserted a release number, then the machine configuration file associated with the asserted release number will be used.
3. The server connection program starts a database server process associated with the Versant configuration that it has found.
In general, client applications compiled with a lower release number can connect to database servers of a higher release number, but client applications cannot connect to a server of a lower release number.
Versant Server Guide 151
Location and Procedures
7.2. Location and Procedures
The Versant configuration is very flexible. In most cases, a given parameter may be defined for a particular scope—a process, a machine, a user or for the system. For each scope the parameter is defined in a specific location. The parameter value associated with the scope is determined, or resolved, based on the priority given to these locations.
Configuration parameters are specified for a given scope in one or more of the following locations. The associated scope is determined based on the resolution rules described in
Configuration Parameters—Search Order” pg. 154.
Environment variables
On a per process basis, you can specify paths with environment variables. Both client and server processes will look for environment variables.
To set a configuration parameter in an environment variable, use the name of the environment parameter followed by its value. For example, suppose you want to set the local database root directory in the Linux environment to be the default location then:
VERSANT_DB /opt/versant/db
If you use C Shell, to set VERSANT_DB in the .login file in the home directory: setenv VERSANT_DB /opt/versant/db
If you use Bourne shell, to set VERSANT_DB in the .profile file in the home directory:
VERSANT_DB = /opt/versant/db export VERSANT_DB
Machine configuration file
On a per machine basis, you can use or modify the machine configuration file created by Versant during installation. Both client and server processes will look for a machine configuration file.
The directory and name of the machine configuration file are /etc/.osc090300. In the Versant machine configuration file, you can create or modify a line for an environment parameter.
152 Versant Server Guide
Location and Procedures
The format for lines in the machine configuration file is the name of the environment parameter followed by the value.
For example, to set the local database root directory on a Linux environment to be the default location, create or modify the following line in /etc/.osc090300.
VERSANT_DB /opt/versant/db
You can make comments in the machine configuration file with the # sign. Anything following the
# sign to the end of the line is a comment.
For example, for local machine mymachine, software root path /opt/versant/9, and database root path /opt/versant/db, the contents of /etc/.osc090300 could be as follows.
VERSANT_ROOT /opt/versant/9 #software root
VERSANT_DB /opt/versant/db #database root
System information file
On a per installation basis, you can use or modify the system information file created by Versant during installation. Both client and server processes will look for a system information file.
The directory and name of the system information file is VersantInstallation/lib/sysinfo, e.g.,
/opt/versant/9/lib/sysinfo
.
To set an environment parameter in the Versant sysinfo file, use the name of the environment parameter followed by its value. For example, to set the local database root directory on Linux to be the default location, create or modify the following line.
VERSANT_DB /opt/versant/db
You should not set the location of VERSANT_ROOTin the sysinfo file, as Versant needs to know its software directory in order to find the sysinfo file in the first place.
You can make comments in the sysinfo file on any line in which either the first column is marked with the # sign or after a # sign on a line containing an entry.
Versant Server Guide 153
Resolving the Configuration Parameters—Search Order
7.3. Resolving the Configuration Parameters—Search Order
To find the information it needs, Versant searches environment variables and information files in a predetermined, hierarchical order. If conflicting information is found in the search, the order of the search resolves the conflict: the first value found is the value that is used.
1. Environment variables — per process
2. User configuration file — per user
3. Machine configuration file — per machine
4. System information file — per installation
Since Versant searches in the above hierarchical order, you can supply most information on a per process, per user, per machine, or per installation basis.
For example, if you create and use local databases in the directory /opt/versant/db, then you can define the following in the machine configuration file (default location):
VERSANT_DB /opt/versant/db
If you have an application that embeds Versant and works solely with drawings stored in databases in the directory /myapplication/db, then, before starting Versant you can define the following environment variable to override the setting in the machine configuration file:
VERSANT_DB /myapplication/db
On personal computer nodes, Versant makes a similar search, although the details differ.
154 Versant Server Guide
Configuration Parameters Reference
7.4. Configuration Parameters Reference
Table 7.1. Parameter Reference
Parameter
VERSANT_ROOT
Description
Specifies the location of the Versant software root directory. This parameter is required.
Env
•
Sys
•
Cfg
•
VERSANT_DB
VERSANT_DBID
VERSANT_DBID_NODE
VERSANT_HOST_NAME
VERSANT_SERVER_PORTS
Refer to
details.
Refer to
Refer to
details.
Refer to
details.
Refer to
details.
Allows you to specify a list of port numbers, or number ranges, to use in establishing connections between the database server and application processes. Specify the numbers as a comma-separated list. Ranges are specified with a hyphen (-). Whitespace characters (spaces, tabs) are not allowed. For example,
VERSANT_SERVER_PORTS=40000,40005-40010
.
The server ports specified must be within the range 1024 to 65534, inclusive.
•
•
•
•
•
•
•
•
•
•
•
•
•
This parameter is only applicable if you are connecting client applications created with
Versant releases prior to 9.2. Refer to
Section 7.6.3, “Using Versant Server Behind a Firewall” pg. 165 for more details.
• – indicates the parameter may be set in the location
Env – a
system environment variable ; Sys – the
system information file ; Cfg – the
Versant Server Guide 155
Configuration Parameters Reference
Parameter
VERSANT_SERVICE_NAME
VERSANT_SERVICE_PORT
Description
Allows you to specify a different service name for client connections.
Refer to
Section 7.6.1, “Versant TCP/IP
Service Name” pg. 162 for more details.
Allows you to specify a different service port number for local server communication.
Env
•
•
Sys Cfg
Refer to
Section 7.6.2, “Specifying the
Service Port” pg. 165 for more details.
• – indicates the parameter may be set in the location
Env – a
system environment variable ; Sys – the
system information file ; Cfg – the
156 Versant Server Guide
Mandatory Parameters
7.5. Mandatory Parameters
The following configuration parameters are essential for Versant to run in a standard environment.
They, however, need to be explicitly set only if, for example, you did not let the installation do the configuring for you, you later move your databases or other Versant files, you create a user configuration file, etc.
When you install Versant, all configuration parameters needed are recorded in either the machine configuration file, /etc/.osc090300, or in the system information file, VersantInstallation/lib/sysinfo.
After installation, the only thing that you should do is add the Versant executables directory to your machine's existing PATH environment variable.
PATH
The parameter Path sets the Executables directory. The path is set by the installer as a part of the
Setup on Windows, however, needs to be manually set on Linux. After installation, append the location of the Versant executables directory bin to the PATH environment variable. This will enable
Versant to find the executables regardless of your current directory.
For a standard installation, the Versant executables directory will be named /bin and be located below the platform directory. For example on Linux environment the location is /opt/versant/9/bin.
If you use C Shell, the search path should be in the .login file in the home directory. To amend it to include the Versant /bin directory, use the set path command.
For example, for a default installation on Linux environment.
set path = (/opt/versant/9/bin $path)
If you use Bourne shell, the search path should be in the .profile file in the home directory.
For example, to amend it to include the Versant /bin directory for a default installation.
PATH=/opt/versant/9/bin:${PATH} export PATH
Versant Server Guide 157
Mandatory Parameters
VERSANT_ROOT
The parameter VERSANT_ROOT sets the software root directory. This is a mandatory parameter. This parameter enables Versant to find its own files, because they are placed in predetermined locations in directories built from the software root directory. On UNIX installations, the default value of
VERSANT_ROOT is /opt/versant/9.
The parameter VERSANT_ROOT can be set in any of the following locations.
• In the environment variable VERSANT_ROOT.
• In a user configuration file, user.cfg, if you also set VERSANT_CFG.
• In the machine configuration file, /etc/.osc090300 which is the default location.
The VERSANT_ROOT parameter can not be set in the system information (sysinfo) file.
The general syntax is, set VERSANT_ROOT=drive:directory
Example, set VERSANT_ROOT=c:\versant
For example, if you use C Shell and set VERSANT_ROOT in the .login file in the home directory: setenv VERSANT_ROOT /opt/versant/9
For example, if you use Bourne shell and set VERSANT_ROOT in the .profile file in the home directory:
VERSANT_ROOT=/opt/versant/9 export VERSANT_ROOT
Client-only, runtime installations need only the error message file under VERSANT_ROOT.
158 Versant Server Guide
Mandatory Parameters
If you have static linkage for the executables, the rest of the Versant installation tree (folders) need not be present.
You can see the location of your Versant installation by calling oscp –p.
VERSANT_DBID_NODE
This parameter specifies the machine location of the database system file, osc-dbid. The parameter
VERSANT_DBID_NODE is required for creating, removing or listing databases.
If your machine is not connected to a network, you can assign a null value to this parameter in order to indicate that the osc-dbid file is on the local machine.
If your machine is connected to a network but will use a local database system file, you should supply the network name of your machine as known to your TCP/IP installation.
If your machine is connected to a network and will use a remote database system file, you should supply the network name of the remote machine as known to your TCP/IP installation.
The parameter VERSANT_DBID_NODE can be set as an environment variable, in a user configuration file user.cfg (if you also set VERSANT_CFG), in the machine configuration file /etc/.osc090300 (the default location) or in the VersantInstallation/lib/sysinfo file.
The general syntax is VERSANT_DBID_NODE osc-dbid_machine.
For example, if you use C Shell and set VERSANT_DBID_NODE in your .login file in your home directory: setenv VERSANT_DBID_NODE myserver
For example, if you use Bourne shell and set VERSANT_DBID_NODE in the .profile file in your home directory:
VERSANT_DBID_NODE = myserver export VERSANT_DBID_NODE
VERSANT_DBID
The parameter VERSANT_DBID sets the local or remote directory that contains the database system file, osc-dbid. This is a mandatory parameter and is required for creating, removing or listing databases.
Versant Server Guide 159
Mandatory Parameters
Remote directories must be specified in terms appropriate to the operating system on the remote machine. This means that for personal computers you should specify directories with drive:\directory syntax and for UNIX computers you should specify directories with /directory syntax.
You may set the parameter VERSANT_DBID as an environment variable, in a user configuration file, user.cfg
(if you also set VERSANT_CFG), in the machine configuration file, /etc/.osc090300 (the default location) or in the VersantInstallation/lib/sysinfo file.
The general syntax is VERSANT_DBID path. For path, substitute the location of the software root directory in terms appropriate to the operating system of the machine that contains the osc-dbid file. For example, on a Windows machine where the osc-dbid file directory on that machine is c:\versant\db
, then the parameter will be specified as follows.
Windows
VERSANT_DBID c:\versant\db
If the machine that contains the osc-dbid file is running Linux and the osc-dbid directory is
/opt/versant/db
, specify VERSANT_DBID as follows.
Linux
VERSANT_DBID /opt/versant/db
VERSANT_DB
The parameter VERSANT_DB sets the database root directory. This is a mandatory parameter and is required for accessing, creating, or removing a database on your local machine. New databases are placed in a directory branching from the database root directory.
You may set the parameter VERSANT_DB as an environment variable, in the user configuration file, user.cfg
(if you also set VERSANT_CFG), in the machine configuration file, /etc/.osc090300 (the default location) or in the VersantInstallation/lib/sysinfo file.
The general syntax is VERSANT_DB path. For path, substitute the location of the database root directory.
For example,
VERSANT_DB c:\versant\db
160 Versant Server Guide
Mandatory Parameters
VERSANT_HOST_NAME
If the VERSANT_HOST_NAME is set, Versant uses this value instead of the actual hostname for the local machine. The VERSANT_HOST_NAME setting controls what host name is written in the osc-dbid file
(The osc-dbid file is the list of databases associated with a given database root directory. Refer to
Section 4.1.1, “Database System Identifier File (osc-dbid)” pg. 44 for information about this file.)
Setting a value for VERSANT_HOST_NAME can be of value in clustered environments.
Versant Server Guide 161
Communication Parameters
7.6. Communication Parameters
The following parameters are used to set up client/server communication.
7.6.1. Versant TCP/IP Service Name
The parameter VERSANT_SERVICE_NAME allows you to have multiple Versant releases on the same machine and connect to the servers from one or the other of these releases selectively from different clients. This is an advanced option and requires careful configuration. It is recommended that you contact Versant support for help in setting up this parameter.
In a default installation, the Versant connection service has the name oscssd and listens on port 5019.
All clients, by default, attempt to connect to the oscssd service. The service name is mapped to a port number by looking up the name in the client-side services file. Using a VERSANT_SERVICE_NAME environment variable entry, you can direct a client to use a different service name and thus the port number associated with the name. Correspondingly, you can tell different servers (different releases) to listen on the appropriate service ports.
For example, suppose you have two Versant server releases, say, 7.0.1 and 8.0.1, installed on the same machine. The following procedure demonstrates how to set up the server machine and the client machines to use a specific server release. The following describes the procedure Windows and for Linux.
Windows
1. Run the networkservices.exe program from the bin directory. You can use the networkservices.exe program from either your previous or the new Versant installation. Edit the Service Name, Service EXE Path
Name, and Service Port Number fields to specify a new service for the previous version. For Service Name, use a name other than oscssd, e.g., oscssd701. For the Service EXE Path Name field, specify the absolute path to the ss.exe file in the previous installation. For example, C:\Versant\7_0_1\bin\ss.exe. The port number can be any unused port other than 5019. Press Add to add the new, changed entry to the list.
Finally, select OK to write the changes to the services file and Windows registry.
The following figure shows the networkservices.exe program window with these changes.
162 Versant Server Guide
Communication Parameters
2. Remove the following system environment variables from the server machine (the machine with both
Versant versions installed).
VERSANT_DB
VERSANT_DBID
VERSANT_DBID_NODE
VERSANT_ROOT
3. Restart your machine after making these changes.
4. The new service port number must be used by clients accessing the previous installation. Clients which need to connect to the previous Versant version must set the environment VERSANT_SERVICE_PORT to the newly created service port.
Using the Versant Tools and Utilities
On the server machine, you will need to dynamically edit the PATH and VERSANT_SERVICE_PORT environment variables to access the new or previous Versant release to use the appropriate database tools. The PATH variable includes the Versant bin directory and VERSANT_SERVICE_PORT specifies the port number. (Refer to
Section 7.6.2, “Specifying the Service Port”
Versant Server Guide 163
Communication Parameters
Linux
1. Select a service name and port number for the previous Versant release. The name must be other than oscssd. The port number can be any unused port other than 5019. For example, oscssd701 for the service name and 5021 for the port number.
2. Edit the services file, /etc/services, to add the selected service name and port for the previous installation. (You will need root privileges for this and the steps following.) The following shows an example of the appropriate Versant services.
oscssd oscssd701
5019/tcp # 9.0 installation
5021/tcp # previous installation
3.
Linux
Create a file in the /etc/xinetd.d directory for the renamed previous service. The file name is the name of the previous service used in the services file. For example, using the service name oscssd701 from the example above, the file name is /etc/xinetd.d/oscssd701. Following is an example of the file content.
service oscssd701
{ socket_type = stream protocol wait user server disable
= tcp
= no
= root
= VersantInstallation/9/bin/ss.d
= no
}
4. Notify the inetd or xinetd process to refresh the configuration to reflect the changes made in the previous step. Use the following command to re-start the xinetd process.
/sbin/service xinetd reload
For specific information regarding refreshing the inetd or xinetd process, refer to your operating system documentation.
164 Versant Server Guide
Communication Parameters
5. The new service port number must be used by clients accessing the previous installation. Clients
which need to connect to the previous Versant version can set the environment variable
to the newly created service port.
Alternatively, edit the services file on the appropriate client machines to add the new service name and port number for the previous release. (The service names and port numbers for Versant services must match each other exactly on the client and server machines.) Set the VERSANT_SERVICE_NAME environment variable to the new service name on each client machine.
7.6.2. Specifying the Service Port
The VERSANT_SERVICE_PORT parameter specifies the port that a client machine should use to connect to a Versant server machine. This parameter is set as an environment variable on the client machine. The
VERSANT_SERVICE_PORT parameter is most often used to override the default port in order to connect to a specific Versant server release on a machine with multiple releases installed. Refer to
7.6.3. Using Versant Server Behind a Firewall
The VERSANT_SERVER_PORTS parameter allows you to work with Versant database servers on machines that are protected by a firewall. It may be set as an environment variable, in the user configuration file, in the machine configuration file or in the system information file. (Refer to
Procedures” pg. 152 for information regarding these locations and the priority order.)
You use the VERSANT_SERVER_PORTS parameter to specify the set of open port numbers in the firewall to be used when establishing connections between application processes or database utilities and the server. The list of open ports is specified as a comma-separated list of port numbers and/or ranges of port numbers as in the following example.
VERSANT_SERVER_PORTS 40000,40000-40005,40026,40030-40032
The usable open server ports must be within the range 1024 to 65534, inclusive. The list must be specified on a single line without whitespace characters (space, tab, etc.). Ranges are specified with a hyphen (-).
As of release 9.2, the Versant Server uses only a single port for communication with clients created with release 9.2 or greater. The VERSANT_SERVER_PORTS parameter is only applicable if you are connecting client applications created with Versant releases prior to 9.2.
Versant Server Guide 165
Database Server System Parameter—Linux Only
7.7. Database Server System Parameter—Linux Only
VERSANT_BE_STACK_SIZE
Stack size of the Versant server thread. Optional.
This configuration parameter controls the stack size of the threads that are created by the Versant database server process (vserver). It is expressed in terms of kilo bytes (KB) and the default size is
256. You can specify a value between 256KB and 1024 KB. If a value less than 256KB is specified then 256KB will be used and if a value greater than 1024KB is specified then 1024KB will be used.
You may set the parameter VERSANT_BE_STACK_SIZE in the machine configuration file,
/etc/.osc090300
, which is the default location.
For example, if you use C Shell and set VERSANT_BE_STACK_SIZE to 512 setenv VERSANT_BE_STACK_SIZE 512
For example, if you use Bourne shell and set VERSANT_BE_STACK_SIZE to 512
VERSANT_ROOT=512 export VERSANT_ROOT
166 Versant Server Guide
Optional Parameters—Windows
7.8. Optional Parameters—Windows
TZ
Your local time zone is needed by the Versant C++ VDate and VTime classes. This parameter is optional.
For example, for Pacific time, set TZ equal to PST8PDT.
HOSTNAME
ETC
The TCP/IP name of your local machine, which is needed by TCP/IP network software. This parameter is optional.
The TCP/IP etc directory, which is needed by TCP/IP network software. This parameter is optional.
The Versant installation program will optionally update your TCP/IP services file as appropriate for your operating environment. If you elect to update the TCP/IP services file yourself, want to examine
Versant's changes, or need to change the Versant installation, the following changes are needed for each of the personal computer operating systems supported by Versant.
In Windows, \%SYSTEMROOT%\system32\drivers\etc\services should define Versant service as: oscssd 5019/tcp
.
Versant Server Guide 167
168 Versant Server Guide
Chapter 8. Backup and Restore
Sections
- Archiving with Multiple Devices
- Restoring After a Crash with Roll Forward Enabled
Versant Server Guide 169
Overview
8.1. Overview
Data backup and restore is an essential and important need of any mission critical application.
You should ideally always plan for your data backup in event of an unavoidable system crash.
The purpose of a backup is to get the database in a consistent state. The purpose of restore is to restore the database with the backed up data.
Versant provides a very efficient and strong backup and restore mechanism.
When you create a backup and recovery strategy, depending on the importance of the data, there are many considerations and decisions to be made, for example:
1. The method of back up
2. The size of the backup device
3. The frequency and time with which the data back up
4. The trade-off between online and offline backups
5. The place of the backup, archive and other files
You can backup multiple databases to a single tape drive or to a single file.
Database backups can be online or offline
Online:
which means that a database can be backed up while it is being used. This is the default mode.
Offline:
which means the backup can be taken when the database is not in use.
Database Restores are only offline and are generally faster than the backup.
Backups can also be incremental or full.
Incremental:
which means, saving only those changes made since the last backup.
170 Versant Server Guide
Overview
Full:
which means saving the entire database.
If multiple databases are backed up with a single command, the first one will be stored in the position specified in the position parameter (see the option parameters below) and any additional ones will be appended after it.
A database backup saves the results of all transactions committed at the time vbackup is invoked.
For additional safety, you may also want to use the -rollforward option in conjunction with the -backup option. This will ensure that no log records are discarded unless they have been archived, using the vbackup option -log on a separate command prompt.
Versant Server uses the vbackup utility for backup, restore, incremental restore, roll forward archiving and info operations.
Versant Server Guide 171
Backup and Restore Methods
8.2. Backup and Restore Methods
8.2.1. vbackup
The purpose of the vbackup utility is to allow recovery, either from a device failure or from accidental deletion of data.
The vbackup utility is used for the following operations:
• Backup
• Restore
• Roll Forward vbackup does not support multi threaded applications.
Incremental Backup vbackup strategy consists of three different backup levels, level 0, 1 and 2.
As database size increases, it becomes more important to set the level in a way, which minimizes backup size and time. It usually takes less time to create a level 1 or level 2 backup compared to a level 0 (full) backup.
Level 0 performs a full backup. Level 1 backs up all changes made since the last level 0 backup. Level 2 backs all changes made since the last level 0 or level 1 backup, whichever was most recent.
Roll Forward RF archiving is another feature that preserves logical log records generated by a database during normal operation in a log archive. These records can be replayed on the database during recovery.
Thus, RF makes it possible to recover a database to its state just prior to the crash.
If you use just the backup and restore features of vbackup utility, you can recover data to the point of the last backup.
But if you want to recover the data, to the point of the last committed transaction, then use the Roll
Forward features of vbackup utility.
For information, refer to the
utility.
172 Versant Server Guide
Backup and Restore Methods
8.2.2. Roll Forward Archiving
If a severe database problem like a application crash or disk crash occurs, you can generally recover/restore your database using your last database backup. However this database backup would only be in the state it was, at the time when the last backup was taken.
This means that you will lose all database transactions, that have been committed after that backup time.
Roll Forward archiving helps to recover and to restore a damaged database to the most recent state before a failure occurred. Roll Forward archiving makes it possible to recover the database to the most recent state as it journals all database transactions.
If you want to keep a history of database states, then you probably want to use a combination of database backups plus Roll Forward archiving. In this way, you can always restore to a previous or last historical state.
If performance is an issue, then you also probably want to use Roll Forward archiving to a local tape or disk drive, because this avoids network traffic without compromising the ability to recover from a destroyed machine.
To ensure that you do not loose that data (post backup and until the restore is done), you should either use some form of Database replication or Roll Forward archiving.
Roll Forward archiving is described in detail in the next section of this chapter.
Versant Server Guide 173
Roll Forward Archiving
8.3. Roll Forward Archiving
Using just the regular backup makes it possible to restore a database to the state it was in when the backup was taken. This implies that you lose all database transactions, that have been committed after that backup time.
To ensure that you do not loose that data, you should either use some form of Database replication or
Roll Forward RF archiving (which journals all database transactions).
The Roll Forward RF archiving makes it possible to recover the database to the most recent state.
Restoring a database with rollforward archiving turned on, first does the backup recovery from the regular level 0 backup, then from the incremental (level 1 or level 2) backup and then applies all the transaction log records form the archives. At the end the current logical.log is restored. This brings the database to its most recent state.
The steps needed to perform Roll Forward archiving are:
• The last full backup
• The incremental backups
• The transaction logs post last backup
8.3.1. Roll Forward Management
To use Roll Forward, you do the following for each database on which you want to use Roll Forwarding:
• Create a level 0 backup and enable Roll Forward.
• The default setting for a newly created database is, Roll Forward not enabled. Roll Forward can only be enabled while performing a full backup (level 0, level 1, or level 2). A full backup is the prerequisite for running with Roll Forward.
• To backup a database and to turn on Roll Forward, you can use the command line vbackup utility.
Once the full backup has been completed and Roll Forward has been enabled, Versant will not delete any log records out of the logical.log file.
• Start Roll Forward archiving.
174 Versant Server Guide
Roll Forward Archiving
• After you created the full backup and enabled Roll Forward, you need to turn on Roll Forward archiving
(vbackup -log), using the command line vbackup utility. After Roll Forward archiving is turned on,
Versant will start archiving log records created since the last backup. You can simultaneously backup multiple database logs to a single tape/file, or use multiple tape drives or files up to one per database.
• Only running an instance of the archiver process ( vbackup -log) will remove the log entries out of the logical.log into an archive device (file, tape, etc.) It is absolutely important to run an archiver process (vbackup -log) at all times after rollforward is enabled, as else the logical.log will expand until it reaches its maximum size (OS dependent) upon which the database will have to shut down.
• Temporarily stop Roll Forward archiving, if desired.
• Once Roll Forward has been enabled, you can safely stop and start archiving temporarily, as long as
Roll Forwarding remains ON. As long as Roll Forwarding is ON, you are always guaranteed that no log records will be discarded until they have been archived.
• There are many reasons why you may need to suspend Roll Forward. For example, you may need to change a tape or file or use the Roll Forward tape drive to make an online backup. Or, Roll Forward may be interrupted by a tape device problem or network crash.
The following table shows the possible database states. (The vbackup command options that will move you from one state to another are shown, e.g., vbackup -off.)
Versant Server Guide 175
Roll Forward Archiving
Figure 8.1. Roll-forward Management
Refer to
Section 10.21, “vbackup ” pg. 278.
8.3.2. Roll Forward Procedure
If you need to Roll Forward, use the vbackup command line utility and first restore a level 0 backup of the database.
After you have restored from your last level 0 backup, you will be given the opportunity first to restore from any incremental backups (level 1 or level 2) and second for your Roll Forward archives and third you will use the entries in the current logical.log which did not make it to an Roll Forward archive yet.
You will not have to invoke vbackup repeatedly as all restore steps are performed in a single invocation.
176 Versant Server Guide
Typical Sequences of Events
8.4. Typical Sequences of Events
8.4.1. Archiving with One Device
If you have only one tape drive or external drive, a typical sequence of events to backup two databases at the same time is the following (the procedure would be the same for just one database db1):
• Perform a level 0 backup and enable Roll Forwarding.
For example: vbackup -level 0 -device tape1 -rollforward -backup db1 db2
After the backup, the command prompt will return. The backup does not have to be a full backup, just whatever is appropriate.
• Begin Roll Forward archiving.
For example: vbackup -device tape1 -log db1 db2
After this command, the command prompt will not return and Roll Forward archiving will continue until you end the archiving process by closing the window or pressing Enter> to exit vbackup.
• Temporarily stop Roll Forward archiving (by pressing <Enter>) to change a tape. During this time, all log records are building up in the logical.log until you start archiving again. Depending on client activities, you might not want to interrupt Roll Forward archiving for too long.
• Temporarily stop Roll Forward archiving to make an incremental backup. Again the log records will build up in the logical.log while Roll Forward archiving is stopped. Depending on client activity the temporary stop of Roll Forward archiving should not last too long.
For example: vbackup -level 1 -device tape1 -backup db1 db2
Versant Server Guide 177
Typical Sequences of Events
• Resume Roll Forward archiving.
For example: vbackup -device tape1 -log db1 db2
8.4.2. Archiving with Multiple Devices
Suppose that you have three tape drives and two databases.
In this case, a typical sequence of events for databases db1 and db2 is the following.
• Perform a level 0 backup and enable Roll Forwarding.
For example: vbackup -level 0 -device tape3 -rollforward -backup db1 db2
After the backup, the command prompt will return. The backup does not have to be a full backup, just whatever is appropriate.
• Begin Roll Forward archiving on database db1 using tape1: vbackup -device tape1 -log db1
• Open another window and begin Roll Forward archiving on database db2 using tape2: vbackup -device tape2 -log db2
• Make an online incremental backup using tape3 while Roll Forward archiving is active on both databases: vbackup -level 1 -device tape3 -backup db1 db2
178 Versant Server Guide
Typical Sequences of Events
8.4.3. Restoring After a Crash with Roll Forward Enabled
For the above examples, to restore after a crash, do the following:
• If the databases were completely demolished, first recreate the database directories and support files(.sharemem, .lock, etc.). The user who recreates the databases must be the same user who created the original databases. In this case: makedb -g db1 makedb -g db2
• Insert the level 0 backup tape and restore: vbackup -device tape3 -restore db1 db2
If additional tapes are needed for the full backup, you will be prompted for them. Also, you will be asked for incremental backups (level 1 and level 2), the Roll Forward tapes as well as the current logical.log as each step is completed.
Versant Server Guide 179
Usage Notes
8.5. Usage Notes
Following are usage rules related to Roll Forward archiving.
• To perform Backups, Roll Forward archiving, and Restores on a database, you must be the DBA user who created the database.
• You do not have to suspend Roll Forward archiving to perform an online backup if you use a device for the backup that is different from the Roll Forward device.
• If you need to spread Roll Forward archiving over several tapes or devices, the tape or device files will be marked with a sequence number. When you use the files to restore a database, the sequence number will be checked to ensure that they are applied in the proper order.
• If a database goes down, Roll Forward archiving for that database will be stopped, but Roll Forward archiving for other databases will continue unless they are writing to the same output media.
• If multiple databases are being archived to the same output media, a failure to any of the databases will cause log archiving to be stopped for all of the databases.
• If a database goes down, when it returns, you will have to restart Roll Forward archiving for that database.
• If Roll Forward archiving is stopped, either explicitly or by a process termination, and then it is restarted, nothing will be lost, and there will be no reason to do a fresh incremental backup. However, if Roll Forward archiving is stopped, you should restart the Roll Forward archiving process as soon as possible. If the database runs out of space in its log files while Roll Forward archiving is suspended, you will get an error message, and the database will shut down.
• Roll Forward archiving has no effect on the normal writing of log files to a database.
• If a database must be restored from backup and log archives, only log archives created after the latest incremental backup are utilitized.
• If you turn off Roll Forward with the -off option of vbackup, Versant will stop saving log records for archiving, and they will be discarded after a transaction ends.
180 Versant Server Guide
Chapter 9. Incremental Restore and Warm Standby
Sections
- Setting up Incremental Restore for Warm Standby
- Starting the Incremental Restore Process
- Suspending the Incremental Restore Process
- Restoring the Suspended Mode
- Resuming the Database (-resume)
- Completing the Restore Process
- Activating the Warm Standby Database
- Maintaining the Warm Standby Database Up-to-date
The incremental restore facility of vbackup strengthens the high availability capabilities of Versant.
This feature is used as an incremental rollforward recovery. It is designed to minimize the downtime in an emergency event, which requires a database recovery.
To achieve this, an up-to-date copy of the primary database needs to be maintained - this is the warm standby database. In the case of an emergency, this standby database can be updated very quickly to the state of the primary database - just by applying the last roll forward archive plus the logical.log of the primary database (rather than starting a full database restore that may take a considerable amount of time with large databases).
The purpose of incremental restore:
• Whenever the restore process requests a new rollforward archive file, the restore process can be interrupted by a suspend (rather than a quit).
• Whenever the restore process gets suspended, the restore process can be resumed again by applying the next available rollforward archive files and/or the logical.log file.
• Between suspend and resume process, the database is in “Restore suspended (unstartable) mode”, i.e., only the vbackup -resume is allowed to start and access this database.
Versant Server Guide 181
• In the case of an emergency the restore process needs only to be resumed with the last roll forward archive file(s) and/or the logical.log of the primary database in order to have the last transactions recovered in the warm standby database that is now ready to be used as the new primary database.
182 Versant Server Guide
Usage
9.1. Usage
vbackup -restore dbname -resume
Resumes a suspended restore procedure.
During the restore operation, when the data in the given backup media, is successfully restored, vbackup prompts the DBA to change the media or to complete/suspend the restore procedure.
There are different cases in this:
• If there is still backup data to be restored, the DBA can change the media (or change the device name) and then continue the restore procedure.
• If there is no backup data left and the DBA considers the restore is complete, he can issue a quit command at the command prompt. Then eventually an existing logical.log will be applied, which will complete the restore procedure and terminate the vbackup utility. After this the database is ready to be used.
• If there are no more roll forward archives available at the moment, but the DBA wants to resume the restore procedure when new roll forward archives become available at a later time, he can issue a suspend command at the prompt. This will terminate the vbackup utility. The database is now partially
restored, or it is in a restore suspended (unstartable) mode. Later, by using the -resume option, DBA can continue to restore the database when new roll forward archives are available or complete the restore procedure.
The vbackup process shuts down the database server after each suspend.
9.1.1. Setting up Incremental Restore for Warm Standby
Incremental Restore always requires a second machine - the Warm Standby machine.
For successful incremental restore, your machine needs to be setup with the following:
1. The warm standby machine needs one new Versant database domain, to avoid dbid problems (to simplify the maintainability and the restore itself - as the standby database always needs to have the same dbid like the original database), i.e., a new osc-dbid file needs to be created on that machine.
2. A makedb has to be performed before the actual restore begins (like with a full restore)
Versant Server Guide 183
Usage
3. The profile.be file of the original database should be either extracted from the backup or obtained from the original database. Before starting the restore process the profile.be might be adapted to the requirements of the new machine, in particular to those of the raw devices that are being used for the database volumes.
4. One location should be prepared where the logical.log of the original database will be located in the last steps of the incremental restore (e.g.,./tmp/logical.log)
9.1.2. Starting the Incremental Restore Process
Incremental restore needs to be started with the normal restore.
After the incremental restore has been setup as described above, the restore process can be started by using: vbackup -dev /backup/test_db/test_db.bac1 -restore test_db
The restore process will apply all existing backup devices to the database it just created, on the standby machine. After which it may eventually apply higher level backup devices also (from level 1 or 2). Then it will request for RF archives.
Every time the restore process requests an additional RF archive, you have the choice to:
• Complete the restore by typing quit - the restore gets completed and (depending on the answer to the question about applying logical.log at the beginning of the restore) the logical.log file gets applied.
• Suspend the restore by typing suspend - the restore goes into “restore suspended (unstartable)" mode.
• To continue the restore by typing the name of the next RF archive, e.g., d /rf/test_db.rf34 and confirming.
9.1.3. Suspending the Incremental Restore Process
suspend
By typing suspend when being asked for the next RF archive the following will happen:
• The database is being set into suspended restore (unstartable) mode, ensuring that the database cannot be accessed by any database utility or application except the vbackup -resume.
184 Versant Server Guide
Usage
• It terminates the vbackup process and stops the database
9.1.4. Restoring the Suspended Mode
In the restore suspended (unstartable) mode the database is unstartable.
Only the vbackup -restore <dbname> -resume may start the database.
dbinfo -p will give the following output as an answer to the state of the database.
VERSANT Utility DBINFO Version 9.3.0
Copyright (c) 2017 VERSANT Corporation
Database is in Restore suspended (unstartable) mode ...
9.1.5. Resuming the Database (-resume)
The restore process that has been suspended by the suspend option as described above, can be continued by the -resume option of the restore command.
vbackup -dev <rf archive name> -restore <database-name> -resume
This command resumes a suspended restore procedure.
When this option is used, data in the volume provided by the -device option, is a roll-forward log archived by the vbackup utility with the -log option.
When a logical.log is requested (at the very end of the resume process), then the absolute path names have to be provided in the case that the resume has been started remotely.
During the resume process, following steps take place:
• Starting the database
• Changing the database mode to "restore"
• Requesting the next RF archive from the user.
Here the you can select from three options:
Versant Server Guide 185
Usage
• Enter the name of the next RF archive - then this archive will get restored and then ask for the next one (again there are three options possible)
• Enter "suspend" (the letter "s" is sufficient) - then the resume gets suspended.
• Enter "qui" (the letter "q" is sufficient) - then the restore completes and asks if you want to apply a logical.log
at the end. If you answer "Y(es)" then it will ask for the location of the logical.log. It will apply the logical.log and bring the database back into multi-user mode.
9.1.6. Completing the Restore Process
When you want to complete the restore process (typically in an emergency case, i.e., when the original database cannot be started anymore), there are three cases possible:
1. There is still one RF archive and the logical.log file is available from the original database
2. There is only one RF archive, but no logical.log file available
3. Neither a RF archive nor a logical.log file is available
For 1:
the normal resume procedure applies as described above, completed by (quit). After which you will be asked if you want to apply the logical.log. The answer is "Yes", then you will be asked for the location of this logical.log file.
For 2:
similar to 1, until you enter quit, except on being asked if you want to apply the logical.log, the answer will be "No".
For 3:
a specific keyword has to be used as a device name: llog_only.
vbackup -dev llog_only -restore <dbname> -resume
It is possible to omit the device name if a default device name has been defined by setting the environment variable VERSANT_TYPE.
For Example:
186 Versant Server Guide
Usage setenv VERSANT_TYPE llog_only
In this case the following command will do the same like the above command: vbackup -restore <dbname> -resume
In all three cases the database state will be switched back to multi-user state and can be started.
The handling of the logical.log depends on whether you are using the -restore option or the -resume option.
The -restore option creates a new database (and a new logical.log file) and therefore needs to be interacted with in order to save the logical.log before it starts working.
The -resume option can ask this question after the last roll forward archive got applied (and the resume process has been terminated by typing quit). In most practical cases only the DBA can answer the question if the logical.log should be applied and where it is located (locally on the warm standby machine).
9.1.7. Activating the Warm Standby Database
After completing the restore process, the standby database needs to be activated for the application.
In order to activate the standby database, it is necessary to update the VERSANT_DBID, VERSANT_DBID_NODE and VERSANT_DB environment variables to the new locations (host and location of the standby database).
After this, the warm standby database is accessible for the application again.
Versant Server Guide 187
Example
9.2. Example
Following is an example to illustrate the typical usage of incremental restore for warm standby.
In this example, there is a database mydb running on host1 and an almost up-to-date copy of mydb is maintained on host2. If mydb on host1 is down, the database mydb on host2 will be activated to take over the services. The database on host2 is kept up-to-date through Versant backup/restore mechanism.
Setting up Warm Standby
1. Install Versant on the warm standby host.
2. Create a new osc-dbid file on that machine if it has not already been created by the installation( as a default). dbid -N
3. makedb mydb
4. Copy profile.be from the original database to the directory created by the makedb in step 2. The profile can be obtained from the backup file directly or by an OS copy operation from the database directory of the original database.
5. Adapt the profile.be to the new machine appropriately (mostly the volume locations)
6. Choose a directory to copy the original logical.log file, for example, .. /tmp/mydb/logical.log on the warm standby host.
9.2.1. Maintaining the Warm Standby Database Up-to-date
First, a full backup of the mydb on host1 needs to be taken and the roll-forward backup mechanism is activated: vbackup -dev mybackup -rollforward -backup mydb@host1
The backup "mybackup" is restored on host2 to create the backup database "mydb".
vbackup -dev mybackup -restore mydb@host2
VERSANT Utility VBACKUP Version 9.3.0
Copyright (c) 2017 VERSANT Corporation
Restoring database `mydb' from device `mybackup':
188 Versant Server Guide
Example
During roll forward, would you like to apply records from the database's current log file in addition to any archived records ? [default = yes ] no
0% 50% 100%
| | | | |
........................................
Restore has completed successfully.
Would you like to do another level of restore on database `mydb'? [ default = no ] no
Current settings are: device = `mybackup' position = `current' capacity = `dynamic' blocking = `10 Kilobytes'
Insert log archive #1 of database `mydb'. [?=help] s
The command suspend suspends the restore procedure of mydb@host2. This suspended restore procedure can be "resumed" any time later by using the -resume option of the restore. No other operation is permitted on mydb@host2.
After restoring the full backup on the host2, on host1 roll-forward logs are archived regularly to files log_1
, log_2, … log_n …etc., i.e., on host 2 we have the standby database, while on host1 production is running. The database actions of the production machine are saved in the RF archives.
vbackup -dev log_n -log mydb@host1
Periodically, the archived roll-forward logs are applied to the warm standby database on host2 to keep mydb@host2 up to date.
To apply the archive file log_n, option -resume is used.
vbackup -dev log_n -restore mydb -resume
VERSANT Utility VBACKUP Version 9.3.0
Copyright (c) 2017 VERSANT Corporation
Current settings are: device = `log_n' position = `current'
Versant Server Guide 189
Example capacity = `dynamic' blocking = `10 Kilobytes'
Insert log archive #n of database `mydb'. [?=help]
Here, you have three options:
• Press the enter key. This confirms the correct settings. The archive number n gets applied to the database and you will be asked to insert archive #(n+1). Now you again have three choices:
• Type suspend (or abbreviate by "s")
This will suspend the resume process and can be resumed at any later point in time
• Type quit (or abbreviate by "q") to quit
You will again be asked:
• Do you have a copy of logical.log file that you would like to apply at this point ? [default = yes ]
• A "no" here will complete the restore.
• The default is “yes” and will lead to:
Enter the path of logical.log:
• Enter the full path name of the logical.log. For example, : /tmp/mydb/logical.log
• And now you get the command prompt again.
• The restore is now completed and the database is back in the multi-user mode.
9.2.2. A Special Case of Resume
In the case that the primary database is down, the restore procedure on mydb@host2 might need to get completed immediately without applying any further RF archives.
There are two possible cases:
• Last RF archive has been applied already and the logical.log of the original database is available
• Last RF archive is not available or the logical.log of the original database is not available
190 Versant Server Guide
Example
Case A:
If mydb@host1 is down but host1 is alive, the logical log file of the down database is usually available. If this is the case, then the log records in the logical.log can be applied to the backup database (when all written RF archives have been applied).
vbackup -dev llog_only -restore mydb@host2 -resume
VERSANT Utility VBACKUP Version 9.3.0
Copyright (c) 2017 VERSANT Corporation
Do you have a copy of logical.log file that you would like to apply at this point ? [default = yes ] y
Enter the path of logical.log : /tmp/mydb/logical.log
After this the mydb@host2 is ready to be used.
See also
Section 9.1.7, “Activating the Warm Standby Database ”
Every committed transaction is in the database. After a startdb the database is physically and logically consistent.
Case B:
If the host1 is down, but neither the last archived logs nor the logical log of the down database might be available(e.g., disk crash on host1). In such a case, in order to complete the restore procedure on host
2, the following needs to be done: vbackup -dev llog_only -restore mydb@host2 -resume
VERSANT Utility VBACKUP Version 9.3.0
Copyright (c) 2017 VERSANT Corporation
Do you have a copy of logical.log file that you would like to apply at this point? [default = yes] no
After this mydb@host2 is ready to be used.
See also
Section 9.1.7, “Activating the Warm Standby Database ”
Versant Server Guide 191
Example
Every archived and committed transaction is in the database. After a startdb the database is physically and logically consistent.
192 Versant Server Guide
Chapter 10. Utilities Reference
Sections
- -locks—Get Information About Locks
- -object—Get Information About Objects
- -trans—Get information about Transactions
- -sys—Database System and Consistency Checks
- -volume—Get Information About Storage Volumes
- -AT—Viewing Consistency and Maintenance of AT Table
- -trace—Trace Components of a Database
- -class—Get Information About All Classes in a Database
- -dbalog—Get Information About Logging Activities
- -space, -AT—Get Information on Fragmentation and Free Space
- -schevol—Get Information About Schema Evolution
- -schevol -evol—Evolve Instances to the Latest Schema
Versant Server Guide 193
194
- Warm standby (Incremental Restore)
- Changing the Parameter Settings
- Restrictions and Limitations
- The Statistics Viewer Output
- Statistics Configuration File—Derived Statistics
- Operating Across Platforms and Releases
- Estimating Operating System Resources
Versant Server Guide
Quick Reference
10.1. Quick Reference
Table 10.1. Database Utilities Quick Reference
Utility Name
Function
To increase the storage capacity of the database by creating and adding a volume to the database.
This utility confirms that the logical object identifiers for the objects in the compared databases are the same.
To convert a database from an older Versant version.
To create, format and initialize a new database.
To display the contents of a specified database along with its classes and objects
This utility manages the osc-dbid database system identifier file.
To determine or set the current mode of the database.
To list the databases in a system of databases coordinated by an osc-dbid file.
Depending upon options specified, you can use the this utility to get information about locks, objects, transactions, classes, logging activities, database system, storage volumes, indexes, AT table and event notification information.
To add, delete, list users or change password of a database or a DBA.
This utility drops one or more specified classes, their subclasses, and instances from a database.
Removes all instances of one or more classes and their subclasses from the a database without changing the database schema.
To create a database directory as per the specified options and to create the database support files.
This utility makes application process and server process profiles for a database.
To display information about the Versant environment for the currently used release.
Versant Server Guide 195
Quick Reference
Utility Name
Function
To stop the database if it is running, destroy and remove all volumes and delete the database from the osc-dbid file.
This utility sets the database identifier to a specified value.
To start the specified database.
To stop the specified database and removes all database resources in memory.
To defragment the database files online.
Copies all objects and class definitions from one database to another.
Print an error message given an error number, name or name fragment.
Display Versant product information, list the version information for each component, or verify consistency of the installation.
This utility will print the details of the installation information needed for generation of the license keys.
This utility is used to determine if a specified component is licensed.
This utility scans a specified license file for errors.
Used to move all objects and copy class definitions from the source database to the target database.
To start the statistics tool which can collect and view database statistics.
Exports the contents of a database to a file or imports data from a file into a database.
196 Versant Server Guide
addvol
10.2. addvol
addvol parameters [options] dbname
This utility increases the storage capacity of the database by creating and adding a volume to the database dbname
. The volume name and path are specified as parameters substituted for parameters and with the options substituted for options.
For a remote database, append the node name to the database name using the syntax database@node.
For performance reasons it is recommended that you have a few volumes of large size rather than many small volumes.
Maximum 2000 volumes
The maximum number of volumes is limited to 2000. Exceeding this limit has the effect that the database cannot be properly backed up and restored.
You must be the owner of the database to add a volume.
The new volume will be registered in the database, and the server process profile file profile.be will contain an entry of following type indicating volume name, size and absolute location specified at creation time.
datavol volume_name size [absolute_path] datavol vol1 1G /vol1/vol1
The new space will be available immediately after the addvol utility finishes. The additional storage space will be available to all classes in the database as classes can span volumes. The volume added would augment the system volume but have no effect on the capacity of the logical or physical log volumes.
There is no corresponding command to delete a volume. To reorganize a database online use the vcompactdb utility.
The minimum size of a database volume depends upon the setting for extent_size specified in the server process profile file, profile.be.
Versant Server Guide 197
addvol
If you run out of database space or database recovery fails for lack of space, the error code 1083,
SM_E_OUT_OF_VOL_SPACE is raised.
Mandatory parameters to be specified are:
-n volName
Name for the new volume. The length of the name is restricted to 31 characters.
For example: -n volume2
-p volPath
Full path name of the volume device or file.
You may specify the path in relative or absolute terms.
For example: -p volume2
The data volume can be moved later to another location. The datavol entry in the server profile will have to be modified accordingly.
For more information, refer to
Options are:
-e extentsize
This is the default option. Extent size in pages. The default is to use the extent size specified in the server process file profile.be.
For example: -e 4
-i
Pre-allocate disk space and initialize the volume. This will prevent a possible insufficient space error at runtime.
-noprint
Suppress display messages while running.
198 Versant Server Guide
addvol
-s volSize
Volume size.
The default size is 128 megabytes. Indicate kilobytes with k or K, megabytes with m or M and gigabytes with g or G.
For example:
-s 1024k
-s 1M
-s 2G
If the size parameter to addvol is not specified on the command line, then the default size will be used. If the datavol entry is already in the server profile file then, the volume with the same name cannot be created manually because the server assumes that the volume with this name already exists.
If the database is associated with password authentication mechanism, then addvol utility will prompt the user to specify the DBA password before making any changes to the database.
Additional Notes for Linux Users
The database files need to be local. This allows the Versant Server process to directly access the database files and will improve performance.
Accessing database files through NFS is not supported. The NFS protocol does not guarantee that file writes are flushed to disk on invocation of a flush system call. For this reason, the use of NFS could result in database corruption!
Versant Server Guide 199
comparedb & compardb
10.3. comparedb & compardb
UNIX comparedb [options] db1 db2
WIN compardb [options] db1 db2
This utility counts the objects in the databases specified as db1 and db2, confirms that the logical object identifiers for the objects in the databases are the same, and displays the logical object identifiers for the first object that is different.
This utility is useful in comparing the contents of a primary and synchronous replication database.
Before using comparedb, you must use the dbinfo utility to set both databases to single user mode in order to compare stable database states.
See also
Section 10.8, “dbinfo” pg. 211.
The second comparison database db2, must be a group database.
You can call comparedb from a program by using the Versant C o_comparedb() function or the Versant
C++ comparedb() method.
Options for Comparedb Utility are:
-classes <class1><class2> ...
This is the default option: compare objects of only the specified classes.
-fullcompare
Display list of loids of objects, which are different in two databases. This option is incompatible with -noprint option.
-noprint
Suppress display messages while running.
-value
Compare object values as well as object identifiers and display the first logical object identifier for objects with non-equal values.
200 Versant Server Guide
comparedb & compardb
-advanced –classes
Compare objects of only the specified classes with alternative algorithm. This option can be used with classes having large number of instances.
If any or both the databases are associated with DBA password then the user will be prompted for their respective passwords to complete the DBA authentication. If both databases need DBA authentication, the two databases should have the same DBA password. If only one of them needs DBA authentication, then the DBA should give the password for the database which needs DBA authentication.
Versant Server Guide 201
convertdb & cnvrtdb
10.4. convertdb & cnvrtdb
LINUX convertdb [options] database_name
WIN cnvrtdb [options] database_name
This utility converts one Versant database from an older version to the current version. This might be necessary in order to enable the use of new features.
The system prompts a confirmation message before starting the conversion procedure. Enter YES to continue with the conversion of the database or NO to abort the operation.
Make sure to back up the database before using this utility.
Options for convertdb utility are:
-noprint
Suppress some display messages while running.
You must end all transactions and then stop the database with stopdb before and after converting it.
Do not stop the database with the -f option.
Example: convertdb pdb
Versant Utility CONVERTDB Version 9.3.0
Copyright (c) 1989-2017 Versant Software LLC
WARNING: Please make sure that the database is backed-up before proceeding with conversion.
Would you like continue? Enter "yes" to continue: yes
202 Versant Server Guide
convertdb does not require the DBA password.
convertdb & cnvrtdb
Versant Server Guide 203
createdb
10.5. createdb
createdb [options] dbname
This utility creates, formats, and initializes a new database with the name dbname and either makes the new database a part of an existing distributed database system or starts a new database system.
Before using createdb, you must use the makedb utility to create a database directory. This will also create the backend and frontend profile files.
The database name dbname must be unique for the distributed database system to which it will belong.
You must be the owner of the database (DBA) or the super user to run this utility.
If the user has specified a password at the time of makedb operation, then the user is prompted for a DBA password and only then it will authenticate you to create, format and initialize a database.
For a remote database, append the node name to the database name using the syntax database@node.
This utility will create the physical log, logical log and system volumes using either values found in the server process profile or else with default values.
If the server profile contains datavol entries for data volumes, then these volumes will also be created.
The createdb utility will update the osc-dbid file to register the new database with the existing distributed database system. The file osc-dbid containing the path and name of all databases in the system must be visible from your machine when you run createdb.
Options for createdb utility are:
-i
This is the default option.
Reserve space for the system volume.
Reserving space can prevent you from running out of space at runtime. For example, suppose you set the size of the system volume as 100 megabytes in your profile, but you really have only 60 megabytes physically available. In such a case, if you use -i, you will immediately get an out-of-space
204 Versant Server Guide
createdb error, but if you do not use -i, you will get an error at runtime as the system volume dynamically expands.
If you have defined multiple storage volumes and the physical space in one volume is less than the logical space, you will get an out-space-error at runtime even though there is space available in the next volume.
Pre-allocating space may improve performance, because space will not have to be dynamically allocated. However, pre-allocating space will slow down the process of creating the database, and because the space is used immediately, it will prevent it from being used for other purposes.
The -i option has no effect on Linux raw devices.
Space for log volumes is always pre-allocated according to the parameters set for the plogvol and llogvol size specifications.
-il
Reserve and pre-format file system space for the logical log volume and the physical log volume.
-noprint
Suppress display messages while running.
If the -i option is specified, both the system volume and any data volumes created will be initialized.
Examples of using createdb: createdb mydb createdb -i mydb
Key components of the newly created database will be:
System volume
A system volume for catalog information and data storage, with a name, location, size, and device according to the specification in the server process profile file profile.be.
The default is a file of 1024 megabytes, named ‘system’ located under the database directory. For example, for a database named dbname:
/usr/local/versant/db/dbname/system
Versant Server Guide 205
createdb
Physical log volume
A physical log volume for physical data information related to logging and recovery, with a name, location, size, and device as specified in the server process profile file profile.be.
The default is a file of 24 megabytes named physical.log located under the database directory. For example, for a database named dbname:
/usr/local/versant/db/dbname/physical.log
Logical log volume
A logical log volume for transaction undo-redo information related to logging and recovery, with a name, location, size, and device as defined in the server process profile file profile.be.
The default is a file of 24 megabytes named logical.log located under the database directory. For example, for a database named dbname:
/usr/local/versant/db/dbname/logical.log
.sharemem
This empty file ensures the creation of a shared memory key that is unique to this database.
206 Versant Server Guide
db2tty
10.6. db2tty
db2tty -D dbname [ options ] [ classnames ...] db2tty -D dbname [ -l ] -o loids
This utility displays the contents of the database specified by dbname.
In the first string, you can optionally specify the names of classes whose contents you want displayed.
In the second string, you can specify the objects you want displayed by using their logical object identifiers
(loids.)
Options for the db2tty utility are:
-6
The -6 option forces the database to communicate using only the IPv6 protocol. If not specified the system's default communication protocol is used.
-4
The -4 option forces the database to communicate using only the IPv4 protocol. If not specified the system's default communication protocol is used.
-a
Show all classes. This option will display a list of the system classes and user-defined classes together with the number of instances for each class. (Refer also to option
, below.)
You can combine this option with -s (i.e., -a -s) to list the classes without their instance count.
-i
Show instances.
-l
Obtain a read lock on the objects to be displayed. The default is no lock.
Versant Server Guide 207
db2tty
-n
-o loids
The logical object identifiers of the objects to be displayed.
-p
The number of objects to be retrieved at a time. The default cursor batch size is 200.
This option can be only used with the -i option.
Password corresponding to the user name entered in -u. This is mainly intended for scripts so that users don't have to enter the password interactively. For normal usage, users can just pass in the -u option and db2tty will prompt for a password. Passwords cannot be more than 255 characters in length.
Running with just the -p option without the -u option will result in an error.
-s
Show a short class list. This is the default output for the db2tty command. This option will display a list of only the user-defined classes and without the number of class instances. (Compare this to the option
This option may be combined with option -a (i.e., -a -s) to display both system classes and user-defined classes but without the instance count.
-u
User name to access the DB. This user has to be a valid user of the DB . You'll be prompted for a password if no password is entered using the -p option. Username cannot be more than 31 characters in length. The default is to run as the OS user without any password.
If you need to count the actual number of instances present in the database run db2tty -i -D
<dbname>.
208 Versant Server Guide
dbid
10.7. dbid
dbid [options] <dbname>
This utility manages the osc-dbid database system identifier file. The osc-dbid file stores the route path and name of all databases in a particular database system (refer to
Section 3.1.1.3, “Database System
Identifier File (osc-dbid)” pg. 27). The utility uses the osc-dbid file specified in the locally set
environment parameters VERSANT_DBID_NODE and VERSANT_DBID. The dbid utility works only with the entries in the osc-dbid file and does not modify the database(s). Refer also to
.
You should not use dbid unless explicitly directed to do so by Versant Customer Support.
In particular, the -c and -C are advanced options and should be used with great care. If they are used, you will need a subsequent call to setdbid with the dbid which has just been created.
Specifying the database
If the database name, <dbname>, is specified, then the osc-dbid file entry will use the local host name.
For example, if your local host is named MyHost, the command dbid -c NewDB will create an entry in the osc-dbid file for NewDB@MyHost. If the entry is for a database on a different host, specify that as dbname@hostname
. (The dbid utility will check that the specified host name is accessable and return with an error if it is not.)
Options
-N
Create an osc-dbid file. <dbname> is not specified.
-c
Create an entry in osc-dbid file for database <dbname> using the next available database identifier
-C <dbid>
Create an entry in the osc-dbid file for database <dbname> with the database identifier specified by
<dbid>
.
Versant Server Guide 209
dbid
-d
Remove the database <dbname> entry from the osc-dbid file.
-r
Print the database id of the database <dbname>
-noprint
Suppress display messages.
210 Versant Server Guide
dbinfo
10.8. dbinfo
dbinfo option database_name
This utility determines or sets the current mode of the database specified as database_name.
This utility can be used only by the database administrator (DBA) of a database. Along with the OS check, the password-based authentication of the DBA will also be done if the database is associated with a password.
You can change a database mode from one state to another at any time, except when changing the mode to and/or from read-only. After a new mode is set, it only affects new connections and existing connections run without interruption. If you want to break existing connections, after running dbinfo, you must stop the database with stopdb.
Parameters for dbinfo utility are:
-c
Create a new .lock hidden file in the current directory.
-p
List the current database mode.
[-m | -0 | -1 | -d | -r]
-m
Set database to multi-user mode.
This is the normal mode for a database.
For a group database, this means that, within the normal definition of a group database, any number of users can make any number of connections.
For a personal database, this means that, within the normal definition of a personal database, only one user at a time can use it, and can use it only as a session database.
Versant Server Guide 211
dbinfo
-0
Set database to unstartable mode.
This mode prohibits all access to the database and prevents it from being started with the startdb utility tool.
-1
-d
Set database to dba/multiple-connections mode.
-r
Set database to dba/single-connection mode.
The database is startable, but it will only accept a single connection from a single client run by the database administrator.
Set database to read-only mode.
The database is startable. However, all data volumes and log volumes are opened in read-only mode and cannot be modified. If you want to access the database from a CD/DVD, then you need to change the mode to read-only before writing the database files to the media. Once the database is written on the CD/DVD you can mount it on the desired machine and you can change the Versant database directory in your environment to point to the media directory that contains the read-only database.
Once this is setup, you can start the database and use it for all types of read-only transactions.
212 Versant Server Guide
dblist
10.9. dblist
dblist [options] [@node]
This utility lists the databases in a system of databases coordinated by an osc-dbid database system identifier file.
To run dblist on a remote node, specify the name of the remote machine using the optional @node argument, where node is the name of the remote machine.
If there are multiple database systems in your network, the databases listed will be those in the network database system coordinated by the osc-dbid file specified in the currently set environment parameters
VERSANT_DBID_NODE and VERSANT_DBID.
Options for dblist Utility are:
-all
This is the default option.
List all databases in the database network system coordinated by the osc-dbid database system identifier file specified in the currently set environment parameters VERSANT_DBID_NODE and
VERSANT_DBID
. This is the default option.
-owner owner_name
List all databases in the system owned by owner_name.
-d dbname[@node]
List only the named local or remote database.
For a remote database, append the node name to the database name using the syntax: database@node.
-dir
List all database directories, including directories which do not currently contain a database, branching from the database root directory specified by the current setting of the VERSANT_DB environment parameter plus all databases that would be returned by the -all option.
Versant Server Guide 213
dblist
-noprint
Suppress display messages while running.
Examples for dblist utilities are below: dblist dblist -all dblist -owner myname dblist -dir
Sample output:
Versant Utility DBLIST Version 9.3.0
Copyright (c) 1989-2017 Versant Software LLC
ID
DB name
= 4678
= db01@server1 creator = cp date created = Mon Jul 14 22:19:40 2014 db type = GROUP DATABASE db version = 9.0.0.0
ID
DB name
= 4679
= db02@server2 creator = cp date created = Mon Jul 14 22:19:49 2014 db type = GROUP DATABASE db version = 9.0.0.0
....
214 Versant Server Guide
dbtool
10.10. dbtool
dbtool [GeneralOptions] Module [ModuleOperation] [ModuleOptions] DatabaseName
The dbtool utility provides numerous modules that perform operations that allow you to get information about or work with different aspects of a database and its contents. Some modules provide more than one operation. If so, you will have to specify the desired module operation. Each module has its own
module options related to the module operation(s). In addition, there are general options that apply to the overall operation of the dbtool utility. For all dbtool operations, you will need to specify the database you want to work with.
Use considerations
The following points need to kept in mind when using dbtool
• The dbtool utility can only used by the DBA of the specified database. It cannot be called using an interface routine.
• The dbtool utility cannot be used to work on a remote database, i.e., dbtool needs to run on the same node as the database server. Exceptions to this rule are the create index (refer to
“Create Index” pg. 234) and the delete index (refer to
Section 10.10.7.3, “Delete Index” pg. 235)
operations.
• The dbtool utility will run in a separate database session. If the database is stopped, the utility will start it in order to create a session. The database is started regardless of the allow_implicit_startdb database profile configuration parameter setting (refer to
information about this parameter). You can prevent utility from automatically starting the database with the dbtool -nosession general option. Refer to
General options and modules
The following sections, listed below, start with the general options for dbtool and continue with the different modules and their operation and options.
•
•
•
—Get Information About Objects
•
—Get information about Transactions
Versant Server Guide 215
dbtool
•
—Database System and Consistency Checks
•
—Get Information About Storage Volumes
•
•
—Viewing Consistency and Maintenance of AT Table
•
—Trace Components of a Database
•
—Get Information About All Classes in a Database
•
—Get Information About Logging Activities
•
, -AT—Get Information on Fragmentation and Free Space
•
—Get Information About Schema Evolution
•
—Evolve Instances to the Latest Schema
10.10.1. General Options
The following options affect the general operation of the dbtool utility. Not all options apply to all modules. The following lists the general options with a brief explanation of their use.
-echo
With this option, dbtool will echo the command arguments, printing them preceeding the header.
Here is a command without -echo.
$ dbtool -class -info -list pdb1
VERSANT Utility DBTOOL Version 9.3.0
Copyright (c) 2001-2015 Versant Software LLC and Copyright (c) 2013-2015 Actian
Corporation. All rights reserved.
** Existing Level 2 Files **
Volume 0 ("sysvol", 1048576K, "C:\Versant\db\pdb1\system"): class
. . .
:0 class 515
The same command with -echo.
216 Versant Server Guide
dbtool
$ dbtool -echo -class -info -list pdb1
Arguments: -echo -class -info -list pdb1
VERSANT Utility DBTOOL Version 9.3.0
Copyright (c) 2001-2015 Versant Software LLC and Copyright (c) 2013-2015 Actian
Corporation. All rights reserved.
** Existing Level 2 Files **
Volume 0 ("sysvol", 1048576K, "C:\Versant\db\pdb1\system"): class
. . .
:0 class 515
If used, -echo must be the first option on the command line.
-noHeader
Using this option simply suppresses printing the header. This can be combined with -echo. An example command with -noHeader.
$ dbtool -echo -noHeader -class -info -list pdb1
Arguments: -echo -noHeader -class -info -list pdb1
** Existing Level 2 Files **
Volume 0 ("sysvol", 1048576K, "C:\Versant\db\pdb1\system"): class :0 class 515
. . .
-nosession
Under normal operation, calling dbtool will establish a session with the named database. If the database is not started, the utility will start the database in order to establish the session. In general, a session is not strictly required for operations that do not write to the database. However, operations such as creating an index or updating the schema—any operation that must write or modify information in the database—will require a session.
The -nosession option directs the utility to not establish a database session for the utility. Operations that require a session, i.e., operations that modify the database contents, will not run if the no-session option is specified. Using the -nosession option will also prevent the utility from automatically starting a stopped database. This implies that the no-session option only applies if the database is started.
Versant Server Guide 217
dbtool
An example
For example, if you want to list the running transactions, the dbtool command is as follows.
dbtool -trans -info DatabaseName
Running this command will list the currently active transactions including the transaction for this utility call. To suppress the utility itself from showing up in the transaction listing, use the -nosession option.
dbtool -nosession -trans -info DatabaseName
Suppressing a database start
Taking the previous example further, if a crash occurs, you may want to know which transactions were left “hanging”. Running the command dbtool -trans -info DB (without -nosession) will automatically start the database resolving the hanging transactions. You can use the no-session option to preserve the database state allowing you to gather useful information for investigating the cause of the crash.
Error reporting
As described above, a session will not be established for the utility using the no-session option.
Using the no-session option will also prevent the utility from starting the database, if necessary, to begin a session. If the database is stopped and you use the -nosession option, regardless whether the operation would require a session or not, the dbtool utility will return with the following error.
ERROR: The database is not started.
The "-nosession" option requires the database to be up.
If the database is started and you use the -nosession option with an operation that requires a session, e.g., creating an index, dbtool will report the following error.
E4012: OM_SE_NOT_IN_SESSION: o_setsession must be called
(The reported error messages may be followed by additional information, depending on the attempted operation.)
218 Versant Server Guide
dbtool
-offline
Using the -offline option directs dbtool to stop the named database and start it in single-user mode before performing the specified utility operation. This is equivalent to calling dbinfo -1
DatabaseName
before calling dbtool. (Refer to
Section 10.8, “dbinfo” pg. 211.)
10.10.2. -locks—Get Information About Locks
dbtool –locks [operation] <options> <dbname>
Options for this utility are:
-stats
Prints lock statistics.
Following is sample output for a database named group that shows lock statistics since the moment when the database was started.
dbtool -stats group
** Lock Statistics **
Locking statistics: total = 98443 outstanding = 97659 deadlocks = 0 conflicts = 0 requests = 196101 objects = 97659
Following is an explanation of the lock statistics fields:
total
The number of locks granted since the database was started.
outstanding
The current number of locks granted. A particular object may have more than one lock; for example, an object might have numerous read locks.
Versant Server Guide 219
dbtool
deadlocks
The number of deadlocks that have occurred since the database was started.
conflicts
The number of times a lock request has been blocked since the database was started.
requests
The number of lock requests since the database was started.
objects
The number of locked objects.
-info
Prints information about current locks held on objects in the specified database. See the -table option (below) for more information.
-v
-xa
Adds extra verbosity.
Displays additional xa state information.
• xid: The xid which has been selected by the transaction manager to open the resource.
• xaTBState: The current transaction branch state of the lock (S0 - S5).
-table [-c connid ...] [-o loid ... ]
Prints lock information for a set of given connections and objects for the specified database.
For connectionid.., you can specify one or more connection identifiers.
For loid.., you can specify one or more logical object identifiers in dotted triple notation.
You can use either or both of the -c and -o options. If neither the -c nor the -o are supplied, -table is similar to -info, except that -table supplies more information than -info.
220 Versant Server Guide
dbtool
For example, for a database named group: dbtool -locks -table group dbtool -locks -table -c 1 group dbtool -locks -table -o 1.0.23456 group dbtool -locks -table -c 1 -o 1.0.2345 group dbtool -locks -table -c 1 2 -o 1.0.12345 1.0.45678 group
For each connection, the following will be printed:
• the connection identifier
• information about the connection, including client hostname, client process identifier, and username.
For each locked object, the following will be printed:
• the logical object identifier (loid) and class name
• the lock mode
• Lock flags indicating whether the lock has been granted ("Hold") or being waited for ("Wait").
Sample Output
Following is sample output that shows information for all locks held on objects in a database named db2
. Note that there are two users.
User Anna is on a machine named alpha with a Versant connection id of 6 and a system process id of 28737. User Anna holds 6 short locks and is waiting for 1 short lock. User Anna is in a session named
VersantView-28737, which is a default name based upon the process id.
User George is on a machine named beta with connection 10 and process 28742. User George holds
7 short locks. User George is in a session named VersantView-28742.
In this case, most of the locks are held on objects of class Course. Locks indicated as an instance of class, are on a class object. Locks indicated as an instance of attribute, are on an attribute object.
The type of short lock is indicated by the usual symbols for lock mode parameters; WLOCK = write lock, RIWLOCK = read/intention-write lock, IWLOCK = intention-write lock, ULOCK = update lock, RLOCK
= read lock, IRLOCK = intention-read lock, and NOLOCK = null lock.
Versant Server Guide 221
dbtool
% dbtool -table db2
Connection Id: 6
Client: alpha[pid: 28737] Session: VersantView-28737
User: venka
LOID [instance of] Lock Lock Flags
========================== =========== ==========
347.0.162850 [Course
347.0.162849 [Course
]
]
RLOCK
RLOCK
Hold,Transient
Hold,Transient
347.0.162848 [Course ] WLOCK
347.0.162822 [attribute ] RLOCK
0.0.2
[class ] IRLOCK
347.0.162821 [attribute ] RLOCK
347.0.162820 [class
Number of locks: 7
] IRLOCK
Wait,Transient
Hold,Transient
Hold,Transient
Hold,Transient
Hold,Transient
Connection Id: 10
Client: beta[pid: 28742] Session: VersantView-28742
User: George
LOID [instance of] Lock Lock Flags
=========================== =========== ==========
347.0.162850 [Course
347.0.162849 [Course
] RLOCK
] RLOCK
347.0.162848 [Course ] RLOCK
347.0.162822 [attribute ] RLOCK
0.0.2
[class ] IRLOCK
347.0.162821 [attribute ] RLOCK
347.0.162820 [class
Number of locks: 7
] IRLOCK
Hold,Transient
Hold,Transient
Hold,Transient
Hold,Transient
Hold,Transient
Hold,Transient
Hold,Transient
Following is sample output for an object with loid 347.0.162849 in database db1. In this case, user
Anna has a short read lock on this object and user George has an update lock and is waiting for a write lock on the same object. From the point of view of a database, each transaction has only one lock entry per object, so in this case, even though George has an update lock, what you will see is an entry showing the wait for a write lock.
% dbtool -table -o 347.0.162849 db1
Connection Id: 7
Client: alpha[pid: 28790] Session: VersantView-28790
User: venka
LOID [instance of] Lock Lock Flags
=========================== =========== ==========
222 Versant Server Guide
dbtool
347.0.162849 [Course
Number of locks: 1
] RLOCK Hold,Transient
Connection Id: 22
Client: beta[pid: 28814] Session: VersantView-28814
User: George
LOID [instance of] Lock Lock Flags
=========================== =========== ==========
347.0.162849 [Course
Number of locks: 1
] WLOCK Wait,Transient
10.10.3. -object—Get Information About Objects
dbtool -object [operation] [options] <dbname>
Options for this utility are:
-info <x.y.z>
Prints information about the object with the specified logical object identifier (LOID) <x.y.z>.
The information printed is useful primarily to Versant Technical Support, as it indicates information about the internal workings of Versant.
Sample Output
dbtool -object -info 2142.0.7187 group
LOID : [2142:0:7187] is in AT and in data page
KIND
{Rvolid=0, Rpage=70, Rslot=114}
: Normal object
CLASS : class
SIZE : 248
STATUS : Normal
TYPE : Normal, never moved
10.10.4. -trans—Get information about Transactions
dbtool -trans [operation] <dbname>
Versant Server Guide 223
dbtool
-info
Prints information about current transactions involving objects in the specified database.
The following is a sample output.
$ dbtool -trans -info testdb
VERSANT Utility DBTOOL Version 9.3.0
Copyright (c) 2001-2017 Versant Software LLC and Copyright (c) 2013-2017 Actian Corporation. All rights reserved.
** Short transaction Info **
---------------------- ----- --------- ------- -------- ---------------- ---------- ------------ ------------
Transaction ID Coord LockCnt flags seconds server pid.tid
client pid client name session name
---------------------- ----- --------- ------- -------- ---------------- ---------- ------------ ------------
15745.0.2105
y 00001 x088290 73.00 06072.01772
04120 testuser 4120@testhost
224
Following are brief explanations of the transaction information items provided.
Transaction ID
Transaction identifiers assigned by Versant. This information is for use by Versant technical support.
Coord
An indication of whether this database is storing coordinator information for two-phase commits, i.e., whether the specified database is being used as a session database.
LockCnt
The number of locks held by the transactions in the specified database.
flags
This is internal information for use by Versant technical support.
seconds
The time that the transaction has been active.
server pid.tid
This is internal information for use by Versant technical support.
client pid
Versant Server Guide
dbtool
This is internal information for use by Versant technical support.
client name
The application name of the current connection to the database.
session name
The session name of the current connection to the database.
-longTrans
The -longTrans option is used with the -info option, i.e., -info -longTrans, to display additional information about long transactions. The -longTrans option adds the following column to the -info output.
. . .
----------------------
. . .
long transaction ID
. . .
----------------------
. . .
Long transactions are deprecated. The -longTrans option is provided for legacy applications that use long transactions in order to view the long transaction identifier.
-xa
The -xa option is used with the -info option, i.e., -info -xa, to display additional information about distributed XA transactions. The -xa option adds the following columns to the -info output.
. . .
------- -------- -------- -------- ------- ------- ------------
. . .
TBState seconds TBAState seconds xaCount xaFlags XID
. . .
------- -------- -------- -------- ------- ------- ------------
. . .
S1 86.00
0 86.00
1 0x0 6162-636465
TBState
The XA transaction branch state. Refer to the XA specification for more information.
seconds
The time that the transaction has been in the given transaction branch state.
Versant Server Guide 225
dbtool
TBAState
The transaction branch association state. This is the association state between a thread of control and a transaction branch. Refer to the XA specification for more information.
seconds
The time that the transaction has been in the given transaction branch association state.
xaCount
The number of attached sessions.
xaFlags
This is internal information for use by Versant technical support.
XID
The XA transaction identifier. The identifier is displayed as a hexadecimal value by default. You can display the identifer as ASCII-characters with the additional option -xidAscii (dbtool -trans -info
-xa -xidAscii
). Non-printable characters are displayed as a period, '.' (ASCII 0x2E).
10.10.5. -sys—Database System and Consistency Checks
dbtool -sys [options] <dbname>
Running a consistency check on a database with active transactions is NOT supported and can lead to data corruptionn and/or spurious results. For this reason, dbtool tries to ensure that the database does not have any active clients before running the consistency check. It does so by issuing a stopdb command internally. If there are active clients running on the database, the stopdb command will fail and dbtool will report this and refuse to proceed with the consistency check. Also, dbtool internally changes the database mode accordingly in order to prevent any new clients from connecting to the database while the consistency check is in progress. After completion of the consistency check, the database mode will be restored. If the consistency check operation is interrupted for some reason, manual intervention might be needed to restore the database mode.
Options for this utility are:
226 Versant Server Guide
dbtool
-check [-MT] [-v] [-inst]
-MT
Perform an overall database consistency check. This option can be used independently or in combination with -MT or -v or -inst.
Enable consistency checks in multi-thread mode. This option is useful only for consistency checks.
The database must be in DBA multi-connection mode.
If this option is used with -v (verbose) mode, the dbtool verbose output is written to the following files.
checkAT.txt
checkAT3_dbidid-no_thread-name.txt
checkdb_n.txt
AT table checks output database file segment checks ouput (n represents the number of threads working on class segments)
By default, these files are created in the location where dbtool is invoked. If the environment variable
VERSANT_DBTOOL_DIR is present, the files are created in the specified directory.
If dbtool reports inconsistencies, refer to these files for more details.
-v
Verify database consistency in verbose mode.
-inst
Perform overall database consistency check and object consistency check. If an object is found in corrupted state, it prints the corresponding loid, poid, number of corrupted loids in a class and finally reports inconsistencies detected during the scan.
-info -activedb
Get names of all currently running databases located under the setting for database root parameter
VERSANT_DB in use by the current process. If there are multiple database root directories on the machine, the names of databases running under other root directories will not be returned.
Versant Server Guide 227
dbtool
-info -resource
Print system usage of shared memory, processes, threads, and connections that are associated with the specified database. Following is a sample of the output.
$ dbtool -sys -info -resource pdb1
VERSANT Utility DBTOOL Version 9.3.0
Copyright (c) 2001-2017 Versant Software LLC and Copyright (c) 2013-2017 Actian Corporation. All rights reserved.
Resources being used by the database: pdb1
Shared Memory:
--------------
Total shared memory in use is 44776K bytes
Total number of shared memory segments are 3
Processes and Threads:
----------------------
-------------------------------------------------------------------------------------------------------------------------------------
PID | TID | Conn. ID | State | Type | User@client[IP address:port],clientpid[session][transaction] |
-------------------------------------------------------------------------------------------------------------------------------------
15526 | 140501147051808 | 2
15526 | 140501005956864 | 3
15526 | 140501006223104 | 4
15526 | 140501005690624 | 5
15526 | 140501005424384 | 6
| alive | main thread
| alive | page flusher thread
| alive | cleanup thread
| alive | connector thread
| alive | vsignals thread
|
|
|
|
|
15526 | 140501005158144 | 7
15526 | 140501001303680 | 8
| alive | legacy connector thread |
| alive | logger thread |
-------------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
|
|
|
Shared Memory
The Shared Memory section shows the shared memory segments in use by database pdb1.
Processes and Threads
The Processes and Threads section provides information about the applications and system processes in use by database pdb1. The columns are:
PID
TID
The operating system process identifier.
The operating system thread identifier.
ConnId
The connection identifier assigned by Versant.
228 Versant Server Guide
dbtool
State
Whether the thread or process is "alive" or "dead".
Type
The type of thread or process. The following codes are used.
• main thread: the server main thread
• page flusher thread: background thread that updates modified pages from the page cache to disk
• cleanup thread: cleans up leftover resources of other threads
• vsignals thread: processes arriving signals synchronously (only present on Linux systems)
• connector thread: connection handling for Versant release 9.2 (or greater) clients
• legacy connector thread: connection handling for clients prior to release 9.2
• logger thread: writer thread that maintains the database log files
The following are only present when a client (or other process) is connected.
• session thread: a database thread that serves an application (each client/session will have a session thread)
• vbackup: a process used by the vbackup utility
• special: a special process, such as an event daemon
Client Information
There is a Client Information section only if the thread or process is associated with database connection made by an application (in the previous example, the client information is shown as wrapped to the next line.)
The client information will include the following:
Username@hostname
The user and machine names associated with the application that has a database connection.
Versant Server Guide 229
dbtool
IP address:port number
If the application is running in a different process, you will see the system TCP/IP address number (i.e. 192.70.173.172 in the above example) and port number (i.e. 37109) for the application.
Process ID
The operating system process identifier (i.e. 28790 in the above example.)
Session name
The name of the Versant session (either a specified or default name.)
10.10.6. -volume—Get Information About Storage Volumes
dbtool -volume [operation] [options] <dbname>
-info -mount
List the names, sizes, and locations of all data storage volumes associated with the specified database.
For example:
dbtool -volume -info -mount group
Volume 0:
Sysname "sysvol" Size: 131072K
Pathname "/net/vp/mvp/lang/george/versant/db/group/system"
In the above case, the database group has one data storage volume named sysvol. It is 131,072 K bytes in size and is located at:
/net/vp/mvp/lang/george/versant/db/group/system
10.10.7. -index—Working with Indexes
dbtool -index [operation] [options] <dbname>
230 Versant Server Guide
dbtool
Operations for the dbtool -index utility are described in the following sections.
10.10.7.1. Getting Information About Indexes
You can check the integrity of an index with the -check operation or get information about an index with the -info operation.
-check [ [ -name <indexName> ] <C> [<A>] ]
Verifies index consistency.
The amount of indexes can be filtered by the class name C and additionally either by its index name indexName or by an attribute name A. In case of a given attribute A, all indexes that contain the attribute were selected. C++ users specify C::A for an attribute.
Note that currently dbtool -index -check only checks whether all the records of a class can be found via the index but does not verify the opposite i.e., whether all the record addresses found via the index are still valid for that particular class record.
Running a consistency check on a database with active transactions is NOT supported and can lead to data corruptions/spurious results. For this reason, dbtool tries to ensure that the database does not have any active clients before running the consistency check. It does so by issuing a stopdb command internally. If there are active clients running on the database, the stopdb command will fail and dbtool will report this and refuse to proceed with the consistency check. Also, dbtool internally changes the database mode accordingly in order to prevent any new clients from connecting to the database while the consistency check is in progress. After completion of the consistency check, the database mode will be restored. In case the consistency check operation is interrupted for some reason, manual intervention might be needed to restore the database mode.
-info {options}
Prints index information for classes and attributes in a database.
Options for dbtool -index -info are as follows.
-list [sub-options] [ [ -name <indexName> ] <C> [<A>] ]
Lists information about the indexes in the database.
Versant Server Guide 231
dbtool
232
The amount of indexes can be filtered by the class name C and additionally either by its index name indexName or by an attribute name A. In case of a given attribute A, all indexes that contain the attribute were selected. C++ users specify C::A for an attribute.
Following is a sample output for indexes on the name attribute of class Employee in the database named db_idx.
dbtool -index -info -list Employee name db_idx dbtool -index -info -list Employee name db_idx
Type: BTREE
Class: Employee
Index Name: nameIdIdx
Properties: multi-version
Attribute Domain Length
-------------------------------------------------------------------------------name id char o_u4b
[16]
4
Number of pages: 3
Creation time: Wed Oct 15 18:45:47 2014
Located in volumes: c:/out/db64\db_idx\system/sysvol
Type:
Class:
BTREE
Employee
Index Name: N/A
Attribute Domain Length
-------------------------------------------------------------------------------name char [16]
Number of pages: 3
Creation time: Fri Oct 17 11:34:18 2014
Located in volumes: c:/out/db64\db_idx\system/sysvol
The following sub-option parameters are available for dbtool -index -info -list
-short
Print index information for all classes and attributes in a database by component. This is the same as using -list without class/attribute options, except that the display format is different. The following is an example output.
Versant Server Guide
dbtool
Type Class Index Name Attribute(s)
-----------------------------------------------------------------
BTREE Employee nameIdIdx name, id
BTREE Employee N/A name
Information that does not fit in the tabular display does not appear.
-printcommand {-create|-delete} [ [ -name <indexName> ] <C> [<A>] ]
The -printcommand option of -index -info prints the form of the -index command needed to create or delete the indexes that are present in the database. This can be useful for generating scripts (e.g., by piping the output) for performing the index create or delete operations.
The amount of indexes can be filtered by the class name C and additionally either by its index name indexName or by an attribute name A. In case of a given attribute A, all indexes that contain the attribute were selected. C++ users specify C::A for an attribute.
A few examples will help to make the operation of -printcommand clear. For the following examples, assume a database, named School with two classes, Student and Course. The Student class has a compound index on the attributes lastName and firstName. This index is named
StudentNameIndex
. The Course class has two simple indexes. One, named CourseNumberIndex, on the number attribute and one, named CourseDurationIndex, on the duration attribute.
Example—print all create index commands
The following generates a list of the commands needed to create the indexes in the database.
dbtool -index -info -printcommand -create School
This produces the following output dbtool -index -create -name CourseDurationIndex Course duration School dbtool -index -create -name CourseNumberIndex Course number School dbtool -index -create -name StudentNameIndex Course lastName,firstName School
Example—print the command(s) to delete the index(es) for the Course attribute number
Optionally, you can specify a class or a class and attribute with -printcommand. This example will produce the command(s) needed to delete the index(es) on the Course class number attribute.
Versant Server Guide 233
dbtool dbtool -index -info -printcommand -delete Course number School
The output is as follows.
dbtool -index -delete -name CourseNumberIndex Course School
10.10.7.2. Create Index
-create [options] -name <indexName> <C> <A>{,<A>}* <dbname>
Creates an index with the name indexName in the named database for the specified attribute(s)
(<A>{,<A>}*) of the specified class (<C>). For a compound index the attribute argument is a comma-delimited list (no spaces) and is limited to ten attributes.
For a given class, the index names must be unique.
In order to successfully create an index on an attribute name that contains a comma, additional quoting
(') is necessary at the beginning and end of the attribute name. For example: dbtool -index -create -polymorphic -name pairIdx "MyPair<PString,PString>"
"'MyPair<PString,PString>::_first'" db
Options for this operation are as follows.
-polymorphic
This option is used to create a polymorphic index (B-tree) for a specified attribute(s) on a specified class. A polymorphic index contains references to objects of a class as well as its derived classes.
For polymorphic indexes, indexName is limited to 23 characters.
-applyToSubclasses
This option, will create an index for the specified class as well as for all the derived classes (including their derived classes). In case that a derived class already has such an index (independent of whether it is unique or not) it will be ignored and the operation will proceed without an error.
234 Versant Server Guide
dbtool
-reapply
Together with -applyToSubclasses, this option, will create an index, if missing, for the specified class as well as for all the derived classes (including their derived classes).
-unique
This option is used to enforce unique values for the specified attribute. For a compound index, uniqueness is determined by the aggregation of the indexed attribute values.
Examples
Simple index
Create a unique simple polymorphic index, named PersonNameIdx for the name attribute of class Person in the database MyDatabase.
dbtool -index -create -polymorphic -unique -name PersonNameIdx Person name MyDatabase
Compound index
Create a unique polymorphic compound index, named AddressCityStateIdx for the city and state attributes of class Address in the database MyDatabase. The combined values of the keys (the city and state values) must be unique.
dbtool -index -create -polymorphic -unique -name AddressCityStateIdx Address city,state
MyDatabase
(Note that multiple attribute names are comma-delimited. The number of attributes in a compound index is limited to ten.)
10.10.7.3. Delete Index
Named index
-delete -name <indexName> <C> <dbname>
Deletes an index, named indexName for the specified class.
Options for this operation are as follows.
Versant Server Guide 235
dbtool
-name
Specifies the name of the index to delete.
-applyToSubclasses
This option, will delete an index for the specified class as well as for all the derived classes (including their derived classes). In case that a derived class already has such an index (independent of whether it is unique or not) it will be ignored and the operation will proceed without an error.
10.10.7.4. Load Index
Named index
-index -load -name <indexName> <C> <dbname>
To load a B-Tree index into the server buffer, where C is the class name and indexName the index name.
10.10.8. -AT—Viewing Consistency and Maintenance of AT Table
dbtool -AT [operation] [options] <dbname>
AT table related options.
Operation parameter for this utility are:
-AT -analyze
Analyzes the AT (loid2poid table) for fragmentation.
-AT -check [options]
Verifies AT table consistency.
Running a consistency check on a database with active transactions is NOT supported and can lead to data corruptions/spurious results. For this reason, dbtool tries to ensure that the database does not have any active clients before running the consistency check. It does so by issuing a stopdb command internally. If there are active clients running on the database, the stopdb command will fail and dbtool will report this and refuse to proceed with the consistency check. Also, dbtool
236 Versant Server Guide
dbtool internally changes the database mode accordingly in order to prevent any new clients from connecting to the database while the consistency check is in progress. After completion of the consistency check, the database mode will be restored. If the consistency check operation is interrupted for some reason, manual intervention might be needed to restore the database mode.
Options for -check parameter are:
-v
Verifies consistency of the AT table in verbose mode.
-alloc X
Pre-allocates space in the server process AT table for the number of entries specified as X.
This option can be used for performance tuning a large database.
-AT -info -loids [options]
Prints all the loids used in the system.
-AT -load
AT table maintenance-related options.
-load
Pre-loads the AT into the server buffer cache.
<dbname>
Database name.
10.10.9. -trace—Trace Components of a Database
You can use tracing to monitor the database server activity.
The primary purpose of tracing is to help Versant Technical Support debug your application.
Turning tracing ON will affect your performance.
Versant Server Guide 237
dbtool
Trace entries are written to a tracing log file. You can also display tracing output on stdout. You can allow concurrent threads to share the same trace file to preserve timing as much as possible.
You can turn tracing ON or OFF, and specify tracing options either with server process profile parameters or with dbtooloptions.
If you use dbtool, you control tracing while the database is running. Parameters used with dbtool will override parameters set in the server profile.
For example, if the profile sets tracing ON, you can use dbtool to turn it OFF. Options set with dbtool persist only while the database is running. When the database restarts, tracing parameters are reset to the values in the server profile.
The options that control tracing are: dbtool -trace [<options>] [<command>]
Options for this utility are:
-file <path>
To view trace records from the file specified by path.
-database <dbname>
To view trace records from the trace file associated with the specified database.
If -trace is invoked with no options parameter, dbtool will look for the trace file specified by the
VERSANT_TRACE_FILE environment variable.
Command parameter for this utility are:
-status
Lists components plus ON/OFF status.
-on [<components>]
Turn ON specified components. If no components are specified, all components are turned ON.
238 Versant Server Guide
dbtool ps sd sm net
COMP
am bf dr io
-off [<components>]
Turn OFF specified components. If no components are specified, all components are turned OFF.
-create [<entries>]
Creates a new trace file with the specified number of entries in it. If number of entries is not specified, the default of 10,000 will be used.
-view [<components>]
Displays the contents of the trace file, showing entries for the specified components. If no components are specified, then trace records for all components are shown.
-tail [-f] [-count <n>] [<components>]
Displays last <n> entries in the trace file for specified components.
If the -f option is specified, additional entries will be shown as they are created.
If the -count option is omitted, then the last 20 trace records for all components are shown.
Invoking -trace with no command parameter is the same as using the -view command.
Example:
The following is an example of the status command. Note how all components are on except net:
% dbtool -trace -database example -status
DESCRIPTION
Access Method
Buffer Manager
Dir Service
I/O Sub System
Process Manager
Storage Man SD
Storage Manager
Network Layer
ON
ON
ON
--
ON
ON
ON
ON
ON rc si tr sl
COMP
at bt hs lg
DESCRIPTION
AT Table
B-tree Manager
Hash Indexing
Log Services
Record Manager
Storage Man SI
TransactServices
System Library
ON
ON
ON
ON
ON
ON
ON
ON
ON
Versant Server Guide 239
dbtool
COMP
vsl om lk csr api
DESCRIPTION
Virtual System
Object Manager
Lock Manager
Cursor
Kernel API
ON
ON
ON
ON
ON
ON
COMP
ut qry rcv ev rpc
DESCRIPTION
Utility Services
Query Manager
Recovery
Event
RPC Messages
ON
ON
ON
ON
ON
ON
The following is another example of trace output.
Each row represents a trace record. The thread field shows the process and thread which wrote the record (no entry indicates no change from the previous line). The function field shows the name of the internal function, which wrote the record. The type field indicates the type of the trace record, such as an entry into the function or exit from the function. The data field shows additional record specific information.
% dbtool -trace -file /tmp/example.vtr -view
THEAD
26206.0001
FUNCTION
net_tcpRead rpc_tr_commit net_tcpWrite net_tcpRead rpc_tr_commit rpc_tr_beglog net_tcpWrite net_tcpRead rpc_tr_beglog om_capi_term om_capi_init rpc_tr_commit net_tcpWrite net_tcpRead rpc_tr_commit
TYPE DATA
rcvd dbid = 802, len = 16 sent dbid = 802 sent dbid = 802, len = 256 rcvd dbid = 802, len = 256 rcvd dbid = 802 sentdbid = 802 sent dbid = 802, len = 256 rcvd dbid = 802, len = 256 rcvd dbid = 802 exit api = o_xact entr api = o_endsession sent dbid = 802 sent dbid = 802, len = 256 rcvd dbid = 802, len = 256 rcvd dbid = 802
240 Versant Server Guide
dbtool
THEAD FUNCTION
rpc_discon net_tcpWrite net_tcpRead rpc_discon om_capi_term
TYPE DATA
sent dbid = 802 sent dbid = 802, len = 256 rcvd dbid = 802, len = 256 rcvd dbid = 802 exit api = o_endsession
10.10.10. -class—Get Information About All Classes in a Database
dbtool -class <operation> [options] <dbname>
Operation parameters for this utility are:
-check { <class> | all } [options]
Checks a class for consistency.
Running a consistency check on a database with active transactions is NOT supported and can lead to data corruptions/spurious results. For this reason, dbtool tries to ensures that the database does not have any active clients before running the consistency check. It does so by issuing a stopdb command internally. If there are active clients running on the database, the stopdb command will fail and dbtool will report this and refuse to proceed with the consistency check. Also, dbtool internally changes the database mode accordingly in order to prevent any new clients from connecting to the database while the consistency check is in progress. After completion of the consistency check, the database mode will be restored. In case the consistency check operation is interrupted for some reason, manual intervention might be needed to restore the database mode.
<class> all
Name of the class.
Checks all the classes.
Options for -check are:
Versant Server Guide 241
dbtool
-v
Verbose
-inst
Performs overall database consistency check and object consistency check. If an object is found in corrupted state, it prints the corresponding loid, poid, number of corrupted loids in a class and finally reports inconsistencies detected during the scan.
-info [options]
Prints information related to classes.
Options for -info are:
-list
Prints all the class names, type and cardinality.
<class>
Name of the class.
10.10.11. -dbalog—Get Information About Logging Activities
All DBA activities should be logged to the per-database configurable file LOGFILE so that the history of commands can be viewed when required. (Refer to
Section 4.2.5, “Log File—LOGFILE” pg. 51 for more
information regarding the LOGFILE.)
These activities may be those that make a physical change to a database or change the running state of a database.
dbtool -dbalog [<options>] dbname
Options for this utility are:
-setlevel <level>
This is the default option and sets the DBA logging level. The level can be either 0 or 1.
242 Versant Server Guide
dbtool
-getlevel
Prints the DBA logging level.
-setfile <filename>
Specifies the name of the file that will be used for logging.
Verify that appropriate OS permissions are given to create, modify or access the file. This file will be accessed from the database server machine.
-getfile
Prints the name of the file currently used for logging.
The following utilities will be logged and will have two entries; one marked START and the other marked
END
:
addvol createreplica ftstool checkdb dbtool habackup convertdb dropclass removereplica createdb dropinst vbackup
The following utilities will be logged and will have only one entry marked INVOKED:
dbinfo vconn comparedb expiry makeprofile vcopydb dbuser vstats polling setdbid
All the utilities that will be logged will have the CWD, PID, RUID, EUID and HOST fields.
For more information refer to
The following are a list of tools/utilities that will not be logged into the per-database configurable LOGFILE file:
db2tty itest oscp verrindx dbid ivstats removedb vstream dblist makedb udltool vtcl3g
Versant Server Guide 243
dbtool
10.10.12. -space, -AT—Get Information on Fragmentation and Free Space
The dbtool utility provides two options, -space and -AT, for determining free-space and fragmentation levels for the data segments and AT tables, respectively. These are discussed in the following sections.
10.10.12.1. Data Segments
You can use the -space option to determine the degree of fragmentation of a data segment. The use of this option follows.
dbtool -space [options] <dbname>
Prints the free space information of database volumes.
Also determines the degree of fragmentation of data segments by inspecting every page occupied in the database and appropriately advise the DBA for reorganization of data.
Options for this utility are:
-volume -files {-all |{-n <volume-name> [-n <volume-name>..]} [-verbose]
Prints the usage of files in the database and additionally (with -verbose) of the volumes.
-volume {sub-options} [sub-options]
Prints free space in volumes.
Sub-option parameters for this utility are:
-all
If this option is specified then fragmentation information for all the segments will be inspected.
-n <name>
To specify a particular segment use this option.
More than one segment name can be provided by adding more -n <name> pairs to the command line.
If the segment name does not exist, the error SM_E_SEG_NOT_FOUND will be thrown.
244 Versant Server Guide
dbtool
-class {-all |{-n <name> [-n <name>..]}} [sub-options]
Determines the fragmentation information only for the segment in which objects of any or a specified class reside. If the class name provided does not exist then the error SM_E_CLS_NOT_FOUND will be thrown.
More than one class name can be provided as follows: dbtool -space -class -n <name> -n <name> <dbname>
-fillfactor <percentage>
Specifies the percentage of bytes occupied in a page that will render a page to be considered full.
The default percentage is 70%.
-sample [-size < sample size > ]
The -sample option looks at 1000 random pages (can be changed with sub-option -size) taken as representative for all pages used by that class.
-pagespace
Prints page free space in addition to extent free space. This option can be used on its own as well as with the -verbose and -extraverbose options.
-verbose
Displays the allocation status of the pages of a segment. Pages that are empty (i.e. less than 10% utilized) will be marked E, pages that are full (i.e., more utilized than percentage specified in fillfactor) will be marked F, and other pages will be marked P to denote partially full.
-extraverbose
Displays a graphical representation of pages of segment along with fragmentation information and
PID of the pages. It prints the PID together with the fill grade character. A page id (PID) has the form: volumeid:pageid
, for example, 0:1024.
-highlevel
Specifies that information should be gathered only at the page level without examining the individual pages.
Versant Server Guide 245
dbtool
-segment {-all |{-n <name> [-n <name>..]}} [sub-options]
Determines the fragmentation information for segments of database <dbname>.
Example
Here's an example on how to check the free space available in the database named spdb.
dbtool -space -volume -all -verbose spdb
Versant Utility DBTOOL Version 9.3.0
Copyright (c) 1988-2017 Versant Software LLC
Volume 0:
Sysname "sysvol" Size: 1048576K
Pathname "/db/spdb/system"
Free extents in vol sysvol : 32714
Percentage of free extents in vol sysvol : 99%
Free extent space in vol sysvol : 1046848KB
Volume 256:
Sysname "vol1" Size: 131072K
Pathname "/db/spdb/vol1"
Free extents in vol vol1 : 4089
Percentage of free extents in vol vol1 : 99%
Free extent space in vol vol1 : 130848KB
Free extents in DB : 36803
Percentage of free extents in DB : 99%
Total available extent free space in DB : 1177696KB
10.10.12.2. AT Tables
It is also possible to determine the fragmentation level of the system tables (also referred to as the AT or liod2piod tables).
This is done with the -AT -analyze option of the dbtool utility.
The command syntax to analyze the AT tables for fragmentation is as follows.
246 Versant Server Guide
dbtool dbtool -AT -analyze DatabaseName
Here is an example call.
dbtool -AT -analyze db1
Versant Utility DBTOOL Version 9.3.0
Copyright (c) 1989-2017 Versant Software LLC
** Analyzing AT **
All AT table(s) are filled above 50% capacity. The space occupied by these tables is 24690688 bytes.
It is recommended that you run a system tables de-fragmentation when at least one of the system tables is filled to below 50% capacity. Refer to
Section 10.23, “vcompactdb” pg. 310 for information about the
de-fragmentation utility.
10.10.13. -schevol—Get Information About Schema Evolution
dbtool -schevol <command> [-force] <C> <dbname>
Displays the history of schema evolution for a class <C>. Prints the schema of each class version indicating the attributes which have been added/deleted/modified.
Options for this utility are:
-mark
Updates old class versions to indicate that they are fully evolved.
-unmark
Undo the changes done to the old class versions with the " -mark" command.
-check
Checks whether old class versions have any instances.
Versant Server Guide 247
dbtool
-info [-last <n> | -all ]
Prints the latest class version. Default will print the latest class version.
-last <n>
Prints the last n class versions.
-all
Prints all class versions.
-force
When used with "-mark" will update old class versions to indicate that they are fully evolved without checking for existing instances corresponding to them.
<C>
Class name
10.10.14. -schevol -evol—Evolve Instances to the Latest Schema
Versant works with a lazy migration strategy. In other words, it evolves instances of old schema versions to the latest schema version only when these instances are modified by database applications. This means that all instances get evolved over a certain time period depending on the access pattern.
One disadvantage of having different instances for different versions in a schema is that it can impact query performance. In this case, it is recommended that you evolve all the instances to the latest schema version to speed up the queries on this schema.
This can be achieved using the server-side, explicit instance conversion feature of Versant. This conversion can be triggered by the dbtool utility.
dbtool -schevol lists the schema evolution related options. The server-side explicit instance conversion feature is available under the -evol option.
Options for the -evol operation are:
-evol
Evolve all instances of old class versions to the latest class version.
248 Versant Server Guide
dbtool
[-fetchsize <n>]
Fetch size of an internal cursor.
[-all]
Evolve all classes. You do not need to provide a class name with this option.
[-threads <n>]
Fork N threads for evolve.
[-noprogress]
Do not show progress on the console.
[-verbose]
Show additional information, useful for debugging.
If you are not sure which schemas have multiple versions, you can use the tool in the following way: dbtool -schevol -evol -all <database name>
This tool is designed in such a way that it evolves only those instances that need to be evolved. Hence, for a large database, using -all instead of specific classnames is absolutely acceptable.
A few things to note, before using the tool:
• This tool should be used only on an offline database. There should be no active transactions running during the operation of this tool.
• Since this is an offline tool, it requires the database to be in DBA-only multi-connection mode, which can be achieved through dbinfo -d <dbname>.
• This tool can take a couple of hours on large databases. Please avoid terminating the tool forcefully.
• This tool is transactionally safe, therefore, in case of interruption, database consistency is guaranteed.
However, interrupting this operation may lead to instability of the database server.
• The tool causes a heavy load on the disk hosting the database data volumes and the log files. This is expected behavior.
Versant Server Guide 249
dbtool
• This tool needs a high number of page buffers during its operation. If it reports the error E2996
SM_E_OUTOF_CACHE_MEMORY: No BufferPool Mem Available
, you should increase the max_page_buffs parameter in the server process profile and restart the operation.
250 Versant Server Guide
dbuser
10.11. dbuser
dbuser command [options] dbname
This utility is used to list the users of a database, add or delete a user or change a user password.
You must specify the database. For a remote database, append the node name to the database name using the syntax dbname@node. You must also specify the desired command operation. The possible commands are listed below, followed by the available options.
Commands
Substitute one of the following for cmd_alternatives and options:
-list
Lists the user entries in the access list for the named database. This is the default command and need not be explicitly given.
-add
Adds a user to the access list for the named database. To add a user to a database, you must be the
DBA of the database and the database must be a group database.
Specify a user name with the -n option. Specify a password with the -passwd option. If you do not specify a password, you will be prompted for one.
You can also specify the access mode—read only or read/write—for the user with the -m option. The default is read/write access.
The -add command is also used to enable public access. Refer to
-delete
Deletes a user from the database access list. To delete a user, you must be the DBA of the database.
You cannot delete the owner of the database.
Specify a user name with the -n option.
Versant Server Guide 251
dbuser
The -delete command is also used to disable public access. Refer to
-chpasswd
Changes the password for a user. Specify a user name with the -n option. Only the database owner or DBA can change the password of other users without specifying the old password. All other users need to specify the old password for verification when changing their password. The command will prompt for the old password, as needed, and for new password. Use the -opasswd and -passwd options to supply these on the command line.
The DBA password can be changed in the following manner if logged in user is the DBA.
dbuser -chpasswd -n DBAname -passwd newpassword dbname
Options
-n username
This option is used by various commands to specify a user name. An error is raised if the given user name is already present in the database access list when using -add or if there is no such user when using -delete or -chpasswd.
-P
(public access)
When public access is enabled anyone can connect to the database, not just the users in the access list. Use the -add command with the -P option to enable public access; the -delete command with
-P
to disable public access. Do not provide a user name with the -n option when enabling/disabling public access.
dbuser -add -P dbname or dbuser -delete -P dbname
When enabling public access, you can specify the public access mode—read only or read/write—with the -m option. The default is read/write access.
252 Versant Server Guide
dbuser
-m access_mode
Sets database access mode for the user(s) specified with -n or -P. Only the database owner may modify the access privileges of other users.
Values for access_mode are as follows.
r
Read-only access.
rw
Read/write access. This is the default.
To see the current access mode of each user, use dbuser -list dbname.
-passwd password
Used with -add or -chpasswd, this specifies the new password for the user. Using this option will suppress the prompt for the password. This is particularly useful when using the command in a script.
-opasswd old-password
Used with -chpasswd, this specifies the existing (old) password for the user. Using this option will suppress the prompt for the old password when using dbuser -chpasswd. This is particularly useful when using the command in a script.
-noprint
Suppresses display message.
dbname
The database name.
Examples
• Add a user named Fred for the database named EmployeeDB.
Versant Server Guide 253
dbuser dbuser -add -n Fred -m rw EmployeeDB
Enter Fred's password:
Confirm Fred's password:
• Make the database publicDB available for public access dbuser -add -P publicDB
• Delete the user Allen from the database EmployeeDB dbuser -delete -n Allen EmployeeDB
• List the user information in the user access list for the database EmployeeDB.
dbuser -list EmployeeDB or dbuser EmployeeDB
• A database user, maybe Fred from above, can change their password.
dbuser -chpasswd -n Fred EmployeeDB
Enter Old Password :
Enter New Password :
Re-Type New Password :
254 Versant Server Guide
dropclass & dropcls
10.12. dropclass & dropcls
UNIX dropclass options [-d dbname] class1 [class2 class3 ...]
WIN dropcls options [-d dbname] class1 [class2 class3 ...]
This utility drops one or more specified classes, their subclasses and instances from the specified database; dbname
.
For a remote database, append the node name to the database name using the syntax database@node.
dropclass() drops instances of all classes which contain a link to the dropped class along with the dropped class.
The dropping of a graph of classes can be avoided by prior schema evolution and removal of the referencing attributes. The steps needed to adjust your schema when there are leaf classes which need to be removed are as follows.
1. Perform schema evolution to drop all attributes which reference the classes to be removed.
2. dropclass() on each class that has been removed in your application.
3. No further call to the SchemaTool is necessary because superclasses do not maintain a list of subclasses.
JVI and C++ Schema evolution utility provide a mode to enforce the replacement of existing classes in the case of an incompatibility between the previous definition of the class and the new one. In this case all instances of the old class definition will be deleted and the new class definition will be registered.
In Versant C++, use the sch2db -f option.
In JVI use the schema option SCHEMA_FORCE_DROP_DATABASE with the TransSession.setSchemaOption() method or the -redefine option with the TransSession.defineClass() method.
This option is not available with JDO.
Parameters for this utility are:
Versant Server Guide 255
dropclass & dropcls
options
Drops Class options.
-d dbname
The name of the database from which a class and its instances are to be dropped. The default is the database named in the environment variable O_DBNAME.
For a remote database, append the node name to the database name using the syntax database@node.
class1 ...
A list of classes to be dropped.
Options for this utility are:
The default option is:
-n
Makes no changes to the database but reports what classes would have been dropped if the -y option had been given.
Password corresponding to the user name entered in -u. This is intended for scripts so that users don't have to enter the password interactively.
For normal usage, users can just pass in the -u option and dropclass will prompt for the password.
Passwords cannot be more than 255 characters in length. Running with just the -p option without the -u option will return an error.
-u
User name to access the DB. This user has to be a valid user of the DB. You will be prompted for a password if no password is entered using the -p option. User name cannot be more than 31 characters in length. The default is to run as the OS user without any password.
-y
Drops the specified classes and their instances without asking for approval.
Interactive <default>: Ask Yes or No. (stdin must be tty)
256 Versant Server Guide
dropinst
10.13. dropinst
dropinst options [-d dbname] class1 [class2 class3 ...]
This utility removes all instances of one or more specified classes and their subclasses from the specified database dbname without changing the database schema.
For a remote database, append the node name to the database name using the syntax database@node.
Parameters for this utility are:
options
dropinst options.
-d dbname
The name of the database from which the instances are to be dropped. The default is the database named in the environment variable O_DBNAME.
class1 ...
A list of classes whose instances are to be dropped.
Options for this utility are:
-p
Password corresponding to the user name entered in -u. This is mainly intended for scripts so that users don't have to enter the password interactively.
For normal usage, users can just pass in the -u option and dropinst will prompt for the password.
Passwords cannot be more than 255 characters in length. Running with just the -p option without the -u option will return an error.
-u
User name to access the db. This user has to be a valid user of the db. You will be prompted for a password if no password is entered using the -p option.
Versant Server Guide 257
dropinst
Username cannot be more than 31 characters in length. The default is to run as the OS user without any password.
-y
-i
Interactive <default>: Ask Yes or No. (stdin must be tty)
-n
Drops the instances without asking for approval.
Instances created by any language interface can be dropped.
For example, to drop all instances of PObject and all classes deriving from PObject from the database myDB without changing the database schema: dropinst -y -d myDB PObject
To do the same thing as another valid user of the DB other than the current OS user you are logged in as: dropinst -y -d myDB -u user1 -p 1user1 PObject or dropinst -y -d myDB -u user1 PObject
This will prompt you for a password.
Makes no changes to the database but report what instances would have been dropped if the -y option had been given.
258 Versant Server Guide
makedb
10.14. makedb
makedb [options] dbname
This utility will create a database directory named dbname and based on the options given.
You must run makedb or create a database directory and the profile files manually before creating a database with createdb.
For a remote database, append the node name to the database name using the syntax dbname@node.
The new database directory is created in the database root on the specified node. The name of the directory will be the same as the name specified by dbname.
Database support files
Database support files will be created if they do not already exist. The following lists the database support files.
../.osc/dbname
An application process profile file, located in the .osc directory branching from your home directory.
This file contains operating parameters used when this database is a session database.
The operating environment for the application will be set according to the specifications in the application profile file corresponding to the session database. If no application profile is found, the application will use default environment settings.
profile.be
A database server process profile file, located in the database directory. This file contains database creation and operating parameters.
.lock
A lock file, which indicates whether or not the database has already been started.
Versant Server Guide 259
makedb
.pw
A password file is created only if the DBA authentication is done using a password-based mechanism.
The specified password is stored in this file and is accessed every time a utility that requires DBA authentication is invoked like createdb, dbinfo, vmovedb etc. If DBA forgets the password, the DBA can log as OS user into the machine, delete the password file and recreate a new password using the
utility.
The DBA authentication will not be performed in the absence of this file under any circumstances.
.dbtype
A database type file, which indicates whether this is a personal or group database.
Command options
-g
Make the named database a group database. This is the default option and need not be given explicitly.
Group databases are accessible to many users at the same time.
-p
Make the named database a personal database. Personal databases are accessible to only one application at a time.
-cpprofile db
Copies the profile file profile.be from the specified db directory to the directory for the new database.
A user can copy a database profile only if it is the owner of the database.
This option works only if both databases are on the same machine.
If only the name is used for db, rather than a full path name, the database root directory is searched.
260 Versant Server Guide
makedb
When using this option, care must be taken to ensure that the volume paths for system volume
(sysvol parameter), log volumes (physical.log and logical.log parameters) and data volumes
(datavol parameter) in the source server process profile file (the profile.be file that is being used as a reference to create the new profile.be) should not have absolute paths.
If an absolute path is specified, make sure that those paths are not referenced by any other database server process profile file (profile.be) on the same machine where the target database directory will be created. Failure to check this can result in severe database corruption and/or deleted volumes.
-nofeprofile
Does not create an application process profile.
-logging
Enables transaction logging.
-locking
Enables transaction locking.
-noprint
Does not display any messages while the command runs.
-promptpasswd
Associates a password with the DBA user to enforce DBA authentication.
The length of the password cannot exceed 255 characters. If string null is specified as the password value, the DBA will not be associated with a password.
-beprofile file
Copies the named file as a server profile file.
If the file is not specified with an absolute path, it is searched in the current working directory.
This parameter cannot be specified with –cpprofile.
Versant Server Guide 261
makedb
The makedb utility will search for the file at the specified location on the same machine where the database directory for that database is located. If the file does not exist or is not accessible, makedb will fail with the error UT_ER_MAKEDB_PROFILE_NOTFOUND. In this case, try using an absolute path.
When using this option, care must be taken to ensure that the volume paths for system volume
(sysvol parameter), log volumes (physical.log and logical.log parameters) and data volumes
(datavol parameter) in the source server process profile file (the profile.be file that is being used as a reference to create the new profile.be) do not have absolute paths.
If an absolute path is specified, make sure that those paths are not referenced by any other database server process profile file (profile.be) that is on the same machine where the target database directory will be created. Failure to check this can result in severe database corruption and/or deleted volumes.
-feprofile file
Copies the named file as a application profile file.
If the file is not specified with an absolute path, it is searched for in the current working directory.
This parameter cannot be specified with –nofeprofile and -cpprofile.
The makedb utility will search for the file at the specified location on the same machine where the database directory for that database is located. If the file does not exist or is not accessible, makedb will fail with the error UT_ER_MAKEDB_PROFILE_NOTFOUND. In this case, try using an absolute path.
262 Versant Server Guide
makeprofile
10.15. makeprofile
makeprofile [options] dbname
This utility makes application process and server process profiles for a database named dbname.
For a remote database, append the node name to the database name using the syntax database@node.
Options for this utility are:
-cpprofile db
Copies profiles from the specified db directory.
A user can copy a database profile only if it is the owner of the database i.e., only the DBA is allowed to copy profiles.
If only a database name is used rather than a full path name, the db directory under the database root directory will be used.
-nofeprofile
Does not create an application process profile.
-logging
Turns logging ON.
-locking
Turn locking ON.
-noprint
Suppress display messages while command runs.
-beprofile file
Copies the said file as a server profile file.
Versant Server Guide 263
makeprofile
If the file is not specified with absolute path, it is searched in the current working directory. This parameter cannot be specified with –cpprofile.
For 2p models, makedb will search for the file at the specified location on the same machine, where the database directory for that database is located. If the file does not exist or is not accessible, makedb will fail with error UT_ER_MAKEDB_PROFILE_NOTFOUND. The file path has to be an absolute path.
-feprofile file
Copies the said file as a server profile file.
If the file is not specified with absolute path, it is searched in the current working directory. This parameter cannot be specified with –nofeprofile and -cpprofile.
For 2p models, makedb will search for the file at the specified location on the same machine, where the database directory for that database is located. If the file does not exist or is not accessible, makedb will fail with error UT_ER_MAKEDB_PROFILE_NOTFOUND. The file path has to be an absolute path.
For example, to make profiles for myDB: makeprofile myDB
If you are recreating a database previously removed with the removedb utility, you can reuse the directories and profiles without having to run makeprofile or makedb.
264 Versant Server Guide
oscp
10.16. oscp
oscp parameter
This utility displays information about your Versant environment for the release you are using.
Options that you can substitute for parameter are:
(with examples shown for a Linux installation)
-d
Returns your Versant database root directory.
For example, the return information might be:
/versant/db
-i
Returns your Versant product version, software root path, runtime path, database root path, machine and directory containing the osc-dbid database system file, and ss.d location.
-l [@remote_host]
Returns the release level of this version of oscp. The default is the level of oscp on your local machine; to find the release level on another machine, specify the name of the remote machine using
@remote_host syntax.
-r
Returns your Versant software root directory.
For example:
/usr/local/versant
Versant Server Guide 265
oscp
-p
Returns your run time path (the software root plus the release and platform directories).
For example:
/usr/local/versant
-v
Returns your Versant version number.
-n
Prints the machine containing the osc-dbid database system file.
-o
Prints the directory containing the osc-dbid database system file.
266 Versant Server Guide
removedb
10.17. removedb
removedb [options] dbname
This utility stops the database if it is running, destroys and removes all volumes of the database dbname, and deletes the database from the system database identifier file osc-dbid.
For a remote database, append the node name to the database name using the syntax database@node.
Options for this Utility are:
-f
Forcibly stops and removes the database immediately even if it is currently running and other users are connected to it.
Without the -f option, the database will not be removed if it is in use by an active transaction. If it is in use, the message Database in Use will be printed and removedb will be terminated.
-rmdir
Removes the database directory and all files in it as well as the database.
-noprint
Suppresses display messages while running.
The utility gets user confirmation before starting the removal procedure. Key in y to continue with the removal of database or any other character or enter will be treated as No. If you use –f option to remove the database, then the database will be removed without confirmation.
The database system osc-dbid file must be visible from your machine before you run removedb. Only the owner of a database can remove it. If the database is authenticated using the password-based mechanism, then the DBA password should be provided.
When you remove a database, all volumes associated with the database are removed. This includes any extra storage volumes that have been added after the database was created. However, the database directories, profiles and password file are not deleted when you run removedb unless you specify -rmdir. If you do not delete the directories and files, you can recreate a removed database using the same directories profiles and password if any. If you delete database directories manually
Versant Server Guide 267
removedb but do not run removedb, the database numerical identifier and information about the old name and path remain in the osc-dbid database system file. Also, if you delete the database directories manually, shared memory will not be removed.
If you accidentally delete database files manually and now want to remove the database information from the osc-dbid file, use the command: dbid -d mydb
It is recommended to use the above command only in the mentioned circumstances.
Examples: removedb my_db removedb -f my_db removedb -rmdir mydb
268 Versant Server Guide
setdbid
10.18. setdbid
setdbid dbid dbname
This utility sets the database identifier of a specified database to a specified value.
This utility references the machine where the osc-dbid file is located, opens the osc-dbid file, and changes the entry associated with dbname to dbid. It also changes the value of the identifier in the database itself. It does not change the logical object identifiers of objects already defined in the database.
If DBA authentication has been enforced on the database, the user will be prompted for a DBA password.
Calling setdbid stops the database. If implicit database start is disabled (the database server process profile parameter allow_implicit_startdb is set to false, refer to
an explicit startdb will be required before applications are able to continue working with the database.
Parameters for this utility are:
-noprint
Suppress display messages.
dbid
New database identifier number.
It is critical that the specified identifier must not have been used previously.
To find the current database identifiers of existing databases use the dblist utility.
Also use dbtool -AT -info -rootpages to see all database identifiers currently used inside the database.
If you plan to copy, move or stream objects from other databases into this database you must perform the dbtool -AT -info -rootpages check on all these databases and ensure that none of those contains the new database identifier.
dbname
Name of the database.
Versant Server Guide 269
startdb
10.19. startdb
startdb dbname
This utility starts the database dbname.
For a remote database, append the node name to the database name using the syntax database@node.
Before starting a database that has password-based DBA authentication implemented, the user will have to provide the DBA password when prompted.
Example:
startdb my_db
If the database was previously interrupted during a transaction, starting the database will automatically start a database recovery process.
For information on how to start a database without recovery from interrupted transactions, contact
Versant customer support.
Using the Versant database system typically involves the following basic actions.
1. Start the databases that will be used by the application.
2. Start a session in a database.
3. Optionally connect to one or more additional databases.
4. Disconnect from the databases. Disconnecting from a database will not stop it.
5. End a session. Ending a session will not stop the session database.
6. Optionally stop the databases.
Starting a database with startdb creates an operating environment, performs any necessary recovery and cleanup operations and prepares the Versant Manager and Versant Servers for access.
270 Versant Server Guide
startdb
Explicitly starting a database is normally not required. By default, an attempt to connect to a database causes an implicit startup of that database. An explicit startup may be preferred since subsequent client connections need not wait for startup. Also, explicitly starting the database allows you to monitor the startup. Implicit database startup can be disabled in the profile.be file using the allow_implicit_startdb parameter. By default, allow_implicit_startdb is on. Sretting this parameter to off ensures that the database is started only by explicitly calling startdb.
To begin or end a database session and to make or break a connection to a database, use language specific interface routines from within an application. To stop a database explicitly, use the stopdb utility.
After a crash, a startdb failure may not get reported on the screen and may have to be read from the
LOGFILE in the database directory.
A startdb failure will also be indicated by the absence of the vserver process.
During execution of startdb you may see the following message:
Init SDA failed...
This means that the system does not have enough shared memory. Either increase system swap space, reduce the server process heap size, or stop some other database.
10.19.1. Required Database Files
Each Versant database is made up of a number of files contained in a database directory. In order for a
Versant database to successfully start up, all of the required files need to be present in the database directory and these files must be accessible by the DBA user. Database file issues may be indicated by one of the following errors: E6, E133, E7001, E7003, E7034, E7054, E7093.
The required files are listed, for each operating system, in
Table 10.2, “Versant Database—Required
The volume entries are the database volumes, the storage units for the database. If no volumes have been added, there will be only the system volume with the default name system. Additional volumes have names that are chosen by the Database Administrator when the volume is added (refer to
Versant Server Guide 271
startdb
Table 10.2. Versant Database—Required Files
Operating System
Windows
Unix
Required Files in the DB Directory
volume(s)
(see
) group.flg
lock physical.log
logical.log
profile.be
sharemem systrace vbackup
LOGFILE
volume(s)
(see
)
.dbtype
.lock
physical.log
logical.log
profile.be
.sharemem
.systrace
.vbackup
LOGFILE
10.19.2. Application Failure
If an application terminates abnormally and you are running with logging turned off, you will probably have to reset the database. This is because with recovery features turned off, Versant does not have the necessary information to restore the database to a consistent state.
10.19.2.1. Reset the Database
1. Run the stopdb utility.
2. Restart the database with startdb.
If logging and recovery are turned ON, then the next time you try to use the database, Versant will automatically rollback all incomplete transactions that may be corrupting the database and restore conditions to a consistent state.
272 Versant Server Guide
startdb
Versant uses shared memory and semaphores for its inter-process communications. If an application does not finish normally, shared memory resources may not be released.
10.19.2.2. Release Shared Memory
1. Run the stopdb utility.
2. Restart the database with startdb.
3. If step 1 does not succeed, you will have to forcibly stop the database. The stopdb -f option should be used with caution. For further information on how to forcibly stop a database, call Versant Customer
Support.
You can use the Linux ipcs command to verify that all shared memory and semaphores have been released.
10.19.3. Monitoring Database Startup
In most cases, the database startup procedure completes quickly, in less than a second. However, if a database recovery needs to be performed (because the database was improperly shut down and there are recovery log records) or if there are port conflicts (the ports used by Versant Server as specified in the VERSANT_SERVER_PORTS environment variable are in use), database startup can take significantly longer.
You can monitor the progress of the database startup using the dbtool -trace command. This displays the messages in the named database systrace file.
dbtool -trace -database DatabaseName -f
(The -f option will wait for and display additional messages as they are appended to the systrace file.
This is analogous to the operation of the Linux tail -f command.)
The following lists trace messages of interest when monitoring the progess of startdb.
1. ut_startdb info vserver starts on HostName
The first message indicating a starting vserver process
2. ut_startdb info Beginning physical recovery phase
Recovery has begun
Versant Server Guide 273
startdb
3. ut_startdb info Ending physical recovery phase
4. ut_startdb info Beginning logical recovery phase
5. ut_startdb info Ending logical recovery phase
Recovery is complete
6. ut_startdb info still waiting for all service threads being intialized
This entry indicates that the wait for internal service threads is greater than five seconds. This is most likely caused if the ports specified by the VERSANT_SERVER_PORTS environment variable are in use.
6.a. LegacyConnector info legacy connector is looking for a port
The legacy connector thread is seeking an open port (refer to
for a list of Versant Server processes and threads)
(If legacy client support—connection support for Versant clients based on release 9.1, 9.0 or
8.0.2—is not needed, the legacy connector thread can be disabled. Refer to
7. LegacyConnector info legacy connector will listen on port NNN
The legacy connector thread is using the specified port
8. ut_startdb info vserver is entering main loop
“The database has been successfully started.” (This message is also written to the database LOGFILE.)
The startdb command should have returned successfully.
Terminating a database startup
• On Linux, if the message ut_startdb info vsignals thread is up and ready has been sent, you can terminate the database startup by sending a TERM signal to the vserver process.
• A stopdb call is not processed until the database has started.
• Calling startdb a second time has no effect on an ungoing database startup.
274 Versant Server Guide
stopdb
10.20. stopdb
stopdb [mode] [-noprint] dbname
This utility stops the database specified by dbname and cleans up all database resources in memory. For example, the following command will attempt to stop the database named MyDatabase.
stopdb MyDatabase
For a remote database, append the node name to the database name using the syntax database@node.
To stop a database, you must be the user who started it, and thus the owner of its shared memory. The
stopdb
utility will prompt for the password for databases that use password-based DBA authentication.
-noprint
You can suppress all display messages while stopdb is running using the -noprint switch.
Operation
By default, the database is not stopped if it is in use by any application. If there are any connections to the database, the stopdb utility immediately terminates. The message Database in Use is written to the console (if not using -noprint). By specifying a stop mode, you can override the default bahavior. For example, stopping the database only after waiting for on-going transactions to complete. The available stop modes are described below.
The stopdb command will return with 0 (zero) when the database is successfully stopped or with an appropriate error code if there were any problems.
For certain stopdb stop modes, the command may take some time waiting for ongoing operations to complete. You can detach the console from the stopdb call with ctrl+C but the command continues to run. For all stopdb calls except a forced stop (with stopdb -f), an internal timeout insures that the command will return within 300 seconds with the code UT_SHUTDOWN_NOT_COMPLETED. Again, this does not imply that the stopdb operation has halted. The command continues to run.
You can see whether the command has completed by monitoring the system processes, checking for the vserver process. You can also call the same stopdb command again (with the same stop mode). Calling the same command again will not affect an ongoing command.
Versant Server Guide 275
stopdb
You can also try calling stopdb with a stricter stop mode. This may stop the database sooner. To stop the database immediately, call stopdb -t or, as last resort, stopdb -f.
stopdb stop modes
-st
Wait for active transactions to complete and then stop the database. Using stopdb with this option will not wait for detached XA transactions. If you attempt to start a new transaction while stopdb
-st
is waiting, the system returns the error SM_TR_XACTS_BLOCKED to the application.
Once all transactions have completed, all client connection sockets to the database are closed and an internal database checkpoint is performed. No recovery phase is needed when the database is re-started.
-s
Wait for active updates—remote procedure calls/RPCs that modify the database—to complete.
Non-modifying RPCs are ignored. New updates are blocked. If you try to start a new update while
stopdb -s
is waiting, the system returns the error SM_TR_NEW_UPDATES_BLOCKED to the application.
When modifying RPCs have completed, the database is stopped as with a call to stopdb -t, described below.
-t
With this mode (and with stopdb -s, once write operations have completed), all client connection sockets to the database are immediately closed. An internal database checkpoint is performed and any active transactions are internally rolled back (refer to
Using stopdb -t (or stopdb -s) will likely require that the database perform a recovery operation when re-started.
-f
Immediately and forcibly stop the database. Pending changes are not written to the database. The
stopdb -f
call will return when the database is stopped. This can take up to approximately ten seconds in some situations.
When using stopdb -f, a BlackBox snapshot is created when the database is stopped. (Refer to
Section 10.22, “vbbadmin ” pg. 305.)
276 Versant Server Guide
stopdb
The database will need to perform a recovery phase (to bring the database to a consistent state based on the database log files) when re-started.
The -t stop mode should be used to quickly stop a database. Use the -f mode only as a last resort.
Contact Versant customer support if stopdb -f is frequently required.
Versant Server Guide 277
vbackup
10.21. vbackup
vbackup [options] command
This utility manages database backup, restore, and roll forward archiving operations.
The purpose of the vbackup utility is to allow recovery from a device failure or from accidental deletion of data.
Versant incremental backup (vbackup) strategy consists of three different backup levels:
Level 0
Performs a full backup
Level 1
Backs up all changes made since the last Level 0 backup.
Level 2
Backs all changes made since the last Level 0 or Level 1 backup, whichever was most recent.
As database size increases, it becomes more important to set the level in a way, which minimizes backup size and time.
Roll-forward (RF) archiving is another feature that preserves logical log records generated by a database during normal operation in a log archive. These records can be replayed on the database during recovery.
RF archiving makes it possible to recover a database to its state just prior to the crash.
If you use only the backup and restore features, you can recover to the point of the last backup. But if you also use the roll forward features, you can recover to the point of the last committed transaction.
The vbackup command line and documentation, use the term tape for referring to the backup device.
Please note that the backup device can either be a tape drive or a normal file. Hence the term tape applies to both a tape and/or a file whichever is being used for the backup.
For example, the recoverable error message end of tape means end of file when the backup device used is a file.
278 Versant Server Guide
vbackup
Command Parameters for this utility are:
Command
-backup
-restore
-rename
-overwrite
-off
-log
-info
-list
-resume
Description
Backsup a database.
Restores a database.
When used with -restore, restores to a renamed database.
When used with –restore and -rename, overwrites additional data volumes of restored database.
Disables roll forwarding.
Start roll forward archiving.
Lists the set of backups and roll forward archives necessary to restore databases to their most recently backed up state.
Lists the backup and roll forward files stored on a backup device or file.
This parameter requires use of the -device option parameter.
When used with -restore, it resumes a suspended restore procedure.
Options Parameter for this Utility are:
Options
-level
-device
-device1
-device2
-noprompt
-position
-capacity
-blocking
-comment
-rollforward
-aggression
-script
-getbeprofile
Description
Specifies incremental level of backup.
Specifies the backup or restore device.
Specifies the backup or restore device for the next incremental level.
Specifies the backup or restore device for the last incremental level.
Suppresses all interaction with the user in combination with -restore.
Specifies position on tape for backup or restore.
Specifies tape capacity.
Specifies number of bytes to read or write at a time.
Specify a comment to be associated with a backup.
Enables roll forward archiving during backup.
Specifies buffer flushing interval.
Specifies a script from which to run vbackup.
Extracts the server process profile file profile.be from backup device or file. This parameter requires use of the -list command parameter.
Versant Server Guide 279
vbackup
Options
-odir
-startsync
Description
Specifies the directory location to extract the server process profile file profile.be
.
This parameter requires use of the -list command parameter.
When FTS is on and when used with -backup, the appropriate restore
(the restore that restores the database that has been backed up with the
-startsync option) will start the synchronization after the restore has completed.
10.21.1. vbackup Usage Notes
• To use vbackup on a database, you must be the DBA who created the database.
• To use vbackup on databases authenticated with password-based mechanism, you must specify the
DBA password for all involved databases.
• If a database device is completely demolished, you can recreate the database directories on another device with makedb and then use vbackup to both create and restore the database in one step.
• If the recoverable errors device not ready or end of tape are encountered, you will be given a chance to correct the error and resume the backup or restore. Except for these recoverable errors, backups are not interactive and can therefore be called from a script.
• For options and commands, it is not necessary to specify the full flag as long as enough is specified to be unambiguous. For example, you can shorten -device to any of the following: -device, -devi,
-dev
, -de, or –d; similarly you can shorten -device1 to either of the following: -dev1 or -d1 and you can shorten -device2 to either of the following: -dev2 or -d2.
• You can use vbackup either in interactive mode (default) or in non-interactive mode (refer to
(noprompt) Non-Interactive Mode pg. 294). However, not all of the functionality is available in the
non-interactive mode.
• For vbackup, the blocking option cannot be used with restore.
vbackup does not support multi threaded applications.
280 Versant Server Guide
vbackup
10.21.2. Command Parameters
This section provides detailed information on command parameters for the vbackup utility.
(-backup) Backup Database
-backup [options] dbname1 [dbname2 ...]
To backup one or more local or remote databases specified as dbname.
Use dbname@host syntax to specify a remote database.
Usage Notes
You can backup multiple databases to a single tape drive or to a single file.
Database backups can be online, which means that a database can be backed up while it is being used. Backups can also be incremental, which means saving only changes made since the last backup, or full, which means saving the entire database.
If multiple databases are backed up with a single command, the first one will be stored in the position specified in the position parameter (see the option parameters below) and any additional back ups will be appended after it.
A database backup saves the results of all transactions committed at the time vbackup is invoked.
For additional safety, you may want also to use the -rollforward option in conjunction with the -backup command. This will ensure that no log records are discarded unless they have been archived, either with another backup or as a result of roll forward archiving with the -log command.
For example, to backup a database named group to the file /tmp/level0 and also turn roll forwarding on: vbackup -dev /tmp/level0 -rollforward -backup group
For this example, you will see the output as (the version number actually shown will match your release number):
Versant Utility VBACKUP Version 9.3.0
Copyright (c) 1989-2017 Versant Software LLC
Versant Server Guide 281
vbackup
Backing up database 'group' to device '/tmp/level0':
0% 50% 100%
| | | | |
........................................
Backup has completed successfully.
(-startsync) Backup database and start polling
vbackup -dev <backup device> [<options>] -startsync -backup <dbname>
This option is used with the Versant FTS fault tolerant server addon module. It allows you to use the backup to restore a replica database.
Using the -startsync option with V/FTS is described in detail in Section 3.4, “Restoring a Replica
Pair Database” in the Versant FTS User's Guide .
(-restore) Restore Database
-restore [options] dbname1 [dbname2 ...]
Restores one or more local databases specified as dbname.
Invoking -restore will immediately stop the specified databases (if running) and set them to dba/single-connection mode.
After the restore is complete, the database mode of the specified databases will be set to multi-user mode.
Before the restore begins, you are given an opportunity to save the current log files so that you can roll forward to the most recent committed transaction.
The first restore done must always be a level 0 restore.
Once this restore has successfully completed, you will be asked if you want to do an additional level restore or if you want to quit. If you answer YES - to do another restore, you can insert a tape with any level 1 or level 2 backup which is incremental to the level 0 which you just restored.
Before invoking the restore command, you must first locate the backups which you will be restoring.
If the database no longer exists, you must use your own records to determine the required backups.
If the database is intact and you are restoring because you have accidentally deleted important data,
282 Versant Server Guide
vbackup you can use the -info command to list the backups necessary to restore to the most recently backed up state.
Once you know what your backups are, you must next locate the tapes on which they are stored.
The -list command can be used to verify the presence and position of the backups on the tape.
If roll forward archiving was ON when the last backup was created, after you have restored from the backup tapes, you will be asked to insert the roll forward backup tape with the appropriate sequence number.
You will also be asked for a safe location to which the current database logical log file can be copied so that it is not overwritten during the restore.
You will be asked to insert successive roll forward backup tapes until you have no more backups to restore. At this point, type quit to exit.
Failure Conditions in Restore
When a restore starts, vbackup first copies the existing log file to a backup file name _backup_.log.
If you encounter a failure during the restore operation, you need to copy the backup file to your logical log file, which is by default named logical.log.
After doing this, you can retry to restore the database. If you do not copy the backup file to your logical log file before repeating a restore, you may lose the changes made by all recent committed transactions.
For example, to restore the database group from the file /tmp/level0: vbackup -dev /tmp/level0 -restore group
The following is a sample of the interactive dialog and output you will see during a restore.
Versant Utility VBACKUP Version 9.3.0
Copyright (c) 1989-2017 Versant Software LLC
Restoring database 'group' from device '/tmp/level0':
During roll forward, would you like to apply records from the database's current log file in addition to any archived records ? [default = yes ]
This logical log file must then be copied to a safe location so it is not overwritten during the restore.
Enter the path of the logical log [ default = '/versant/
Versant Server Guide 283
vbackup db/group/logical.log' ]
Enter the path for storing the copy [ default =
0%
| |
'/versant/db/group/_backup_.log']
50%
| |
100%
|
........................................
Restore has completed successfully.
Would you like to do another level of restore on database 'group'? [ default = no ]
Current settings are: device = '/tmp/level0' position = 'current' capacity = 'dynamic' blocking = '10 Kilobytes'
Insert log archive #1 of database 'group'. [?=help] dev /tmp/log0
Current settings are: device = '/tmp/log0' position = 'current' capacity = 'dynamic' blocking = '10 Kilobytes'
Change additional settings or type <return> to proceed. [?=help]
Current settings are: device = '/tmp/log0' position = 'current' capacity = 'dynamic' blocking = '10 Kilobytes'
Insert log archive #2 of database 'group'. [?=help] quit
After you have verified that the database was successfully restored, remember to remove
'/versant/db/group/_backup_.log'.
At this point when you quit, Versant will apply all log records in the file _backup_.log to the database.
If an error occurs and you cannot complete the restore and/or roll forward, before trying again, replace your logical log file with the _backup_.log file.
(-rename) Restore and Rename database
-restore [options] dbname -rename dbnameNew
284 Versant Server Guide
vbackup
Restores the database specified as dbname to the database name specified as dbnameNew.
For example, suppose you have done the following:
1. Backed up a database named db1 to a file named db1.0.
2. Used the makedb command to create database profile files and a database directory for new database named db1new.
The server process profile file, profile.be, can be edited to add absolute paths for volumes to be restored or can be copied from another database. In this case please make sure that the absolute paths used for the database volumes are not referred by any other database's server process profile file, profile.be, that is on the same machine on which the target database directory will be created. Failure to check this can result in severe database corruption and/or deleted volumes.
Now, suppose you invoke the following command: vbackup -dev db1.0 -restore db1 -rename db1new
When you execute this command, a database named db1new will be created using the profile file parameters as if you had invoked createdb manually, and initialized with the contents of the backed up database db1.
It is essential that the restored, renamed database has a different database identifier than the original database. Accordingly, if an entry for the new database name is found in the osc-dbid system file and the entry has the same identifier as the original database, an error will be returned.
To ensure that the renamed database has a unique identifier, you can delete any existing entry with the command: dbid -d db1new
Versant FTS
This command is especially useful if you are using the V/FTS fault tolerant server addon module and want to perform an online recovery after a replica database has failed.
For more information, refer to the description of the Section 3.4, “Restoring a Replica Pair Database” in the Versant FTS User's Guide utility.
Versant Server Guide 285
vbackup
Usage Restriction:
The restore rename utility affects only one database at a time.
(-overwrite) Restore, rename and overwrite
-restore [options] dbname -rename dbnameNew -overwrite
Restores the database specified as dbname to the new database specified as dbnameNew and overwrite existing database volumes of restored database, with corresponding volumes of rename database.
For example, suppose you have done the following:
1. Backed up a database containing additional database volume at location $TMP/vol1 to device dev1
.
2. Used the makedb command to create database profile files and a database directory for new database named db1new.
Now, suppose you invoke the following command: vbackup -dev db1.0 -restore db1 -rename db1new
For this restore process, the following Versant Error Message will be raised:
UT_ER_DATAVOL_ALREADY_EXISTS
.
The user will be cautioned by vbackup restore command and prevent overwriting of additional data volume at location $TMP/vol1.
Now, suppose you invoke the following command: vbackup -dev db1.0 -restore db1 -rename db1new -overwrite vbackup restore command is issued to overwrite data volumes of restored database with those of renamed database.
If the restored database has volumes at absolute paths, then please make sure that those paths are not referred by any other database server process profile file (profile.be) that is on the same machine on which the target database directory will be created. Failure to check this can result in severe database corruption and/or deleted volumes.
286 Versant Server Guide
vbackup
Usage Restriction
Only one database name can be specified as an option to rename if the –overwrite option is to be used.
If more than one database names need to be specified, -overwrite will need to be specified explicitly for each vbackup command.
For Example: vbackup –dev db2.0 –restore db2 –rename db2new –overwrite vbackup –dev db3.0 –restore db3 –rename db3new –overwrite vbackup –dev db4.0 –restore db4 –rename db4new –overwrite
10.21.3. Warm standby (Incremental Restore)
The Warm Standby or Incremental Restore, strengthens Versant's high availability capabilities.
This feature is used as an incremental roll forward recovery. It is designed to minimize the downtime in an emergency event, which requires a database recovery.
To achieve this, an up-to-date copy of the primary database needs to be maintained, this is the Warm
Standby database. In the case of an emergency event, this Warm Standby database can be updated very quickly to the state of the primary database by applying the last roll forward archive plus the logical.log
of the primary database, rather than starting a full database restore which may take considerable time with larger databases.
Features:
The purpose of Incremental Restore is:
• Whenever the restore process requests a new roll forward archive file, the restore process can be interrupted by a suspend (rather than a quit).
• Whenever the restore process gets suspended, the restore process can be resumed again by applying the next available roll forward archive files and/or the logical.log file.
Versant Server Guide 287
vbackup
• Between the suspend and resume process, the database is in restore suspended mode. In this mode the database is not able to be started, or only the vbackup -resume is allowed to start and access this database.
• In the case of an emergency the restore process needs to be resumed with the last roll forward archive file(s) and/or the logical.log of the primary database in order to have the last transactions recovered in the Warm Standby database that is now ready to be used as the new primary database.
For more information refer to
Chapter 9, Incremental Restore and Warm Standby pg. 181.
(-log) Start Roll Forward Archiving
-log dbname1 [dbname2 ...]
Starts writing log records for the specified databases to the roll forward archive file.
Roll forward logging requires its own ongoing process. This means that the command line will not return after this command is invoked until <Enter> is pressed a second time. Pressing <Enter> a second time will exit the logging process, which has the effect of suspending roll forward logging, which means that log entries will continue to accumulate changes without being written to archive files.
While running, the roll forward process will report any errors, which occur while writing to the archive tape or file. If the tape fills up, logging will be suspended, and you will be asked to insert a second tape.
You do not have to backup with the -backup command and the -rollforward option before using the -log command, although that is the recommended sequence. You can backup with the roll forward option and start roll forward archiving in either order, but you must do both in order to ensure that all database changes are archived and that you do not overflow your log files.
You can use the -log command to start roll forward archiving on a remote database. To specify a remote database, use the syntax: dbname@node.
For example, to start writing log records for a database named group to the file /tmp/log0: vbackup -dev /tmp/log0 -log group
For this example, the following output will be seen (the version number actually shown will match your release number):
288 Versant Server Guide
vbackup
Versant Utility VBACKUP Version 9.3.0
Copyright (c) 1989-2017 Versant Software LLC
Press <return> when you are ready to exit.
Archiving log records to device '/tmp/log0':
Database 'group' is now being archived.
(-off) Stop Roll Forward Archiving
-off dbname1 [dbname2 ...]
Turns roll forward archiving off for the specified databases, which means that log records will not be written to the roll forward archive and may be discarded when the log file space is reused.
By turning roll forward archiving off, the roll forward archive chain gets interrupted. For example, at restore time you can restore the database only up to the point when you turned roll forward archiving off.
To turn roll forward archiving on, perform a backup with the -rollforward option.
Only together with that backup can the archive files restore the database up to the last transaction or up to the point when roll forward has been switched off.
(-info, -list) Backup Info
-info
-info dbname1 [dbname2 ...]
Shows information about the last backup that has been made for that database and about the log archiver state, whether a roll forward archiver is running or not. If one is running the roll forward archiver, it will show the number of the currently running archive.
Backup information for database `test1':
Level 0 backup made on `Tue May 23 17:11:46 2006'.
Done
Currently archiving logs to file #57 via connection 289.
Versant Server Guide 289
vbackup
-list
vbackup -dev <device> -list
List the backup and roll forward files stored on a backup device or file.
Before restoring from a tape, it is common to use this command to list the contents of the tape or tapes from which you plan on doing the restore. This allows you to verify your records and to be sure that the backup files you are about to use are really on the tapes and in the positions where you believe they are.
List entries have the following format: position <position>: 'label' volume <volume> blocking <blocking>
'comment'
Where:
position
The position of the file on the tape, where 0 is the first file.
label
The label of the file.
volume
The volume number for the case where a backup spans multiple tapes. The first volume is
0
.
blocking
The blocking factor that was used during backup on the device or file.
comment
The comment, if any, that was entered when the backup was made.
The format of a backup file label is:
290 Versant Server Guide
vbackup db_name -- level backup_level backup of date-time
Where:
db_name
The name of the backed up database.
backup_level
The level of the backup.
date-time
The date and time the backup was made.
The format of a roll forward archive label is:
Logs from date-time: db1 #file-no1 [ db2 #file-no2 ...]
Where:
date-time
The date and time archiving started.
db1 ..
The database that is being monitored.
file-no ..
The roll forward archive file sequence for the corresponding database.
Examples:
• vbackup -dev /backup/test1.bak -list
Versant Utility VBACKUP Version 9.3.0
Copyright (c) 1989-2017 Versant Software LLC
Listing Versant files on device `/backup/test1.bak':
Versant Server Guide 291
vbackup position 0: `level 0 backup of test1' volume 0 blocking
`10 Kilobytes'.
Done.
• vbackup -dev /backup/test1.rf1 -list
Versant Utility VBACKUP Version 9.3.0
Copyright (c) 1989-2017 Versant Software LLC
Listing Versant files on device `/backup/test1.rf1': position 0: `Logs from Tue May 23 17:16:29 2006: test1 #58' volume 0 blocking `10 Kilobytes'.
Done.
10.21.4. Options Parameters
The following section describes in detail the options parameters.
You can substitute zero or more of the following options.
(-level) Backup Level
-level [ 0 | 1 | 2 ]
The incremental level of backup to perform, either 0, 1, or 2. The default value is 0.
This option is only available with the -backup command.
The level options mean:
The default option is:
level 0
Perform a full backup.
level 1
Back up all changes made since the last level 0 backup.
292 Versant Server Guide
vbackup
level 2
Back up all changes made since the last level 0 or level 1 backup, whichever was most recent.
The most recent set of backups can be viewed with the -info command. When a database is small, there is no problem with saving its entire state every time it is backed up, but as database size increases, it becomes more important to set the level in a way which minimizes backup size and time.
(-device) Backup Device
-device device_name
The backup device on which to read or write.
The backup device can be either a tape drive or a normal file. If this argument is not set, it will default to the value of the tape environment variable.
To specify a remote device, use the syntax host:device. A remote device will be accessed using the rsh and rmt programs. Since rmt is used, remote devices are supported, but not remote files.
If you backup to a tape, you should only use non-rewinding tape devices.
On Windows, the default tape device name for SCSI tapes is \\.\TAPE0. See the notes for the Windows utility vtape for more information on device names.
(- device1) Next Incremental Level Backup Device
-device1 device_name
The backup device from which the next incremental level (1 or 2) can be restored, after the level 0 restore has completed.
This option is only available with the -restore command.
Note, that the position will remain the same as that for the level 0 restore. If this argument is not set with the restore command, the user will be prompted for a device, unless the -noprompt option has also been set. In the latter case, the restoring process will complete after the level 0 restore.
Versant Server Guide 293
vbackup
(- device2) Last Incremental Level Backup Device
-device2 device_name
The backup device from which the last incremental level (2) can be restored, after the level 0 restore and the level 1 restore have completed.
This option is only available with the -restore command.
With this option you may specify a level 2 backup, but only in combination with the -device1 option specifying a level 1 backup.
Note, that the position will be remain the same as for the level 0 and the level 1 restore. If this argument is not set with the restore command and with the -device1 option, and a level 1 backup is specified, then the user will be prompted for a device with a level 2 backup, unless the -noprompt option has also been set. In the latter case, the restoring process will complete after the level 1 restore.
(- noprompt) Non-Interactive Mode
-noprompt
In combination with the -restore command, -noprompt suppresses all interaction with the user.
With the -device1 and the -device2 options, you may specify devices from where to restore backup files of the next incremental levels. If these options are not set, the restore process will finish after the level 0 restore has completed. In any case with -noprompt set, no log records from log archives or an existing logical logfile will be applied.
(-position) Backup Position
-position tape_position
The position on the tape where the backup file should be read or written. The default is the current position.
Specify tape_position as:
294 Versant Server Guide
vbackup
number
A non-negative number. The first position on the tape is 0, the second is 1, and so on. If you are using a file for the backup, the only valid position is 0.
current
Use the keyword current to use the current position of the tape.
append
Use the keyword append to write after the last file on the tape.
Different tape drives have different capacities. If you want to put two backups on the same tape and your tape drive cannot do random positioning, then use append for the second backup on the same tape.
Versant uses standard operating system input/output control for positioning tapes, but individual device drivers may vary in their support. Positioning to the beginning of a tape or appending to the end are the most universally supported operations.
See the Release Notes for your platform, which may describe limitations on tape positioning.
(-capacity) Backup Tape Capacity
-capacity tape_capacity
The maximum number of bytes to write to the tape before requesting a second volume.
The purpose of this parameter is to ensure that the database backup is done on several smaller devices rather than one large device.
On UNIX machines and on NTFS, large files of up to a size 64GB are supported. FAT32 allows file sizes of up to 4GB.
Specify tape_capacity as:
number
A number with memory units.
Versant Server Guide 295
vbackup
The default unit is megabytes, alternatively, you can specify by bytes, blocks, kilobytes, megabytes, or gigabytes. Units can be abbreviated. For example, -cap 1.2g means 1.2 gigabytes.
dynamic
This is the default option.
Use the keyword dynamic to trust the device to detect the end of the tape without losing any information. However the capacity used when restoring from a backup must be the same as the one which was used during the backup.
The following call from vbackup will fill the given backup device with 1024MB and will then prompt for the next device in order to proceed further.
vbackup -dev backup_1 -cap 1024M -backup mydb
You can automate the vbackup process by using an input file: vbackup -dev backup_1 -cap 1024M -backup mydb < input.txt
Do not forget the empty lines in the input file in order to simulate the <return>.
(- blocking)Backup Blocking
-blocking blocking_param
The number of bytes to read or write at a time. The default is to query the device for an optimal value.
Specify blocking_param as: optimal
This is the default option.
The special non-numeric value optimal can be used to query the device for the value which it believes is optimal, which is the default. This is a good starting point, but if tape I/O is slow or there are other problems, you may want to increase this value for better throughput.
296 Versant Server Guide
vbackup
number
A number with memory units.
If only a number is specified, then the default unit of blocking is a Block and has a size of 512 bytes. This memory unit can also be specified in terms of bytes, kilobytes, megabytes, or gigabytes. Units can be abbreviated. For example, -block 63k specifies 63 kilobytes.
Depending on the device, this value may be subject to certain restrictions. For example quarter inch cartridge tapes often require the blocking to be a multiple of 512 bytes.
Whatever blocking was used to make a backup must also be used when restoring from that backup.
(-comment) Backup Comment
-comment backup_comment
Associate a comment with a backup. The default is no comment.
This option is utilized only with the -backup command and will be ignored when used with other commands. The comment specified will be stored with the backup and in the database and will appear when information about the backup is listed with the -list or -info commands.
A comment is useful for specifying the name or label of the tape on which the backup was made.
When providing a comment, it is a good idea to enclose the comment string with single quotes. This prevents the shell from misinterpreting it as multiple arguments.
(-rollforward) Turn Roll Forward Archiving ON
-rollforward
When used in conjunction with the -backup command, turn roll forward archiving ON, but do not begin writing to the roll forward log.
After this option, you are guaranteed that no log records will be discarded unless they have been archived.
If you don't use this parameter with -log, the log files will eventually fill to capacity. When a log file fills to capacity, the database will freeze until the log file is relieved by turning roll forward logging ON, which will cause the log entries to be archived and then discarded, or by terminating roll
Versant Server Guide 297
vbackup forward logging entirely, which will cause the log entries to be discarded after they have been applied to a database.
(-aggression) Aggression - Buffer Time
-aggression aggression_param
The maximum number of seconds vbackup is allowed to hold data in a buffer before writing to tape.
The default interval is 60 seconds. Decreasing this number can make log records go to tape more quickly, but can decrease storage efficiency. Similarly, increasing the number increases the amount of time it takes to write log records to tape but increases storage efficiency. This is because vbackup must write to tape only in chunks of the size specified by the -blocking parameter.
If the interval specified by -aggression elapses and there are still not enough unarchived log records to fill up one block, vbackup will add padding and flush anyway. Since this padding is wasted space, storage efficiency is reduced.
The -aggression flag can be used to specify either a single number for all databases being logged, or a list of numbers, one for each database.
(-script) Script
-script command
If interaction is required, this option will perform the specified command and exit the current process with a message to the console.
This option is useful if you are running vbackup from a script. For example, if you are performing roll forward logging, this option can be used to notify you when an archive tape fills up.
If you are using UNIX, you can insert an entry into the /etc/rc.local file to start vbackup whenever the system reboots. This is best done by having /etc/rc.local run a script in a separate file which runs setuid to the DBA account. If you are using Windows, you can similarly run vbackup with an entry in a boot file. Following are relevant examples.
For example: vbackup -script 'mail dba < vbackup.out' \
-log db1 db2 db3 > vbackup.out
298 Versant Server Guide
vbackup
The above command will start standard log archiving for three databases. If something happens which requires user input, such as the backup device becoming full, vbackup will exit and mail its output to the DBA user.
Another example: i=0 while test $i -lt 30 do vbackup -dev log$i -script 'echo log full | mail dba' \
-capacity 100M -log db1 db2 db3 i='expr $i + 1' done
The above command does the same standard log archiving. Rather than archiving directly to tape, it archives to disk in a series of 100 megabyte files named log1, log2, log3, etc. Whenever a new file is completed, the DBA is notified via mail. To avoid an infinite loop in the case when vbackup hits a legitimate error instead of a full tape, the script exits after 30 iterations.
There are many useful ways to use the -script option. For example, a line could be added which copied the 100MB files to tape once it was completed. It could also be made to cycle through a series of tape devices rather than a series of files. Once one tape drive filled up, the next one would take over, thus minimizing the need for human intervention.
Following is an example of a script that allows you to switch between two disk files. When one file becomes full, it is closed, and a new file takes over while the previous file is being copied to tape.
Archive logs to file and copy the file to tape once it reaches 100M. Delete the file once it is copied.
Limit ourselves to 30 iterations to avoid infinite loops.
blocking=10k i=1 while [ $i -le 30 ]; do
# backup logs to file vbackup -dev log$i -capacity 100M -blocking $blocking \
-script 'echo log full | mail dba'-log group@gamehendge
# wait until the last file was copied to tape if [ $i -gt 1 ]; then while [ -f log'expr $i - 1' ]; do sleep 5
Versant Server Guide 299
vbackup done fi
# fork a process to copy the current file to tape
( if dd if=log$i of=/dev/nrst0 bs=$blocking; then rm log$i else echo dd failed for log$i | mail dba
) & fi
# increment i i='expr $i + 1' done
(-getbeprofile) Extract Server Process Profile File
-getbeprofile
This option is used in conjunction with the –list command to extract the backed up server process profile file profile.be.
vbackup backs up the server process profile file profile.be into the backup device or file. For a multiple database backup, multiple server process profile files (profile.be) will get backed up to the same backup device or file.
Use the -getbeprofile option to extract the server process profile file profile.be that was present at the time when the backup was taken. By default this option will dump the contents of all the backed up server process profile files (profile.be) to stdout.
(-odir) Target Directory for Extracted Server Process Profile File
-odir <output directory>
This option is used with the –list command and the –getbeprofile option together. The syntax is:
-list [-getbeprofile [-odir <path-to-save-profile>]]
300 Versant Server Guide
vbackup
Use the -odir <output directory> option to extract all the server process profile files (profile.be) into the specified directory. This directory should already exist and must have write permission.
vbackup will create a new file under this directory that will adhere to the following naming convention:
<database name>_<hostname>_level<backuplevel>_profile.be
10.21.5. Changing the Parameter Settings
If there is a recoverable error or an additional phase of restore, such as a second or third level of restore or a log roll forward, you can change certain settings after vbackup has been invoked.
The settings can be changed only for the following parameters:
• device
• position
• blocking
• capacity
Following is an example, which shows how to change the device name after initially specifying a nonexistent device.
Suppose vbackup has been invoked as follows, and the device /tmp/grp does not exist:
#vbackup -dev /tmp/grp -backup group
In this case, the following output is seen (the version number will correspond to your particular release number):
Versant Utility VBACKUP Version 9.3.0
Copyright (c) 1989-2017 Versant Software LLC
Backing up database 'group' to device '/tmp/grp':
0% 50% 100%
| |
Current settings are:
| | | device = '/tmp/grp' position = 'current' capacity = 'dynamic'
Versant Server Guide 301
vbackup blocking = 'optimal'
Could not open device '/tmp/grp' at position 'current'.
OS error #2. Please check the device. [?=help] ?
Change the setting by typing a name and new value, for example, position 2), type quit to quit, or press
<Return> to proceed. It is only necessary to type enough of a command to make it unique, so you can type q instead of quit or p 2 instead of position 2.
After changing a setting you will see the following:
Change additional settings or type <return> to proceed. [?=help]
10.21.6. Database Backup Frequency
A database should be backed up regularly. The more heavily a database is modified, the more frequently you will want to back up, either in full or incrementally. The basic trade-off is that full backups take longer than incremental backups, but they are much easier to use for a restore operation.
A rule of thumb for using backup levels is first to do a level 0 backup and then do level 1 backups. After a while, as changes accumulate, you will start to get tired of how long the level 1 backups are taking. At that point, you can start to do level 2 backups. When level 2 backups start to take a long time, then you should begin the cycle again by doing a level 0 backup.
If you do multiple level 1 and/or 2 backups, you should only use the latest backup when you restore the database.
For a heavily modified database, you might want to perform daily backups on a schedule similar to the following:
Day of the week: Sun Mon Tue Wed Thu Fri Sat
Level of backup: 0 1 2 0 1 2 2
A less heavily modified database might be backed up daily, but with only one full backup:
Day of the week: Sun Mon Tue Wed Thu Fri Sat
Level of backup: 0 1 2 2 1 2 2
A lightly modified database could be backed up three times a week:
302 Versant Server Guide
vbackup
Day of the week: Sun Mon Tue Wed Thu Fri Sat
Level of backup: 0 1 2
A very lightly modified database could be backed up weekly:
Week of the month:
Level of backup:
1st 2nd 3rd 4th
0 1 1 1
In short, you should back up at a frequency that is relative to the importance of a database and the frequency with which objects in it are modified.
If a database is small, you can perform a full level 0 backup every time. If it is large, you should take advantage of the incremental backup feature by setting the backup level to minimize the amount of time and storage associated with each backup.
If you want to restore the database to the most recently backed up state, and if the database still exists, you can use the -info option to tell you which back up files and the order you need to use them to restore the database. If the database does not exist, you will have to figure out for yourself the order in which to use the backup files.
See also
and
stopdb , both of which are utilities needed to perform restore operations.
10.21.7. Database Restore Procedure
The steps involved in restoring a database are as follows:
1. Determine what backup files you need.
Before restoring a database, you must determine which backup files you need. If you are recovering from a deletion or damaging of key objects, you can use the -info option with vbackup to list the set of backups necessary to restore the specified databases to their most recently backed up state. If list information is not available, you will have to rely on your own records.
For additional comments,
2. Locate and examine files on tapes or other backup device.
Once you know what backups are needed, you must next locate the tapes or file devices on which they are stored. You can use the -list option with vbackup to list the backup files stored on a backup device.
Versant Server Guide 303
vbackup
For additional comments, refer to the description for
3. Perform the restore.
To restore from a device, use the -restore option to vbackup. You must restore in the proper order as listed by -info or your own records, working from the last full backup to the most recent incremental backup.
Refer to the description of
for additional comments.
304 Versant Server Guide
vbbadmin
10.22. vbbadmin
vbbadmin <command>
This utility manages the BlackBox and provides options to export and view the data.
start/stop
explicitly start/stop the black
info
print the status of the BlackBox
export
save a snapshot of the BlackBox to a file
view
the contents of the snapshot, BlackBox dump
The timestamps reported by the BlackBox may not represent the precise time of the event. For performance reasons the BlackBox only receives timestamp information every few seconds. However, events are serialized between timestamps using a counter insuring that the order of events is preserved.
Using vbbadmin with a database that has password-based DBA authentication implemented, the user will have to provide the DBA password when prompted.
Parameters for this utility are:
-start [-comp] [-size] {-d <dbname>}
Start the BlackBox recording explicitly.
Versant Server Guide 305
vbbadmin
On Windows systems calling -start will result in an error if the BlackBox has been previously used
(started and stopped) with the database. The error is caused because the Black- Box shared memory segment used by the previous BlackBox session cannot be released. To run the BlackBox again, you must stop and restart the database.
-comp {all | rpc llg om pf pm}
Start the BlackBox recording with the specified components. If multiple components are specified, the list must be delimited by commas with no spaces.
To add components you have to restart the BlackBox.
-size <size>
Number of entries in the BlackBox recorder area. Default is 100000.
-stop {-d <dbname>}
Stop the BlackBox recording. This will generate a snapshot in the database BlackBox directory.
-info {-status | -summary} {-d <dbname> | -f <filename>}
Print the status information for the BlackBox.
-status
Lists the on/off status for components.
For example: vbbadmin -info -status -d gg
Versant Utility VBBADMIN Version 9.3.0
Copyright (c) 1988-2017 Versant Software LLC
BlackBox Size = 100000
COMP DESCRIPTION ON
==== =================== == rpc RPC Messages llg Logical logging
ON
ON om Object Modification --
306 Versant Server Guide
vbbadmin pf Page Flushes pm Page Modification
--
ON
-summary
Print a summary for the BlackBox.
-export [-f <filename> ] {-d <dbname> }
Save a snapshot of the BlackBox to a file. The filename specifies the name of the file to be used for export.
If the filename is not specified, a filename corresponding to the database name will be generated in the database directory.
-view -file <filename> <command>
Start a command shell. Following are valid the commands:
filter [ -comp] [-thread] [-timeframe] [-trans]
View the contents of the BlackBox according to the filter specified. Multiple filters can be used in conjunction.
For example: filter -comp rpc pm -thread all
-comp { rpc, llg, om, pf, pm}
View according to the component specified.
-thread {-all | <thread-id>}
View thread-wise data or for the specified <thread-id>.
Thread identifier, thread-id, is the corresponding vserver thread.
-timeframe {[-eq | -lt | -gt] <time>} | {<time1> <time2>}
View data for the specified time.
Versant Server Guide 307
vbbadmin
Time is specified in DD:MM:YY:HH:MM:SS format.
-trans {-unfinished | <txid> }
View data for specified transaction.
-unfinished
List all unfinished transactions
txid
Transaction in LOID format
export {-csv <filename>} exit
Export the BlackBox recording in CSV format.
Stop the view for the specified file/database
For example, filter all remote procedure calls vbbadmin -view -file gg_pegasus_2Apr_10.39.vbb
Versant Utility VBBADMIN Version 9.3.0
Copyright (c) 1988-2017 Versant Software LLC
>filter rpc
THREAD
10420.005096
rpc_ut_generic rpc_ut_generic rpc_tr_beglog
FUNCTION
rpc_connect
RPC
RPC
TYPE
RPC
TIMESTAMP
1
TS COUNTER
Thu Apr 02
10:39:03 2009
0 rpc begin Thu Apr 02 10:39:03
2009
Thu Apr 02 10:39:03
2009
RPC
2 rpc end
Thu Apr 02
10:39:03 2009
3
DATA
rpc begin rpc begin
308 Versant Server Guide
vbbadmin
THREAD
rpc_sch_qryeval rpc_sch_qryeval rpc_csr_alloc rpc_csr_alloc rpc_csr_fetch rpc_csr_fetch rpc_obj_gread
FUNCTION
rpc_tr_beglog
RPC
RPC
RPC
RPC
RPC
RPC
RPC
TYPE
RPC
Thu Apr 02 10:39:03
2009
Thu Apr 02 10:39:03
2009
Thu Apr 02 10:39:03
2009
Thu Apr 02 10:39:03
2009
Thu Apr 02 10:39:03
2009
Thu Apr 02 10:39:03
2009
Thu Apr 02 10:39:03
2009
TIMESTAMP TS COUNTER
Thu Apr 02
10:39:03 2009
4
5 rpc begin
6
7
8
9
10
11 rpc end rpc begin rpc end rpc begin rpc end rpc begin
DATA
rpc end
Versant Server Guide 309
vcompactdb
10.23. vcompactdb
10.23.1. Introduction
As objects grow or are deleted, empty spaces are created in the database files resulting in data segment fragmentation. As a result of this fragmentation, performance becomes less efficient and disk usage is increased. An organized, unfragmented database enjoys performance advantages resulting from better data allocation. An organized database also utilizes its back end cache to the fullest extent because each page in the cache contains the maximum possible number of objects.
Normally, in a high availability system, compacting a database offline is not an option. The vcompactdb utility reorganizes the data online. In addition to compacting database objects, vcompactdb also compacts system tables, also known as AT tables.
The dbtool utility can be used to analyze a database, seeking out unused data or spaces which are a result of fragmentation. This utility will aid in determining if running vcompactdb is necessary.
10.23.2. Options
The following is a list of available options and their descriptions for utilizing vcompactdb.
vcompactdb
-database <dbname>
[-class <class name> | -all]
[-batchsize <number of objects>]
[-systables]
[-nowait]
[-pollonly]
[-cancel]
-version
-class <class name>
Indicates that reorganization should be executed on data segments for the non-system class specified by <class name>. Specifying an invalid class name will result in an error being thrown.
310 Versant Server Guide
vcompactdb
-all
Indicates that reorganization should be performed on all data segments for all the non-system classes in the database.
The utility vcompactdb -all iterates through all the classes and schedules to compact each of them one after the other.
-batchsize <number of objects>
Indicates that reorganization should be performed by reorganizing a specified number of objects as a group. This option can be used to tune the memory requirements and execution speed of vcompactdb.
The default batch size is 1000.
-systables
Indicates that the reorganization should be executed on System Tables. This option can be used in conjunction with the -class option.
vcompactdb -database <database name> -class Hello -systables
The system table is a hash table used by the database server to lookup physical object locations within the database volumes given a LOID (logical object identifier) as a key.
It is implemented using extensible hashing which is a form of dynamic hashing scheme. The LOID values are keys for the hash table. Due to the random nature of changes to the hash table, the table becomes fragmented over time. As a result, the fill grade of the pages used for hash table entries could be significantly below the average 50% normally reached by the hashing algorithm. A fragmented table can lead to increased memory consumption, slower lookups, and unnecessary database space used.
The first time the system tables are compacted on a database that has been in use for a long time, the process may be lengthy but result in a lot of freed pages. Subsequent compacting will be faster compared to the time needed to compact the pages used for the objects in the database. It is recommended that you also compact the system table whenever vcompactdb is run.
You may use the dbtool -AT -analyze option to get an indication of the current System Tables fill grade.
Versant Server Guide 311
vcompactdb
For more information, refer to
Section 10.10.12, “-space, -AT—Get Information on Fragmentation and Free Space” pg. 244.
-nowait [-systables] -class classname
Starts compacting the given class without polling any progress information. Compacting will run in the background on the server. Compacting System Tables can be started in addition to, or alone, without a class.
Note that if vcompactdb -nowait is called on more than just one class at a time, then parallel compaction threads will be started for each one of the given classes. For example, vcompactdb
-nowait is called on multiple classes as follows.
vcompactdb -database <db> -class class1 class2 class3 class4 -nowait
By specifying four classes, four parallel compaction threads will be started.
Similarly, if for instance vcompactdb -database <db1> -all -nowait is called on a database db1 which has 500 classes, then 500 parallel compaction threads will be started. This could result in a lot of load on the machine leading to a slow down of all the other processes.
If you wish to run vcompactdb on multiple classes it is recommended to do so using the -all option
(without the -nowait option) as illustrated below. This will proceed with the compaction in a sequential way, de-fragmenting one class at a time.
vcompactdb -database <db> -all or, vcompactdb -database <db> -class <class1> <class2>...<classN>
-pollonly [-systables] -class classname
Prints the progress of a compaction running on the given class. Compacting System Tables can be polled in addition to, or alone, without a class.
312 Versant Server Guide
vcompactdb
-cancel [-systables] -class classname
Cancels a running compaction for the given class. Compacting System Tables compaction can be cancelled in addition to, or alone, without a class.
The vcompactdb -cancel -all option only terminates the ongoing class compaction on the server side. It does not cancel a scheduled class compaction. Thus, calling -cancel -all, terminates the running class compaction, and once it is terminated, vcompactdb utility will continue compacting the next scheduled class.
In order to fully terminate the vcompactdb client utility, you need to shutdown the client manually
(CTR.C is safe or kill the process is also safe), and then call -cancel to cancel the ongoing compaction.
-version
Displays vcompactdb version information.
If vcompactdb is executed without specifying -class <class name> or -all or -systables option, then only a list of classes in the database will be displayed on the screen and no compacting will take place.
10.23.3. Benefits
Fragmentation significantly effects reads, writes, and un-optimized queries. Using vcompactdb regularly enables your application to achieve better performance.
10.23.3.1. Fragmentation Effects on Performance
Fragmented pages affect performance of nearly every database operation. For example, assume you have 50% fragmentation (i.e. only 50% of your disk pages are occupied with objects and 50% are empty).
The effect of this type of fragmentation is as follows:
• The server cache is only half as efficient when fragmented as it is with zero fragmentation. This is due to the pages stored in the cache hold only half as many objects as they hold with zero fragmentation. This means that reads will read from the disk versus reading from shared memory on the server twice as often. The result is a significant slow down of read performance.
Versant Server Guide 313
vcompactdb
• Write performance suffers because each page written to the physical log and the system files contains only half as many objects as with zero fragmentation. This would not affect writes to the logical log because this log is not page based. The total slow-down in write performance is approximately 35%.
• Un-optimized queries take up to twice as long because twice the number of pages are fetched from the database volumes to search through the same number of objects.
10.23.3.2. Improved Free Space and Re-use
As a result of fragmentation, it could be that although you have plenty of free space, none of the spaces available are large enough for new objects to be placed in.
While de-fragmenting, vcompactdb will naturally free up larger sections of space. The actual physical size of the database will not be reduced, but there will be larger sections of space available for re-use when new objects are created in the database.
10.23.3.3. When to Run a De-fragmentation?
The following two commands determine the fragmentation level of the database quickly and efficiently.
Analyze the Data Use for Fragmentation
dbtool -space -class -all -sample db
The -sample option samples 1000 (default) random pages and uses them as representation for all the pages used by that class. The sample size can be changed using sub-option -size to get a more accurate estimate. However, 1000 pages should be adequate to get a clear representation.
Typical output:
Versant Utility DBTOOL Version 9.3.0
Copyright (c) 1989-2017 Versant Software LLC
Class: DBCompoundMsg bytes not in use = 129777664 percentage empty = 37%
Class: DBExpectedMsg bytes not in use = 144556032
314 Versant Server Guide
vcompactdb percentage empty = 39%
Class: DBActualRecipient bytes not in use = 135561216 percentage empty = 37%
Class: DBInternalAlarm
Empty class
Class: DBCell bytes not in use = 62865408 percentage empty = 13%
Class: DBTCILayer bytes not in use = 32768 percentage empty = 18%
Class: DBLogRecord bytes not in use = 0 percentage empty = 0%
Recommendation
The higher the percentage of empty space is and the higher the number of bytes, the more you will gain by de-fragmenting a class. As a rule, run a de-fragmentation for a class when the percentage of empty space is greater than 20% and the number of unused bytes is greater than 100000.
How often you run a de-fragmentation will depend on the use of the database specifically, the more a database is used the more quickly it becomes de-fragmented.
If your classes become de-fragmented quickly, you could run a de-fragmentation when the percentage of unused space is greater than 30%.
In the above example, the Classes: DBCompoundMsg, DBExpectedMsg, DBActualRecipient will significantly benefit from de-fragmentation.
Analyzing the AT (loid2poid table) for fragmentation:
dbtool -AT -analyze
Typical output :
Versant Server Guide 315
vcompactdb
Versant Utility DBTOOL Version 9.3.0
Copyright (c) 1989-2017 Versant Software LLC
** Analyzing AT **
6 AT table(s) are less than 50% filled. The space occupied by these tables is 10354835456 bytes. The space occupied by the complete AT is
10355146752 bytes.
Recommendation
A System Tables de-fragmentation should be run when at least one of the System Tables has less than 50% unused space.
In the example above, 6 System Tables are filled to less than 50% then you will significantly benefit from a System Tables de-fragmentation. In theory, you could expect to regain more than 50% of the
10354835456 bytes currently occupied, not to mention a performance improvement.
10.23.3.4. How often to run a de-fragmentation?
Frequency of de-fragmentation depends on the use of your database. Running the dbtool utility at regular intervals will give you an indication of how quickly your database becomes fragmented.
The first time a database is compacted, the process will take significantly longer than on subsequent runs.
10.23.4. Example
$ vcompactdb -database test
Compacting DB test
4 classes to compact
Please specify the class for which you would like to de-fragment the segment using the -class <class name> option or specify all classes using the -all option.
Choose from the following classes: c0 c1 c2 c3
316 Versant Server Guide
vcompactdb
You receive this output when you do not specify which class (or all classes) to de-fragment. The following uses the -all option to de-fragment all classes.
$ vcompactdb -database test -all -systables
Compacting DB test
4 classes to compact
115488 KB free before compaction vcompactdb for class c0 has 12.8358 percent (state is running) vcompactdb for class c0 has 89.2537 percent (state is running) vcompactdb for class c0 has 100 percent (state is complete) has finished with error code 0 vcompactdb for class c1 has 25 percent (state is running) vcompactdb for class c1 has 75 percent (state is running) vcompactdb for class c1 has 100 percent (state is complete) has finished with error code 0 vcompactdb for class c2 has 15 percent (state is running) vcompactdb for class c2 has 50 percent (state is running) vcompactdb for class c2 has 100 percent (state is complete) has finished with error code 0 vcompactdb for class c3 has 13 percent (state is running) vcompactdb for class c3 has 29 percent (state is running) vcompactdb for class c3 has 100 percent (state is complete) has finished with error code 0
Defragmenting system tables . . .
0 percent (state is scheduled)
100 percent (state is complete) has finished with error code 0
Done.
118240 KB free after compaction. 2752 KB freed up
10.23.5. Restrictions and Limitations
Only one instance of vcompactdb should be run on a class at the same time.
Versant Server Guide 317
vcompactdb
Running vcompactdb can affect query results. The order of loids in a query result may be different before and after compaction. Also, while vcompactdb is running a query might return duplicate loids.
318 Versant Server Guide
vcopydb
10.24. vcopydb
vcopydb [options] dbname copy_dbname
Copy all objects and class definitions from one database to another.
After using this utility, the objects in the target database will have the same logical object identifiers as the objects in the source database.
While copying objects and class definitions from one database to another, ensure that the same DBA password is specified for the databases that require password-based authentication.
If the target database does not exist, use makedb to create the target database directory before running vcopydb
. Both the source and the target databases must be group databases.
To copy a database is a resource intensive operation and for database sizes in the Gigabyte range, it is recommended to use special profile.be parameters for the source and target database.
As a default, vcopydb, locks objects when it reads them from the source database. Since it does not lock down the database while it runs and only locks objects of classes while it is iterating through them, there is a high chance that the target database can have logical inconsistencies. For example, if references between objects are changed while vcopydb is running, but, those objects have already been copied by vcopydb
, then the target database will not reflect this change. To minimize these kind of effects, it is recommended to put the source database in DBA/multiple-connections mode, before initiating the copy operation.
vcopydb can be run on an active database, however, it can lead to logical inconsistencies if another client modifies/deletes/inserts objects during the vcopydb operation. Setting the database in
DBA/multiple-connections mode can help prevent such problems.
Using vcopydb to copy data across two major Versant release versions, say from Versant 7.0 to 8.0, is not supported. In order to use vcopydb to copy data across installations successfully, the installations should share the same service release number at least (patch numbers may be different). For example, using vcopydb for copying data between Versant 8.0.2.1 and Versant 8.0.2.7 is fine.
Source Database
max_page_buffs
, set value as high as possible.
Versant Server Guide 319
vcopydb
Target Database
• The creation of data requires intensive logging, so tuning the log buffers and log files is essential for performance.
The recommended minimal sizes are:
• llogvol 32M
• plogvol 32M
• llog_buf_size 128M
• plog_buf_size 128M
• Turn Locking off in the target database.
• The log_buf_size should be 4 * logvolsize.
You can also alternatively use the -optimize option to tune the profile of the target database.
For more information refer to the
option.
After changing the profile.be parameter stop the databases.
On completion of vcopydb please replace the profile.be of the database with the production settings and restart the databases.
Parameters for this utility are:
dbname
The name of the source database.
copy_dbname
The name of the target database.
Options for this utility are:
-batchsize M
The default is 1000.
320 Versant Server Guide
vcopydb
Copy M objects per transaction. If these are large objects, there is a chance that you may get out-of-heap errors. You can use the -threads and -batchsize options to keep the heap requirement low. If not specified, vcopydb takes 1000 objects per transaction.
-i
Create, pre-allocate and initialize the target database.
A new database cannot be used as a replica database with the Fault Tolerant Server option.
-nocreate
Copy a database into an existing database without creating a new database for the copy.
An error will be returned if:
• The target database does not exist.
• The user does not have write access to the target database.
• The target database does not have enough space allocated to contain all objects in the origin database.
• The target database already contains user class definitions or objects. In this case, the error raised will be UT_DB_NOT_EMPTY.
-nocreate and -i cannot be used together.
-nolock
Turn Locking OFF in the source database.
-noprint
Suppress display messages.
-noprogress
Do not report the overall copy progress on this console. By default, the overall progress is displayed on the console via a progress gauge.
Versant Server Guide 321
vcopydb
-optimize
Use automatic profile tuning for speedup.
Optimizes the copy database operation by automatically tuning the server profile (profile.be) of the target database for performance. Only the server profile of the target database is changed. The profile parameters are tuned before the start of the copy operation and restored after the copy operation completes.
The following target server profile parameters are tuned automatically:
Parameter
locking logging
Action
This parameter is set to OFF.
If vcopydb terminates prematurely or is explicitly terminated, manual user intervention may be needed to restore the above mentioned server profile parameters to their original values. Additionally, the target database may not be in a usable state (since logging was turned off). Further steps would involve investigating why vcopydb terminated, fixing the problem and restarting vcopydb.
-threads N
Copy a database using N threads. The number of threads is limited by system resources. If this parameter is not specified, vcopydb will optimize and create 3 to 30 threads by itself.
322 Versant Server Guide
verr
10.25. verr
verr err_num|err_name|err_frag
Print an error message given an error number, name or name fragment.
Parameters for this utility are:
err_num
Specify the error number of error message to print.
err_name
Specify the error name of the error message to print.
err_frag
Specify a fragment of the error message to print.
The verr command reads error messages from the file error.txt in the versant.lib directory.
The error.txt file also contains explanations to many errors.
Programs linked with Versant, read error messages from the file error.msg in the versant.lib
directory.
The error.msg file contains only one-line error messages.
Following are several examples of using the verr utility to look up an error using a number or name.
verr 2903
====== SEARCHING FOR '2903' ======
2903, SM_LOCK_TIMEDOUT: Lock wait Timed out verr SCAP_PREP_CLS
====== SEARCHING FOR 'SCAP_PREP_CLS' ======
8127, SCAP_PREP_CLS: Cannot add signature to class
Versant Server Guide 323
verr object,for class %s
We were unable to mark the class object as dirty, so we could not add the class signature to it.
This will prevent the schema signature assertion at runtime.
Note that for the second example, explanatory information was available.
If you abbreviate the err_name argument, all messages matching the partial name will be printed.
For example: verr OUT_OF
====== SEARCHING FOR 'OUT_OF' ======
1022, SM_E_OUT_OF_CLASS_CB_SPACE: Out of class
CB space
1033, SM_E_OUT_OF_CSR_SPACE: Out of cursor space
1083, SM_E_OUT_OF_VOL_SPACE: all volumes exhausted
8816, EVPP_OUT_OF_MEMORY: out of memory in parser
The vpp program ran out of memory. Adding more swap space could help, as could removing some processes from the machine.
Using stopdb on a Versant database can also help a lot.
324 Versant Server Guide
vinfo
10.26. vinfo
vinfo [ -l | -v | -i]
Display Versant product information, list the version information for each component or verify consistency of the installation.
Options for this utility are:
-l
Display Versant product patch number and component versions
-v
Verify checksum of all files inside binaries and headers.
Vinfo will report any files that do not have the expected checksum for the current patch level. Any files that are from older patch levels will be reported as such and any files that are completely unknown will be reported as corrupt.
For example:
% vinfo -v ok odbms/demo/embeddability/ovbackup.c
ok bin/addvol ok bin/vserver ok bin/comparedb ok bin/convertdb ok bin/createdb
.....
error h/obmacros.h (This file matches the one shipped with Versant base release, patch 1, patch 2, patch
3)
.....
Versant Server Guide 325
vinfo
-i
Identify the patch level of an installation by taking a checksum of each installed file and comparing with an internal database of checksums for all patch levels. After making the best effort identification, vinfo verifies that each file is correct for the assigned patch level.
vinfo only has knowledge of patch levels matching the current vinfo version and older.
For example:
% vinfo -i
This installation is Versant Object Database 9.3.0.
ok odbms/demo/embeddability/ovbackup.c
ok bin/addvol ok bin/vserver
1) ok bin/comparedb ok bin/convertdb ok bin/createdb
......
error h/obmacros.h (This file matches the one shipped with Versant base release, patch 1, patch 2, patch
3)
......
326 Versant Server Guide
vinstinf
10.27. vinstinf
vinstinf
This utility will print the details of the installation information needed for generation of the license keys.
Machine type and machine identification dataHostid, ipv4 or ipv6) is needed when requesting for a license key. Any arguments passed will be ignored and will print the following details on the machine where it is executed.
1. Machine name
2. Machine type, Windows or Linux
3. Hostid
4. IPv4
5. IPv6
6. Total number of physical CPUs
7. Total number of CPU cores
Versant Server Guide 327
vlicchk
10.28. vlicchk
vlicchk –c <component_name> -v <component_version> [ <server> ]
The function of this utility is to determine if a specified component is licensed.
Parameters for this utility are:
-c <component_name>
The component name as decided by the component team.
-v <component_version>
The most significant two digits identifying the version of the component. This should follow the component specification. e.g. 6.0
server
The server machine to contact for performing the license check. If this parameter is not specified, the utility will perform a local license check. If a server name/ address is specified is the same machine on which the utility is executed, the utility will perform a local license check, else it will perform the remote license check.
328 Versant Server Guide
vlicvrfy
10.29. vlicvrfy
vlicvrfy [ <license-file> ]
The function of this utility is to scan a specified license file for errors.
It will accept one optional argument, which will be the license file to be scanned. If no arguments are specified, the following table identifies the files to be scanned:
Order
1
2
Environment Variable
VERSANT_LICENSE_FILE
VERSANT_ROOT
License File Name
$VERSANT_LICENSE_FILE
$VERSANT_ROOT/license.xml
Versant Server Guide 329
vmovedb
10.30. vmovedb
vmovedb [options] [-C <c1> <c2> <c3> …] <src_db> <target_db>
The function of this utility is to move all objects and copy class definitions schema from the source database to the target database.
Parameters for this utility are:
src_db
The name of the source database from which objects/schema are to be moved.
target_db
The name of the target database into which objects/schema are to be moved.
Options for this utility are:
-C <c1> <c2> <c3> …
This is the class name parameter. If not specified, all the objects from non-system classes will be moved to the target database else c1, c2, c3 are the classes whose objects are to be moved.
If a class with zero instances has been specified by the user, vmovedb will copy only the schema.
If the source database is empty, vmovedb will return the err UT_NO_OBJS_TO_MOVE.
-subclasses
This will be specified on the command line if the user needs to move objects from all the subclasses for the selected class or classes. If not specified, only objects belonging to the class, and not its subclasses, will be moved.
-closure L
For the selected set of objects, move objects in the closure set taken up to L levels. If this option does not specify the value of L is ‘0’ no objects linked to that object, either directly or indirectly, will be moved. Specify –1 to return all objects linked directly or indirectly to the objects selected by the –C option.
330 Versant Server Guide
vmovedb
-batchsize S
The default is 1000.
Move S objects per transaction. If not specified, then vmovedb will move 1000 objects per batch. This feature will improve scalability of vmovedb.
Usage Notes:
vmovedb is not allowed on a replica pair of databases. An attempt to do so will result in error
UT_NO_REPLICA_MOVE
.
vmovedb requires that the target database be in existence. If it does not exist, error TARGET_DB_NOT_CREATED will be returned.
If the source and target databases are the same, vmovedb returns error UT_VMOVEDB_INVALID_TARGET.
If the source database is associated with a password, then the same password should be specified for the target database. If the password verification fails, SM_E_INVALID_PASSWORD error is returned.
Versant Server Guide 331
vstats
10.31. vstats
The vstats utility allows you to perform server statistics collection. The Versant Server can report statistical data corresponding to nearly every aspect of server behavior and performance. You can collect information about the object cache, lock requests and contentions, communication data such as bytes read and written, remote procedure calls received, and much more. These statistics allow you to monitor system resources and to see how much time is spent performing tasks. You can even mathematically combine statistics to create statistics expressions that can provide very detailed server operational information.
The collected statistical information can be used—often under the direction of Versant support—to troubleshoot and improve your Versant Server system performance. Of course, statistics collection does not come for free. There is some performance overhead based on the type and number of statistics you are observing. For this reason, statistics collection is rarely, if ever, used 24/7 in a production system.
However, you can use limited statistics collection on a regular basis to verify performance and to monitor operations as your Versant system use requirements change over time.
Statistics collection involves connecting to a Versant Server and retrieving numerical parameters, mostly counters, but also time-based values, for specific databases. The basic operation of statistics collection using vstats is straightforward.
1. Enable, turn on, the desired statistics in a given database. Statistics collection has some performance overhead so, by default, statistics collection is turned off. Enabling a statistic directs the database to evaluate the statistic value and make it available to the statistics viewer. The following example enables the statistics db_net_rpcs (cumulative total of client remote procedure calls) and db_data_reads
(cumulative total of the number of database pages sent to the clients).
vstats -database db1 -on db_net_rpcs db_data_reads
2. View the statistics values for an appropriate amount of time. Except for the most recent values, statistics are not stored on the server. The viewer requests that the server return the current value of a given statistic. The viewer, in turn displays the statistic values on the console. The following command displays the statistics enabled above.
vstats -database db1 -stats "db_net_rpcs db1" "db_data_reads db1"
The output is in a tabular form with timestamps indicating when the values were read from the server.
332 Versant Server Guide
vstats
T = Timestamp
0 = db_net_rpcs db1
1 = db_data_reads db1
T
=====
17:22:36
17:22:41
17:22:46
17:22:51
. . .
0
=====
11
12
13
14
1
=====
18
36
54
72
The vstats utility prints to stdout. To save the output, simply redirect the command to a file.
By default, the time between iterations is five seconds and statistics collection continues until you terminate the vstats -stats command or you stop the database. You can specify the time period between requests with the -period option which determines how often the statistics are updated on the console. You can also specify how many total requests are made using the -iterations option.
This allows you to collect a specific number of values for a specific time span. For example, the command line vstats -database db1 -period 10 -iterations 360 -stats . . .
will collect statistics values every 10 seconds for an hour, i.e., 360 iterations.
In addition to collecting and printing basic statistics values, you can combine values, get minimums and maximums and display deltas. Refer to
Section 10.31.3, “Statistics Expressions” pg. 346.
3. Finally, disable statistics collection. Once you have collected the statistics you are interested in, you should disable the statistic collection in the database.
vstats -database db1 -off
The following sections describe the command syntax in detail, provide information about the statistics viewer output, discuss statistics expressions and derived statistics and provide a complete list of the available statistics, by category. Also, a number of suggested statistics collection scenarios are provided.
Versant Server Guide 333
vstats
Versant Client Statistics
The server statistics available using the vstats utility can also be gathered on the client-side in your
Versant C++ or Java Versant Interface applications. Client-side statistics can consist of the server data described here and also include statistical information about the Versant Client process and session. You can even add statistics reporting to your own application routines. Client-side statistics can be read by your application in real time or can be written to a file. Client statistics files may be read using the vstats utility.
For information about statistics collection in your Versant Client application, refer to your Versant C++
Programmer's Guide or Java Versant Interface Programmer's Guide.
10.31.1. Command Syntax
The basic syntax of the vstats utility is as follows.
vstats [ options ] command
Typing vstats, without any arguments, from the command line displays the available options and commands.
[C:\]vstats usage: vstats [options] command where options are one or more of:
-filename <filename>
-stdin
-database <dbname>
-username <user>
-password <passwd>
-id <connection-id>
-period <seconds>
-iterations <iterations>
-noinfo and command is one of:
-stats <stats>
-on <stats>
-off <stats>
334 Versant Server Guide
vstats
-connections [-hostname]
-transactions
-locks
-summary
-list
Each of these syntax components—commands and options—are described in the following sections.
10.31.1.1. Commands
The available commands are grouped here based on their function; statistics collection (enabling/disabling statistics), viewing statistics, and informational. The applicable options are listed for each command.
Statistics Collection
-on
(enable statistics collection)
vstats [ input options ] -on StatisticsList
This turns on statistics collection for the statistics specified in the StatisticsList.
The statistics list is a single statistic name or a space-separated list of statistic names.
Always supply a statistics list. Failure to specify the list can result in all statistics being collected, potentially causing severe performance issues.
Only the database owner is allowed to enable/disable statistics.
Statistics remain enabled only while the database is open. Stopping the database will disable all active statistics. Statistics enabled with -on are not automatically enabled when the database is re-started.
To automatically enable statistics collection when a connection to a database is made, you can name the desired statistics using the stat parameter in the database profile file. Refer to
“Statistical Parameters” pg. 133 for more information. Statistics enabled this way can be disabled
with the vstats -off command.
Versant Server Guide 335
vstats
Available statistic names are given in
Section 10.31.5, “System Statistic Names” pg. 349. You can
also use the
command to list the available statistics.
Options
(required)
(optional)
Example
This enables, turns on, the statistics db_net_rpcs and db_data_readsfor the database db1.
[C:\]vstats -database db1 -on db_net_rpcs db_data_reads
-off
(disable statistics collection)
vstats [ input options ] -off [ StatisticsList ]
This turns off statistics collection for the statistics specified in the StatisticsList.
The statistics list is a single statistic name or a space-separated list of statistic names. If no statistics are specified, all active statistics are disabled.
Only the database owner is allowed to enable/disable statistics.
Options
(required)
(optional)
Example 1
This disables, turns off, the statistic db_net_rpcs for the database db1.
[C:\]vstats -database db1 -off db_net_rpcs
Example 2
This turns off all enabled statistics for the database db1.
336 Versant Server Guide
vstats
[C:\]vstats -database db1 -off
Viewing Statistics
-stats
vstats [ input options ] [ output options ] -stats StatisticsList
The specified statistics are read from the source specified in the input options. The statistics must be enabled using
or in the
The statistics list is one or more statistics names. Multiple names are separated by a space character.
The statistic name must be in double-quotes and must also include the database name separated from the statistic name by a space. For example, to monitor the statistic db_net_rpcs for a database named db1, provide the name as "db_net_rpcs db1".
The statistics are displayed in tabular form on the console. For a description of the output refer to
Section 10.31.2, “The Statistics Viewer Output” pg. 344.
It is possible to combine statistics using arithmetic operators to create statistics expressions. For example, you can add statistics, take their ratio, or show a delta value. Expressions are described in
Section 10.31.3, “Statistics Expressions” pg. 346.
Options
Exactly one of the following input options must be specified.
All of the following output options are optional.
Example
[C:\]vstats -database db1 -stats "db_net_rpcs db1"
Versant Server Guide 337
vstats
T = Timestamp
0 = db_net_rpcs db1
T
=====
17:22:36
17:22:41
17:22:46
17:22:51
. . .
0
=====
11
12
13
14
Informational Commands
-connections
vstats [ input options ] -connections [ -hostname ]
This prints the connection identifier, user name, session name, server process identifier, application process identifier, and protocol information for each connection associated with the specified database.
Use this command to get a connection identifier that can be used with the -id input option.
With the -hostname option, the Server Port and Client Port entries are displayed as names rather than as IP addresses. Compare the two examples below.
Options
(required)
Example 1
This first example is without the -hostname option.
[C:\]vstats -database db1 -connections
Connection ID to database `db1':
. . .
338 Versant Server Guide
vstats
Connection ID
User Name
= 8
= `orpheus'
Session Name = `vstats -connections'
Long Transaction = `0.0.0'
Server Process
Client Process
= `lyra-win7':4440
= `lyra-win7':5056
Protocol
Server Port
Client Port
= TCP/IP v6
= `fe80::431:643:9529:4a17':`49370'
= `fe80::431:643:9529:4a17':`49372'
Example 2
This next example uses -hostname.
[C:\]vstats -database db1 -connections -hostname
Connection ID to database `db1':
. . .
Connection ID
User Name
= 10
= `orpheus'
Session Name = `vstats -connections'
Long Transaction = `0.0.0'
Server Process = `lyra-win7':4440
Client Process
Protocol
Server Port
Client Port
= `lyra-win7':1140
= TCP/IP v6
= `lyra-win7.versant.com':`49370'
= `lyra-win7.versant.com':`49391'
-locks
vstats [ input options ] -locks
For each locked object in the specified database, this prints the object's logical object identifier
(LOID), the external lock mode, the internal lock mode, the transaction identifier, and whether the object has a pending lock request.
Options
Versant Server Guide 339
vstats
(required)
Example
[C:\]vstats -database pdb1 -locks
Locks in database `pdb1':
Object
External Mode
Internal Mode
Transaction ID
Flags
= `5.0.2058'
= `Intention to Write'
= `None'
= `5.0.4112'
= `Running, Transient'
-transactions
vstats [ input options ] -transactions
For each transaction with a connection to the specified database, this prints the transaction identifier, the connection identifier associated with the transaction, and the number of locks held by the transaction.
Options
(required)
Example
[C:\]vstats -database pdb1 -transactions
Transactions in database `pdb1':
Transaction ID
Name
Lock Count
Connection ID
Flags
Transaction ID
Name
= `5.0.4112'
= `runhello'
= 0
= 16
= `Short'
= `5.0.4114'
= `vstats -transactions'
340 Versant Server Guide
vstats
Lock Count
Connection ID
Flags
= 0
= 18
= `Short'
-list
vstats [ input options ] -list
This lists the currently enabled database (db_) and connection (be_, backend) statistics.
Options
(required)
(required for listing connection statistics)
Example
[C:\]vstats -database pdb1 -on db_net_rpcs be_net_rpcs
[C:\]vstats -database pdb1 -list db_net_rpcs
[C:\]vstats -database pdb1 -id 16 -list be_net_rpcs db_net_rpcs
-summary
vstats -summary
This command prints a list of all defined statistics names together with a short description. Derived statistics defined in the statistics configuration file are also listed.
Versant Server Guide 341
vstats
Not all of the listed statistics may be available in your environment. Refer to
Section 10.31.4, “Statistics Configuration File—Derived Statistics”
347 for more information about the available statistics.
Example
[C:\]vstats -summary
Frontend per process statistics: fe_net_reads: Reads from back end fe_net_bytes_read: Bytes read from back end fe_net_read_time: Seconds reading from back end
. . .
Frontend per session statistics: se_net_reads: Reads from back end se_net_bytes_read: Bytes read from back end se_net_read_time: Seconds reading from back end
. . .
Backend per connection statistics: be_net_rpcs: Database RPCs received from clients be_net_reads: Reads from front end be_net_bytes_read: Bytes read from front end
. . .
Backend per database statistics: db_disk_free: Bytes of storage available db_disk_reserved: Bytes of storage reserved by classes db_net_rpcs: Database RPCs received from clients
. . .
Derived statistics from `C:\Versant\9\lib\vstats.ini':
. . . .
342 Versant Server Guide
vstats be_cache_hit_ratio db = be_data_located db / (be_data_located db + be_data_reads db)
. . . .
db_cache_hit_ratio db = db_data_located db / (db_data_located db + db_data_reads db)
. . .
10.31.1.2. Options
The vstats options are described in this section. They are grouped by whether they determine input or output behavior.
Input Options
-database DatabaseName
Defines the database to connect to for statistics collection. Additionally, you may supply a user name and password using the -username and -password options. The default user is the logged-in
OS user.
-id ConnectionID
Used with the -database option to limit the statistics to a specific database connection. The connection identifier is a numerical value. You can get a list of the connection identifiers using the
command. This only applies if your statistics list contains connection statistics (with the be_ prefix). Not specifying a connection ID implies all connections to the named database.
-filename StatisticsFile
Reads the named statistics file. Statistics files are created on the client.
This option only applies to Versant C++ and Java Versant Interface client statistics collection.
-stdin
This directs the vstats utility to read directly from the console stdin. This allows you to get the statistics in real time as they are being written to a client statistics file.
This option only applies to Versant C++ and Java Versant Interface client statistics collection.
Versant Server Guide 343
vstats
Output Options
-iterations n
Sets the number of iterations, i.e., statistics readings, to display. The default, 0 (zero), is to read statistics indefinately or, in the case of a statistics file, to the end of the file.
-period t
This sets the time period, in seconds, between readings. The default period is 5 seconds when using a direct connection, i.e., when the input is specified using -database, or 0 seconds when the input is from a file or stdin.
-noinfo
For some statistics, the right-most column of the statistics display shows additional information.
Setting -noinfo suppresses the display of the information column.
10.31.2. The Statistics Viewer Output
You have already seen the viewer output in previous examples. This section descibes the output display in more detail. As previously mentioned, the output is a tabular display of the statistics values specifed in the StatisticsList argument to the vstats -stats command. The viewer output is to the console, specifically stdout.
Here is a sample command call.
[C:\]vstats -database pdb1 -stats "db_cache_hit_ratio pdb1" "db_data_located pdb1"
"db_data_reads pdb1"
This will view the three specified statistics, db_cache_hit_ratio, db_data_located and db_data_reads for a database named db1. Each statistic is displayed in a column. The column header shows a number corresponding to the statistic as given in the printed legend. The first column, labeled T, is the Timestamp, the next column, 0, is the db_cache_hit_ratio value, and so on. Each line or row corresponds to an iteration, i.e., a collection request. The time of the iteration is stated and the value of each statistic is then given. Here is a sample.
T = Timestamp
0 = db_cache_hit_ratio pdb1
344 Versant Server Guide
vstats
1 = db_data_located pdb1
2 = db_data_reads pdb1
T
=====
12:41:48
12:41:53
12:41:58
12:42:03
12:42:08
12:42:13
12:42:18
12:42:23
12:42:28
12:42:33
12:42:38
12:42:43
12:42:48
12:42:53
12:42:58
12:43:03
12:43:08
12:43:13
^C
0
=====
0.333
0.333
0.333
0.333
0.385
0.385
0.385
0.385
0.385
0.385
0.385
0.444
0.474
0.500
0.545
0.565
0.600
0.630
10
12
8
9
13
15
17
5
5
5
5
5
1
=====
3
4
5
3
4
5
10
10
10
10
10
10
10
8
8
8
8
8
2
=====
6
8
8
6
8
8
If you are collecting a large number of statistics, the lines will wrap on your display making interpretation difficult. You can save the output to a file for viewing in an editor (or for parsing or other manipulation) by redirecting the viewer output.
[C:\]vstats -database pdb1 -stats "db_cache_hit_ratio pdb1" "db_data_located pdb1" "db_data_reads pdb1" > TodaysStats
By default, the time period between displayed iterations is 5 seconds and collection continues until halted by terminating the command (e.g., with ctrl+C) or closing the database. To limit the collection run to a specific amout of time, you can specify the time period and number of request iterations with the commands -period and -iterations, respectively. For example, here is the same command line as above but collection will automatically terminate after one hour (360 collection samples, a sample taken every 10 seconds).
Versant Server Guide 345
vstats
[C:\]vstats -database pdb1 -period 10 -iterations 360 -stats "db_cache_hit_ratio pdb1" "db_data_located pdb1" "db_data_reads pdb1" > TodaysStats
10.31.3. Statistics Expressions
You can combine basic statistics using arithmetic expressions to produce more meaningful information.
The -stats command understands the standard arithmetic operators +, -, *, /, (), and the built-in operators delta, min, max, and avg. For example, the following vstats call prints the cumulative page cache hit ratio.
vstats -database db1 -stats "db_data_located db1 / (db_data_located db1 + db_data_reads db1)"
Each of the basic statistics used in an expression must be enabled.
The operators are described in the following table.
Table 10.3. Statistics Expression Operators
*
/
Operator
+
-
() delta min max avg
Description
Adds the current values of two basic statistics.
Substracts the current value of a basic statistic from the value of another.
Multiplies the current values of two basic statistics.
Divides the current value of a basic statistic from the value of another. A divide by zero error is indicated by NaN (not a number) on the output line.
Groups an operation to establish precedence.
Returns the difference of the most recent value of a basic statistic to the previous value. Since the delta function requires two lines of output to make the difference comparison, the first line of output for this expression has no value (represented by the - character).
Returns the minimum value of the basic statistic during the current -stats run.
Returns the maximum value of the basic statistic during the current -stats run.
Returns the average value of the basic statistic during the current -stats run.
346 Versant Server Guide
vstats
10.31.4. Statistics Configuration File—Derived Statistics
Statistics expressions can be defined in a statistics configuration file for ease of re-use. When it starts,
vstats
reads this file and makes the derived statistics defined there available for use with the -stats command. The statistics configuration file is in the lib directory of your Versant Server installation.
On Windows installations, the name of the file is vstats.ini. On Linux installations, the file is .vstatsrc.
This file is supplied with your Versant Server installation and contains many pre-defined derived statistics.
In addition, on Linux systems, if you create a file named .vstatsrc exists in your home directory, it is also read.
In the statistics configuration file, the derived statistics are given a name that you can use in the
StatisticsList
argument to the -stats command. For example, the statistic expression
"be_ev_sys_delivered db + be_ev_user_delivered db" can be given the name be_events_delivered
db
. The definition is entered in the statistics configuration file as follows.
define be_events_delivered db = be_ev_sys_delivered db + be_ev_user_delivered db
In the derived statistic definition above, db is a place-holder, an argument, that can be defined when the derived statistic is used in a statistics list. For example, here is a vstats call using the derived statistic with a database named Rosetta.
vstats -database Rosetta -stats "be_events_delivered Rosetta"
(As with any statistic expression, each of the basic statistics that make up the derived statistic must be enabled.)
Each derived statistic definition is a separate line ending with a hard return. The definition line cannot be broken by a \ or line-continuation character. The basic syntax is as follows.
define stat_name [ args ] = expression
Elements of a definition line are:
stat_name
Name of the new statistic.
Versant Server Guide 347
vstats
args
A space delimited list of arguments. The most common use of args is to specify the database for connection and database statistics (those with the prefixes be_ and db_).
expression
The statistics expression. Defining expressions is discussed in
The file can contain comments beginning with the # character.
You can also define statistic name aliases in the statistics configuration file. The syntax is simply define
AliasName = StatisticName
You can use the derived statistic name in the statistics list of the -stats command as if it were a basic statistic. Derived statistics defined in a statistics configuration file are also listed by the vstats -summary command.
Example
This is a portion of the .vstatsrc/vstats.ini file in the lib directory of your Versant Server installation showing the derived connection and database statistics defined there. You can extend this file with derived statistics definitions of your own.
. . .
#####################################
# PER CONNECTION BACKEND STATISTICS #
#####################################
# hit ratio for page cache (both cumulative and instantaneous) define be_cache_hit_ratio db = be_data_located db / (be_data_located db + be_data_reads db) define be_inst_cache_hit_ratio db = delta be_data_located db / (delta be_data_located db + delta be_data_reads db) define be_cpu_time db = be_system_time db + be_user_time db define be_run_time db = be_real_time db - be_net_read_time db - be_net_write_time db - be_latch_wait_time db define be_latch_holds db = be_latch_granted db - be_latch_released db
###################################
# PER DATABASE BACKEND STATISTICS #
###################################
# hit ratio for page cache (both cumulative and instantaneous) define db_cache_hit_ratio db = db_data_located db / (db_data_located db + db_data_reads db) define db_inst_cache_hit_ratio db = delta db_data_located db / (delta db_data_located db + delta db_data_reads db) define db_latch_holds db = db_latch_granted db - db_latch_released db
348 Versant Server Guide
vstats
10.31.5. System Statistic Names
You can get a list of all statistics, including derived statistics defined in the statistics configuration file, using the vstats -summary command.
Process and session statistics (fe_ and se_ named statistics, respectively) are only available to clients using the Versant C++ or Java Versant Interface SDKs.
Latch and heap manager statistics (be_latch_, db_latch_, db_heap_ named statistics) should only be used under the direction of Versant support. Enabling these statistics arbitrarily can have a serious performance impact or even lead to a server halt.
In this section, the system database (db_) and connection (be_) statistics are listed and briefly described.
•
•
10.31.5.1. Database Statistic Names
The following statistics can be collected for a database.
Table 10.4. Database Statistics Names
Statistic
db_at_leaf_located db_at_leaf_located db_at_root_located db_at_root_read db_bf_llog_bytes_written db_bf_llog_flushes db_bf_plog_bytes_written db_bf_plog_flushes
Description
Associative table leaf pages found in database page cache
Associative table leaf pages read from sysvol and added volumes
Associative table root pages found in database page cache
Associative table root pages read from sysvol and added volumes
Bytes written to logical log
Number of writes to logical log
Bytes written to physical log
Number of writes to physical log
Versant Server Guide 349
vstats
Statistic Description
db_cache_hit_ratio db, where db is the name of a database
Derived statistic db_cache_hit_ratio db = db_data_located db /
(db_data_located db + db_data_reads db) db_checkpoints db_data_located
System checkpoints.
Pages found in database page cache db_data_reads db_data_writes db_disk_extent_free db_disk_free
Pages read from sysvol + added volumes
Pages written to sysvol + added volumes
Free extent space in bytes. This free volume space is universally available for all classes and index structures
Free volume space in bytes, including reserved space. Reserved space cannot be used by other classes or index structures db_disk_reserved db_ev_defined db_ev_sys_delivered db_ev_sys_raised db_ev_user_delivered db_ev_user_raised db_inst_cache_hit_ratio db, where
db
is the name of a database db_lock_deadlocks db_lock_timeouts db_lock_wait_time db_lock_waits db_locks_granted db_net_bytes_read db_net_bytes_written db_net_read_time db_net_reads db_net_rpcs db_net_write_time
Bytes of storage reserved by classes
Events defined
System events delivered
System events raised
User events delivered
User events raised
Derived statistic db_inst_cache_hit_ratio db = delta db_data_located db
/ (delta db_data_located db + delta db_data_reads db)
Deadlocks occurred
Timeouts waiting for locks
Seconds clients spent waiting for locks
Lock waits which occurred
Locks requested and granted
Bytes read from front end
Bytes written to front end
Seconds reading from front end
Reads from front end
Database RPCs received from clients
Seconds writing to front end
350 Versant Server Guide
vstats
Statistic
db_net_writes db_num_repobj db_obe_locks_waiting db_obj_received db_obj_sent db_polling_throttle_time db_qry_btree_objs db_qry_btree_time db_qry_hash_objs db_qry_hash_time db_qry_scan_objs db_qry_scan_time db_xact_active db_xact_committed db_xact_rolled_back db_xact_started
Description
Writes to front end
Versant FTS—Reports the current number of replication objects queued for syncing to the replica database. Refer to
Section 3.5.1, “Monitoring Sync Progress” in the Versant FTS
User's Guide
.
Connections waiting for locks
Objects received from front end
Objects sent to front end
Current throttle time value for transaction delay during the
V/FTS re-sync operation. Refer to the description of the database profile parameter
Objects read during B-tree query
Seconds spent in B-tree query
Objects read during hash query
Seconds spent in hash query
Objects read during sequential scan query
Seconds spent in sequential scan query
Active transactions
Transactions committed
Transactions rolled back
Transactions started
10.31.5.2. Connection Statistic Names
The following statistics can be collected for a server connection. This makes it possible to connect to a database and view database process statistics for connections other than your own.
To view only statistics for specific connections, it is necessary to determine the connection identifiers, using vstats -connections, and specify the connection(s) of interest to the statistics viewer, vstats
-stats
, with the -id option.
Gathering connection staticstics is only useful for client applications that have long running sessions.
Viewing connection statistics for application servers makes little sense as they share a connection session between multiple clients.
Versant Server Guide 351
vstats
Table 10.5. Names of Server Connection Statistics
Statistic
be_cache_hit_ratio db be_cpu_time db be_data_located be_data_reads be_data_writes be_ev_defined be_ev_sys_delivered be_ev_sys_raised be_ev_user_delivered be_ev_user_raised be_inst_cache_hit_ratio db be_lock_deadlocks be_lock_timeouts be_lock_wait_time be_lock_waits be_locks_granted be_net_bytes_read be_net_bytes_written be_net_read_time be_net_reads be_net_rpcs be_net_write_time be_net_writes
Description
Derived statistic, where db is the name of a database be_cache_hit_ratio db = be_data_located db /
(be_data_located db + be_data_reads db)
Derived statistic, where db is the name of a database (not all operating systems support this statistic) be_cpu_time db = be_system_time db + be_user_time db
Pages found in database page cache
Pages read from sysvol + added volumes
Pages written to sysvol + added volumes
Events defined
System events delivered
System events raised
User events delivered
User events raised
Derived statistic, where db is the name of a database be_inst_cache_hit_ratio db = delta be_data_located db
/ (delta be_data_located db + delta be_data_reads db)
Deadlocks occurred
Timeouts waiting for locks
Seconds clients spent waiting for locks
Lock waits which occurred
Locks requested and granted
Bytes read from front end
Bytes written to front end
Seconds reading from front end
Reads from front end
Database RPCs received from clients
Seconds writing to front end
Writes to front end
352 Versant Server Guide
vstats
Statistic
be_obe_locks_waiting be_obj_received be_obj_sent be_qry_btree_objs be_qry_btree_time be_qry_hash_objs be_qry_hash_time be_qry_scan_objs be_qry_scan_time be_real_time be_run_time db be_system_time be_user_time be_vm_maj_faults be_xact_active be_xact_committed be_xact_rolled_back be_xact_started
Description
1 if waiting for lock, 0 otherwise
Objects received from front end
Objects sent to front end
Objects read during B-tree query
Seconds spent in B-tree query
Objects read during hash query
Seconds spent in hash query
Objects read during sequential scan query
Seconds spent in sequential scan query
Seconds elapsed.
Derived statistic, where db is the name of a database be_run_time db = be_real_time db - be_net_read_time db
- be_net_write_time db - be_latch_wait_time db
Seconds in OS kernel functions
Seconds not in OS kernel functions
Virtual memory major page faults
Active transactions
Transactions committed
Transactions rolled back
Transactions started
10.31.6. Sample Collections
Following are some suggested statistics collections for monitoring different aspects of system performance.
(Note that the %DB% in the command lines refers to a Windows environment variable used to allow these commands to be used in a batch file. Modify this according to your own scripting environment.)
Versant Server Guide 353
vstats
Regular Monitoring
It is recommended that you regularly monitor your Versant Server system performance. The following is a suggested set of statistics for obtaining baseline information about your database use. Run the statistics collection for up to an hour at the same time daily.
vstats -database %DB% -on db_net_rpcs db_net_reads db_net_bytes_read db_net_read_time db_net_writes db_net_bytes_written db_net_write_time db_locks_granted db_lock_waits db_obe_locks_waiting db_lock_wait_time db_obj_sent db_obj_received db_data_reads db_data_writes db_xact_started db_xact_committed db_checkpoints db_xact_active db_qry_btree_objs db_qry_scan_objs db_qry_btree_time db_qry_scan_time db_data_located db_bf_llog_flushes db_bf_plog_flushes db_latch_wait_time db_bf_llog_bytes_written
# runs for 1 hour, samples every 10 seconds, 360 samples total vstats -database %DB% -period 10 -iterations 360 -stats "db_cache_hit_ratio %DB%"
"db_inst_cache_hit_ratio %DB%" "db_xact_active %DB%" "delta db_xact_started %DB%" "delta db_xact_committed %DB%" "delta db_checkpoints %DB%" "delta db_net_rpcs %DB%" "delta db_net_reads %DB%" "delta db_net_bytes_read %DB%" "delta db_net_read_time %DB%" "delta db_net_writes %DB%" "delta db_net_bytes_written %DB%" "delta db_net_write_time %DB%" "delta db_locks_granted %DB%" "delta db_lock_waits %DB%" "db_obe_locks_waiting %DB%" "delta db_lock_wait_time %DB%" "delta db_obj_sent %DB%" "delta db_obj_received %DB%" "delta db_data_reads %DB%" "delta db_data_writes %DB%" "delta db_qry_btree_objs %DB%" "delta db_qry_scan_objs %DB%" "delta db_qry_btree_time %DB%" "delta db_qry_scan_time %DB%" "delta db_data_located %DB%" "delta db_bf_llog_flushes %DB%" "delta db_bf_plog_flushes %DB%"
"delta db_latch_wait_time %DB%" "delta db_bf_llog_bytes_written %DB%" > daily.txt
Server Cache Efficiency
This set of statistics allows you to measure the effectiveness of the Versant Server cache. A high cache hit ratio means that most of of the objects sent to clients were found in the server cache, that is, read from server-side memory rather than from disk. Memory reads are significantly faster so a high cache ratio is desirable. For optimal performance this ratio should be above 0.8 and preferrably as close 1.0 as possible.
vstats -database %DB% -on db_xact_active db_data_reads db_data_located vstats -database %DB% -stats "db_xact_active %DB%" "delta db_data_reads %DB%" "delta db_data_located %DB%" "db_inst_cache_hit_ratio %DB%" "db_cache_hit_ratio %DB%" > cache.txt
354 Versant Server Guide
vstats
Throughput
These statistics can be used to give you information about the transaction commit throughput of the system. A high throughput is important for update intensive applications. The goal is to increase the number of transactions committed. Monitoring rolled back transactions might provide insight to the reason why throughput is not as expected.
vstats -database %DB% -on db_xact_active db_xact_committed db_xact_rolled_back db_data_reads db_data_located db_net_rpcs db_data_writes db_checkpoints vstats -database %DB% -stats "db_xact_active %DB%" "delta db_xact_committed %DB%" "delta db_xact_rolled_back %DB%” "delta db_net_rpcs %DB%" "delta db_data_writes %DB%" "delta db_data_reads %DB%" "delta db_data_located %DB%" "db_inst_cache_hit_ratio %DB%"
"db_cache_hit_ratio %DB%" "delta db_checkpoints %DB%" > throughput.txt
Concurrency
These statistics allow you to monitor the locking concurrency conditions of your database. If you see large values for lock waits, lock wait time, or deadlocks this is an indication that lock conflicts are present.
Such conflicts can have a dramatic impact on performance. Changes to your application code may be needed to reduce the possibilty of lock conflicts.
vstats -database %DB% -on db_xact_active db_locks_granted db_lock_waits db_lock_timeouts db_lock_wait_time db_obe_locks_waiting db_lock_deadlocks vstats -database %DB% -stats "db_xact_active %DB%" "delta db_lock_waits %DB%" "delta db_lock_timeouts %DB%" "delta db_lock_wait_time %DB%" "delta db_obe_locks_waiting %DB%"
"delta db_lock_deadlocks %DB%" > lock.txt
Logging System
Logging checkpoints occur whenever the physical or logical log file becomes full. For a well-tuned logging system you want to see that there is at least thirty seconds between checkpoints and that each checkpoint is completed quickly, within a few seconds. For information on setting the log file size refer to
Section 6.1.4, “Tuning Parameters” pg. 80.
vstats -database %DB% -on db_checkpoints db_xact_committed db_bf_llog_bytes_written db_bf_plog_bytes_written db_data_writes db_bf_llog_flushes db_bf_plog_flushes
Versant Server Guide 355
vstats vstats -database %DB% -period 1 -stats "delta db_checkpoints %DB%" "delta db_xact_committed
%DB%" "delta db_bf_llog_bytes_written %DB%" "delta db_bf_plog_bytes_written %DB%" "(delta db_data_writes %DB%)*16192 " "delta db_bf_llog_flushes %DB%" "delta db_bf_plog_flushes
%DB%" > logging.txt
Network Traffic
The statistics in this group monitor network communication traffic between database clients and the server. Large numbers of remote procedure calls (RPCs) per object, for example, implies that network traffic could be greatly reduced by using group operations in your application.
vstats -database %DB% -on db_xact_active db_net_reads db_net_bytes_read db_net_writes db_net_bytes_written db_obj_sent db_net_rpcs vstats -database %DB% -period 1 -stats "db_xact_active %DB%" "delta db_net_reads %DB%"
"delta db_net_bytes_read %DB%" "delta db_net_writes %DB%" "delta db_net_bytes_written
%DB%" "delta db_obj_sent db_net_rpcs %DB%" "db_obj_sent %DB%" "db_net_rpcs %DB%"
"(db_net_rpcs %DB%)/(db_obj_sent %DB%)" > net.txt
Query Efficiency
The following statistics relate to query performance. A large value for db_qry_scan_objs (seconds spent in sequential scan query) indicates that you can significantly improve performance by adding an appropriate index (or indexes). Large values for btree-based queries can indicate that indexes may not be effective.
vstats -database %DB% -on db_xact_active db_qry_scan_objs db_qry_scan_time db_qry_btree_objs db_qry_btree_time vstats -database %DB% -stats "db_xact_active %DB%" "delta db_qry_scan_objs %DB%" "delta db_qry_scan_time %DB%" "delta db_qry_btree_objs %DB%" "delta db_qry_btree_time %DB%" > query.txt
A Customer Case Study
In this case, a customer reported that there seemed to be a performance decrease when upgrading from an earlier version of Versant.
356 Versant Server Guide
vstats
The following statistics and statistic expressions were monitored.
Statistic Expression
db_xact_active delta db_data_reads delta db_data_writes delta db_data_located delta db_qry_btree_time delta db_qry_scan_time delta db_latch_wait_time delta db_latch_wait_time_bf delta db_checkpoints
Intended Measurement Note
Reports the number of active transactions at the timestamp.
The delta, i.e., change, in the amount of data being read. In other words, since the last time stamp, are active transactions reading more or less data from the database.
These two statistics together monitor the change in data traffic to and from the database. This needs to take into account the number of active transactions reported by the previous statistic.
The delta, i.e., change, in the amount of written data. In other words, since the last time stamp, are the active transactions writing (commiting) more or less data to the database.
This shows change in requested data that are already located in the database server cache and thus do not require reading from the pyhsical database.
Taken together with delta db_data_reads
, this gives and indication of the cache effectiveness.
The seconds spent during the time interval performing an indexed
(B-tree) query.
The seconds spent during the time interval executing a sequential scan query.
A measure of internal data structure use.
A measure of internal data structure use.
The number of checkpoints performed during the time interval.
A sequential scan query is one that does not use an index. If you are spending a large amount of time here, depending on the objects being queried, you could consider defining an appropriate index.
Latch statistics should only be used under the direction of Versant support.
Latch statistics should only be used under the direction of Versant support.
Versant Server Guide 357
vstats
Statistic Expression Intended Measurement
delta db_xact_committed
The number of transaction commit operations performed during the time interval.
delta db_bf_llog_bytes_written
The number of bytes written to the logical log file during the time interval.
delta db_bf_plog_bytes_written
The number of bytes written to the physical log file during the time interval.
delta db_lock_wait_time
The number of seconds clients spent waiting for locked objects during the time interval.
delta db_latch_wait_time_log_unit
A measure of internal data structure use.
Note
Latch statistics should only be used under the direction of Versant support.
Statistics runs were performed for 30 minutes at different times during day.
Statistics data
Here is a portion of one of the statistics runs.
T = Timestamp
0 = db_xact_active CustomerDatabase
1 = delta db_data_reads CustomerDatabase
2 = delta db_data_writes CustomerDatabase
3 = delta db_data_located CustomerDatabase
4 = delta db_qry_btree_time CustomerDatabase
5 = delta db_qry_scan_time CustomerDatabase
6 = delta db_latch_wait_time CustomerDatabase
7 = delta db_latch_wait_time_bf CustomerDatabase
8 = delta db_checkpoints CustomerDatabase
9 = delta db_xact_committed CustomerDatabase
10 = delta db_bf_llog_bytes_written CustomerDatabase
11 = delta db_bf_plog_bytes_written CustomerDatabase
12 = delta db_lock_wait_time CustomerDatabase
13 = delta db_latch_wait_time_log_unit CustomerDatabase
T
=====
0
=====
15:30:03 699
15:30:08 698
15:30:13 699
15:30:18 698
. . .
15:45:20 712
15:45:25 715
15:45:30 713
15:45:35 715
15:45:40 715
. . .
16:29:51 748
1
=====
-
10
25
14
14
29
7
3
17
5
2
=====
-
0
0
0
740
62
70
72
0
0
3
=====
-
4930
3808
5859
7770
6405
6326
10351
14844
7995
4
=====
-
0.001
0.005
0.002
0
0.001
0
0.001
0
0
5
=====
-
0.154
0.665
2.257
0.180
0.247
0.185
0.092
0.185
0.381
6
=====
-
0.946
0.244
0.428
7
=====
-
0.005
0.093
0.094
10.022
35.969
13.508
44.892
1.443
0.019
0.104
0.002
0.225
0.565
0.195
0.001
8
=====
-
0
0
0
1
1
1
1
0
0
40
33
28
40
52
50
9
=====
-
51
61
58
10
=====
-
346112
182272
237568
323584
399360
202752
303104
256000
321536
11
=====
-
0
0
0
2904064
407552
327680
440320
0
0
12
=====
-
0
0.022
0.457
13
=====
-
0
0
0.004
0
0
0
0
0
0.028
0.022
0.008
0.006
0.023
0.004
0
358 Versant Server Guide
vstats
16:29:56 748
16:30:01 748
1
7
0
0
7894
7670
0
0
0.220
0.098
0.274
0.094
0.224
0.069
0
0
62
44
493568
272384
0
0
0
0.300
0.021
0
Analysis
The following anaysis was provided by Versant based on the statistical values collected. Though not complete, it helps to show the kinds of things to look for when interpreting your own statistical runs.
“From the measurements taken in the afternoon at 15:30 an increase in the amount of modifications is visible with the llog / plog bytes written.
“Active transactions / connections are on average 726 in [current release], just 3% higher than in [previous release] with 706 transactions. But the llog / plog bytes written have doubled. This increase can be just a coincidence, if the measurements are taken in production. They do not explain such a decrease in transaction throughput. As long as no other limits are hit I would expect a proportional decrease of transaction throughput if the amount of logged data modifications increases. The considered vstats parameters do not show another limit.
“All other listed parameters [appear] consistent:
“The average latch wait time has nearly doubled, from 0,647s ([previous release]) to 1,208s ([current release]). But that is consistent with the amount of data that has been written to the logs, llog ([previous release]: 187MB; [current release]: 346MB) and plog ([previous release]: 35MB; [current release]: 97MB). That the log unit latch time has not increased means that a different latch is involved when logging occurs.
“On average, only a few number of pages are read from disk ([previous release]: 8; [current release]: 23), most pages are found in the cache. With [current release] 9731 pages are read from the cache, versus 7085 pages with [previous release], i.e., read load is about 40% higher on [current release].
“The number of pages written, db_data_writes, fits to asynchronous page flushing. All occurrences of page writes that occur without a checkpoint are due to high watermark triggered flushes, and those flushes comprise more than
616 pages (bf_dirty_high_water_mark (1024) - bf_dirty_low_water_mark (408) = 616). [note: bf_dirty_high_water_mark and bf_dirty_low_water_mark are server profile parameters—refer to
“At checkpoints all dirty pages are written, up to 1152 pages on [current release]. On [previous release] the maximum is only 900 pages, but that is just dependent on the timespan since the last flush triggered by a high watermark.
Query times between the versions are not significantly different. There are 3-4 checkpoints every 15 minutes triggered by habackup -split commands. Once in a while there is a single checkpoint when the logical log file runs out of space before the next split command occurs. Every split command causes 1 or 2 checkpoints, and checkpoints are comparatively expensive.”
Versant Server Guide 359
vstream
10.32. vstream
vstream mode -d dbname options filename
Exports the contents of a database to a file or imports data from a file into a database.
Parameters for this utility are:
mode
Import or export the database.
-d dbname
Name of database to receive or supply data.
options
Import or export options.
filename
Name of file to receive or supply data.
10.32.1. Mode
Alternatives for the mode parameter are:
Mode
-i
-o
Description
Stream data from a file to a database.
Stream data from a database to a file.
Input Mode, -i
In input mode, vstream reads in objects according to the exported data file and creates a new logical object identifier (loid) for each object. The -p option allows you to use the same loid's as in the original database.
360 Versant Server Guide
vstream
Output Mode, -o
In output mode, vstream iterates through all the objects in the database using cursors and streams the objects to a file. You can use the option -n to set how many objects to read in each cursor fetch.
The default setting limits the number of objects read in one cursor fetch to not exceed 80% of the cache size.
10.32.2. Options
Options for this utility are:
-p
Preserve object links when importing.
The -p option ensures that logical object identifiers are not changed during the import process.
When importing data from a file to a database in multiple executions of vstream, you need to use the -p option to preserve link relationships.
In general, you should never break an object graph into two vstream calls, or you may not be able to properly restore it.
For example, suppose you have a container with classes A and B and that instances of these classes have links to one another. Now, suppose that you use two vstream iterations to export the database: vstream -o -d db -c A data1.dat
vstream -o -d db -c B data2.dat
Then, later, if you import these two database files into a database with the following commands, the link relationships between A and B will not be set properly: vstream -i -d db data1.dat
vstream -i -d db data2.dat
However, link relationships will be set properly with the following commands, because the logical object identifiers were preserved: vstream –i –p –d db data1.dat
vstream –i –p –d db data2.dat
Versant Server Guide 361
vstream
When exporting data, if logical object identifiers are to be preserved in a destination database, you should either filter by class name or set level filtering to 1. If level filtering is set to a number greater than 1, some duplication in the data stream might occur.
-a
Aborts on schema miss-match. This option is applicable when input mode (-i) is enabled.
With this option, vstream will abort if the schema from the stream differs for the existing classes in target database.
-t num
Number of import or export iterations to perform before executing a commit and releasing the object cache.
The default is one iteration, which means vstream releases memory after each cursor fetch or after reading each vstr from an exported data file.
-n num
Number of cursors to be used to fetch objects.
-l level
Maximum levels of an object graph to export.
The default is -1, which means read the entire object graph.
Specify a positive number to specify a particular number of levels to export. Setting a low level number, such as 1, will reduce memory requirements.
If you specify the -l option with a level greater than 0 (i.e., 1, 2, etc.), vstream will write the morphology data to a file. The name of this file will be the same as your data file, except with the suffix .morph. This file must be present for vstream to recreate the database.
-g
Turn on the group read option.
This option will improve performance if your object graph (the object tree) is not very complex.
362 Versant Server Guide
vstream
-f
Fast mode, which means read all objects into memory when exporting.
This option improves performance but requires a lot of memory.
-nolock
Set default lock to NOLOCK during export
-c class
Specify names of the comma separated classes whose instances will be exported. While specifying the multiple class names, there should not be any space after the comma separator.
If the template classes have multiple parameters, the comma separating the template parameters should be escaped with the \ escape character. Additionally, if the list of classes contains a template class then it should be specified using double quotes.
For example, to stream out a class A and a template class B having two template parameters you need to use the following command line: vstream -o -d db -c "A,B<o_4b\,o_4b>" data1.dat
To stream out template class B you can use; vstream -o -d db -c "B<o_4b\,o_4b>" data2.dat
To stream out class X, class Y and class Z you can use; vstream -o -d db -c X,Y,Z data3.dat
If you specify the -c option, vstream will write morphology data to a file. The name of this file will be the same as your data file, except with the suffix .morph. This file must be present for vstream to recreate the database.
-q query
Specify instances to be exported by using a query.
The query should have the general form: class attribute op value
Versant Server Guide 363
vstream where:
• class is the class name
• attribute is the attribute name
• op is one of {==, <, >, <=, >=, !=}
• value is the attribute value, which must be matched.
Only objects matching the query will be exported.
Place the query in quotes so that it is parsed as a single argument.
-q7 vql7_query
Specify instances to be exported by using a VQL7 query.
Projections are not supported.
Only objects matching the query will be exported.
Place the query in quotes so that it is parsed as a single argument.
For example, to stream out all “Hello” objects that are pointing to a particular instance, you can use the following command line: vstream -o -d db -q7 "select selfoid from Hello where Hello::mylink
=7.0.3086" data4.dat
-u user
Run as the specified DB user.
-pwd password
Enter password for the DB user specified in -u.
364 Versant Server Guide
vstream
10.32.3. Specifying Levels to Export
When an object is streamed out, by default the whole object graph referenced by this object is streamed.
If the object graph is very large, as is the case for a container object that has links to every object in the database, level filtering can be used to control the depth of the object graph.
For example, streaming out a database with level 1 will export all the top level objects without following any further links; streaming with level 2 will force vstream to export an object and any object that is linked to it. The internal morphology map will guarantee the consistency of the object graphs.
Figure 10.1. Object Relationships
Within one vstream –l execution, all the object relationships (morphology) are preserved.
10.32.4. Synchronizing Schema
When you are importing into a database, if a class schema for the imported classes already exists in the target database, vstream will try to synchronize the class definitions in the new database.
The attributes in the stream schema and the database schema must be equal in name, type, and repetition factor for a successful match. The following schema synchronization rules apply:
Versant Server Guide 365
vstream
• If the schema defined in the new database is the same as in the stream data file, no synchronization is made.
• Any object attributes present in the database schema and not present in the stream schema will not be overwritten.
• Any object attributes present in both the database and stream schema are overwritten by the stream value. Attributes do not have to be in the same sequence.
• Any linked attributes present in the stream but not in the database are still processed, but not reproduced. The sub-graph of the link is still read in.
• Any non-linked attributes present in the stream but not in the destination database are ignored.
10.32.5. Operating Across Platforms and Releases
You can stream data with vstream across platforms.
Data can be streamed across different versions of Versant. However, when you stream from newer versions of a database to older versions of a database, make sure that you don't have any version-related system class inside your new database that cannot be handled in the old database.
10.32.6. Estimating Operating System Resources
• In general, close as many applications as possible before running vstream.
The vstream utility requires adequate random access memory (RAM) and a swap file of sufficient size to hold the morphology data. You can estimate the operating system (OS) resources needed for the streaming process for a given database size.
• If the page fault number remains high for over five minutes, vstream probably does not have enough
RAM.
Windows users:
For the current page fault number, refer to Task Manager>Processes>Page Faults; if it changes quickly, less than desirable progress is probably being made.
To export when memory is low, you may need to export only top-level objects by using the -l 1 option.
366 Versant Server Guide
vstream
Example:
Following is an example that calculates resources based on Windows operating system requirements.
The same equations are used to generate the resource requirements for a UNIX system.
The first step in estimating resources is to consider the object graph. The complexity of a given database object graph depends on the number of links between objects. In a worst case graph, each object is linked to every other object; in a best case graph, each object is isolated.
The table below lists object graph scenarios and the typical amount of RAM needed according to the number of objects, x, in the graph.
Table 10.6. Graph Complexity
Scenario
Worst Case
Average Case
Best Case
RAM
40x
20x
4x
Swap File
40x
40x
40x
The swap file must be large enough to contain the entire morphology map, which is always 40 times the number of database objects.
In the worst-case scenario, an average object has links to many other objects. This requires references to object information throughout the morphology map and during the streaming process. To achieve an acceptable level of performance, the required RAM size is approximately 40 times the number of objects plus the amount of RAM needed by the operating system.
In the average and best case a scenario, the object graph is relatively sparse and objects, once processed, are not referenced again. You still need the same swap file size, but the amount of RAM required is reduced to half or less. You can stream databases with smaller amounts of RAM if a typical object is referenced only a few times. Once these objects are swapped to disk by the operating system, it is less likely that they will be needed again. In the worst-case scenario, however, many objects are frequently referenced and the insufficient RAM can cause page faults.
The following formulas can be used to estimate the amount of operating system resources (RAM and swap file) needed:
Required RAM = (factor * ObjectCount) + OsRAM
Required swap file size = (40 * ObjectCount) + OsSwap
Versant Server Guide 367
vstream
Elements of the above equations are:
Elements
factor
ObjectCount
OsRAM
OsSwap
Description
Based on the morphology scenario .
The approximate number of database objects. You can calculate number of database object by running the db2tty utility.
The operating system requirement for RAM.
The operating system requirement for the swap file.
The following examples illustrate the method of estimating operating system resources in two cases.
The operating system sizes in the examples refer to Windows OS. The RAM and swap file requirements are similar for other supported platforms.
Table 10.7. Operating System Resource Examples
Database size:
Object count(1):
Case:
Factor:
RAM (2):
Swap file (3):
400 MB
2 million
Worst Case
40
(40*2*106)+30MB = 110MB
(40*2*106)+100MB = 180MB
1 GB(4)
10 million
Average to Best
15 (5)
(15*107)+30MB = 180MB
(40*107)+100MB = 500MB
Tips for calculating resources:
1. Can be calculated using db2tty.
2. Most databases will not require this maximum RAM amount. A test using a highly connected or worst case database of 380MB ran perfectly with a 96MB RAM limit. The Windows OS alone requires 30MB
RAM. If additional applications are running, increase this value. Vary this value for other operating systems accordingly.
3. The Windows OS alone requires 100MB swap file. Additional running applications will require an increased swap file size. Vary this value for other operating systems accordingly.
4. With a database of this size, it is likely that the graph is sparse, so the user should consider this an average or best case scenario.
5. Since this database is large and is between the suggested values for average (20) and best (4) cases, evaluate your database and choose this number.
368 Versant Server Guide
vstream
10.32.7. Estimating Stack Usage
For a very large object graph, the depth required to travel the graph for a first search may result in stack overflow.
On Windows operating system, the default stack limit is 1MB.
For an object graph whose level exceeds 1000, we recommend that you use level filtering.
Versant Server Guide 369
370 Versant Server Guide
/
Download
Just a friendly reminder. You can view the document right here. But most importantly, our AI has already read it. It can explain complex things in simple terms, answer your questions in any language, and help you quickly navigate even the longest or most compilcated documents.
Public link updated
The public link to your chat has been updated. You may view and manage your chat links after registration here.
Document public link
Advertisement
Key features
Object-oriented database
High performance
Scalable operation
Distributed databases
Client/server architecture
Two-phase commit
Schema management
Backup and restore
Warm standby
Frequently asked questions
Versant Server consists of a client and a server. The client interacts with the server to access and manipulate data. The server manages the database and provides the necessary services for clients to operate.
Versant Server offers a wide range of features, including data as objects, database features, database system, database administration, application programming, physical database, scalable operation, and distributed databases.
Versant Server uses a client/server model, locks, volumes, two-phase commits, and lazy updates to ensure scalable operation. It also supports distributed databases to handle large data volumes effectively.
Versant Server has four types of database users: Database System Administrator (DBSA), Database Administrator (DBA), Database User (DBUser), and Root User (root for Linux). Each type has specific access privileges and functionalities.
User questions
