ClearCase Reference Manual, Release 4.0, Windows

VOB

ClearCase VOB data structures

APPLICABILITY

ClearCase (data structure), Attache (data structure)

SYNOPSIS

Windows directory tree created by mkvob command

DESCRIPTION

A VOB (versioned object base) is a data repository for a directory tree. For users to access a VOB on a ClearCase client host:

The VOB must be activated on the host by mounting it as a file system of type MVFS (ClearCase multiversion file system type). See the mount reference page for more information.
The VOB must be accessed through a view.

This reference page discusses both a VOB's physical data structures and its logical structures, as seen by a user process through a view.

A VOB is implemented as a standard directory tree, whose top-level directory is the VOB storage directory. The directory contains files and subdirectories:

.pid	A one-line text file that lists the process-ID of the associated vob_server process, currently running on the host where the VOB storage directory resides.
admin	A directory that contains administrative data related to the amount of disk space a VOB and its derived objects are using. Use space -vob to list this data.
vob_oid	A one-line text file that lists the VOB's universal unique identifier( UUID). (OID means "object identifier".) This UUID is the same for all the replicas in a VOB family (ClearCase MultiSite). This file is also stored in the VOB's database; do not edit it.
replica_uuid	A one-line text file that lists the ClearCase replica UUID of this particular replica of the VOB. Different replicas created with ClearCase MultiSite have different identifiers.
identity.sd	Binary data file that contains the security descriptor for the VOB storage directory. This security descriptor includes a Windows ACL that assigns ull control (all permissions) to the VOB owner and also to the group ID ClearCase (the ClearCase servers run under this user ID).
groups.sd	List of supplementary groups for the VOB.
s	A subdirectory in which all of the VOB's local source storage pools reside.
d	A subdirectory in which all of the VOB's local derived object storage pools reside.
c	A subdirectory in which all of the VOB's local cleartext storage pools reside. See VOB Storage Pools below.
db	A subdirectory containing the files that implement the VOB's embedded database. See VOB Database.
vob_server.conf	A text file that records configuration information for the vob_server; read at vob_server startup. This file contains the setting for deferred deletion of source containers; deferred deletion is activated if you have turned on semi-live backup. See the vob_snapshot_setup reference page for more information.

The sections that follow discuss the more significant files and subdirectories in a VOB.

VOB Storage Pools

Each VOB storage directory is created with three default storage pools, located within the directories listed above.

s\sdft	Default source storage pool, for permanent storage of versions' file system data.
c\cdft	Default cleartext storage pool, for temporary storage of the cleartext versions currently in use (for example, reconstructed versions of text_file elements).
d\ddft	Default derived object storage pool, for storage of promoted/shared derived objects.

For more information on storage pools, see the mkvob, mkpool, and chpool reference pages.

VOB Database

The VOB database subdirectory, db, contains these files:

vob_db.dbd	A compiled database schema, used by ClearCase embedded DBMS routines for database access. The schema describes the structure of the VOB database. The mkvob command creates this file by copying `ccase-home-dir`\bin\vob_db.dbd.
vob_db_schema_version	A schema version file, used by ClearCase embedded DBMS routines to verify that the compiled schema file is at the expected revision level. The mkvob command creates this file by copying `ccase-home-dir`\bin\vob_db_schema_version.
vob_db.d0`n` vob_db.k0`n`	Files in which the database's contents are stored.
vista.*	Database control files and transaction logs.
db_dumper	A copy of `ccase-home-dir`\bin\db_dumper.exe. This is an executable program, invoked during the reformatvob command's dump phase. Each VOB gets its own copy of db_dumper so that it can always dump itself to ASCII files. (Typically, it needs to be dumped after a newer release of ClearCase has already been installed on the host; with this strategy, the `ccase-home-dir`\bin\db_dumper program in the newer release need not know about the older VOB database format.)
vob_db.str_file	Database string file that stores long strings.

CAUTION: Do not move the VOB database directory (db) to another host. ClearCase uses two server processes, db_server and vobrpc_server, to access a VOB's database. These two server processes and the VOB database directory must be on the host where the VOB storage directory physically resides. Moving the VOB database directory can negatively affect VOB performance and ClearCase's ability to ensure the integrity of the VOB database by recovering from interrupted transactions.

BACKUP DATABASE SUBDIRECTORIES. reformatvob does its work by creating a new VOB database. By default, it preserves the old database by moving it aside to a date-stamped name. Thus, a VOB storage directory may contain old (and usually unneeded) VOB database subdirectories, with names like db.0318. If reformatvob is interrupted, it may leave a partially reformatted database with the name db.reformat.

LOGICAL DATA STRUCTURES

From the user's standpoint, a VOB contains file system objects and metadata. Some metadata is stored in the form of objects; other metadata is stored as records or annotations attached to objects.

The VOB Object and Replica Objects

Each VOB database contains a VOB object that represents the VOB itself. The VOB object provides a handle for certain operations. For example:

Listing event records of operations that affect the entire VOB (see the lshistory command). This includes creation and deletion of type objects, removal of elements, and so on.
Placing a lock on the entire VOB (see the lock command).

Using ClearCase MultiSite, you can create any number of replicas of a VOB at different sites. Each VOB replica is represented in the VOB database by a replica object.

File System Objects

A VOB database keeps track of users' file system objects using the following database objects:

File element	An object with a version tree, consisting of branches and versions. Each version of a file element has file system data: a sequence of bytes. Certain element types constrain the nature of the versions' file system data; for example, versions of text_file elements must contain text lines, not binary data.
Directory element	An object with a version tree, consisting of branches and versions. Each version of a directory element catalogs a set of file elements, directory elements (subdirectories), and VOB symbolic links. An extra name for an element that is already entered in some other directory version is termed a VOB hard link.
VOB symbolic link	An object that contains a text string.

Type Objects

A VOB can store several kinds of type objects:

Element type	Defines a class of elements within the VOB.
Branch type	Defines a set of like-named branches in some or all of the VOB's elements.
Label type	Defines a mnemonic name that can be attached to a set of versions, thus defining a configuration of the VOB's elements.
Attribute type	Defines a name to be used in attaching name/value pairs to VOB-database objects.
Hyperlink type	Defines a class of logical arrow that can be used to connect pairs of objects.
Trigger type	Defines a monitor on operations that modify the VOB's objects.

Instances of Type Objects

After a type object is created, users can create any number of instances of the type.

Element	Each file or directory element in a VOB is created by mkelem or mkdir as an instance of an existing element type in that VOB.
Branch	Each branch in an element is created by mkbranch as an instance of an existing branch type in that element's VOB.
Version label	The mklabel command annotates a version with a version label, by creating an instance of an existing label type.
Attribute	The mkattr command annotates a version, branch, element, VOB symbolic link, or hyperlink with an attribute, by creating an instance of an existing attribute type. Each instance of an attribute has a particular value-a string, an integer, and so on.
Hyperlink	The mkhlink command creates a hyperlink object, which is an instance of an existing hyperlink type. A typical hyperlink connects two objects, in the same VOB or in different VOBs.
Trigger	The mktrigger command creates a trigger object, which is an instance of an existing trigger type. The trigger becomes attached to one or more elements.

Derived Objects

A VOB's database stores information on all the shareable derived objects (DOs) created at pathnames within the VOB. For each DO, the database catalogs this information:

The directory element, along with the location of the DO within the directory (for example, util.o or proj\util.o)
The DO's unique identifier, its DO-ID
Shopping information for the DO

For more information, see Derived Objects and Configuration Records in Building Software with ClearCase.

Configuration Records

A VOB's database stores the configuration records (CRs) associated with shareable derived objects and DO versions (derived objects that have been checked in as versions of elements). Each CR documents a single target-rebuild, which typically involves execution of one build script. For more information, see Derived Objects and Configuration Records in Building Software with ClearCase.

Event Records

ClearCase creates an event record in the VOB database for nearly every operation that modifies the VOB. See the events_ccase reference page for more information.

The vob_scrubber utility deletes unneeded event records. By default, the ClearCase scheduler runs vob_scrubber periodically. See the schedule reference page for information on describing and changing scheduled jobs.

The VOB Root and lost+found Directories

When it is first created by the mkvob command, a VOB appears to users (through its type-MVFS file system mount point) as an almost-empty directory tree. It contains no files, and only two directories: the VOB root and lost+found.

VOB Root Directory - mkvob executes a mkdir command to create a directory element, the VOB root directory, in the new VOB. Mounting a VOB makes its root directory accessible at the VOB-tag (VOB mount point) pathname.

For most purposes, the VOB root directory is like any other ClearCase directory element you subsequently create within the VOB. But there are differences in certain contexts:

The file-name pattern in a config spec rule cannot be a relative pathname that begins at a VOB root directory. A relative pathname must start below a VOB root directory. See the config_spec reference page for details.
You must use a special syntax for a version-extended name that specifies a location in the version tree of a VOB's root directory:

dir \src\proj@@\main\3 (invalid if directory 'proj' is VOB root)

dir \src\proj\.@@\main\3 (valid)

The VOB root directory is assigned to the three default storage pools. All newly created file and directory elements are assigned to the default storage pools until new pools are created and assigned.

The lost+found Directory - mkvob also creates a special directory element, lost+found, as a subdirectory of the VOB root directory. (Only dynamic views can access lost+found.) ClearCase and Attache place elements that are no longer cataloged in any directory version in this directory. This occurs when you do any of the following:

Create new elements, and then uncheckout the directory in which they were created
Delete the last reference to an element with the rmname command
Delete the last reference to an element by deleting a directory version with the rmver, rmbranch, or rmelem command

When an element is moved to lost+found, it gets a name of the form

element_leaf_name.id-number

The id-number is a unique (and rather lengthy) hexadecimal number, such as

41a00000bcaa11caacd0080069021c7

The lost+found directory has several unique properties:

It cannot be checked out.
It can be modified.
No branches can be created within it.

To move an element from the lost+found directory to another directory within the VOB, use the cleartool mv command. To move an element from the lost+found directory to another VOB, use the relocate command.

To conserve disk space, periodically clean up the lost+found directory:

If you need an element in lost+found, catalog it in a versioned directory using mv.
Use rmelem command to remove unneeded elements.

VOB TEXT MODES

Each VOB can operate in either of two modes:

Standard Mode - In this mode, no special provision is made in the VOB for correctly reporting the sizes of text files stored in views created with mkview -tmode msdos. All VOBs are initially created in this mode.
MS-DOS-Enabled Mode - In this mode, the VOB database tracks the number of text lines in each version of each text file. A utility program, msdostext_mode.exe, places a VOB in this mode (or restores it to standard mode).

See Administering ClearCase for detailed information on MS-DOS text mode.

VOB REGISTRY AND VOB ACTIVATION

Each VOB is registered in the network wide storage registry, as described in the registry_ccase reference page. The mount command activates a registered VOB by mounting it as a type-MVFS file system. See the ClearCase mount reference page for details.

VOB