Command Reference, Release 2002.05.00, All Platforms

reformatvob

Updates the format of a VOB database.

APPLICABILITY


Product	Command Type
ClearCase	cleartool subcommand
ClearCase LT	cleartool subcommand
Attache	command


Platform
UNIX
Windows

SYNOPSIS

ClearCase and Attache on UNIX:

reformatvob [ -dum·p | -loa·d ] [ -rm ] [ -f·orce ] [ -to dumpfile-dir-pname ]: [ -hos·t hostname -hpa·th local-pname -gpa·th global-pname ]
vob-storage-dir-pname

ClearCase and Attache on Windows:

reformatvob [ -dum·p | -loa·d ] [ -rm ] [ -f·orce ]: [ -hos·t hostname -hpa·th local-pname -gpa·th global-pname ] vob-storage-dir-pname

ClearCase LT on UNIX:

reformatvob [ -dum·p | -loa·d ] [ -rm ] [ -f·orce ] [ -to dumpfile-dir-pname ] vob-storage-dir-pname

ClearCase LT on Windows:

reformatvob [ -dum·p | -loa·d ] [ -rm ] [ -f·orce ] vob-storage-dir-pname

DESCRIPTION

NOTE: Always back up a VOB's storage directory before using this command.

reformatvob is a one-way command. The dump and load phases must be allowed to complete (although they can take place at different times). You cannot abort and undo a reformat operation after you have started it; you can only restart and complete the operation.

reformatvob changes the format of a VOB database from a format used in a previous release of ClearCase or ClearCase LT to the current format. A new release may use a different database format to support new product features, to enhance storage efficiency, or to improve performance.

reformatvob also performs the actions of the checkvob -setup command. This checkvob setup processing must be completed to use the checkvob command. If this processing is interrupted during the reformatvob command execution, you must run the checkvob command manually. (See the checkvob reference page for details.)

You can also use reformatvob for other purposes:

In ClearCase and Attache, to move a VOB storage directory between hosts of different architectures, that is, hosts with different binary formats for the files that implement the VOB database

In ClearCase, Attache, and ClearCase LT, to clean up a VOB database, physically deleting records that have been logically deleted by vob_scrubber

In both cases, the VOB database has the same internal format, and checkvob -setup is not invoked.

reformatvob locks the VOB before reformatting it. If the VOB is already locked, reformatvob proceeds with the reformatting and then unlocks the VOB.

NOTE: reformatvob does not overwrite the old, invalid VOB database; it renames the old database to db.date. The old database remains in the VOB storage directory until you delete it with a standard operating system command.

reformat_vob Internals

The information in this section is rpovided as background information only. following programs are called by the reformatvob command to update a VOB database. Neither is intended to be invoked directly by administrators.

The db_dumper program converts binary VOB database files to ASCII files.

The db_loader program reads the ASCII files, creating a new VOB database that uses the up-to-date schema.

The bahvior of these programs varies according to platform, as described in the following sections.

UNIX Systems-reformatvob activates /usr/atria/etc/dumpers/db_dumper.num, where num is the revision level of the VOB. (This value is stored in the vob_db_schema_version file located in the VOB's db subdirectory.) If reformatvob cannot find a matching db_dumper, it invokes the VOB's own copy of db_dumper: when the VOB is created with mkvob, a db_server running on the VOB host copies file ccase-home-dir/etc/db_dumper into the new VOB's database subdirectory and changes its access mode to 4555. The db_server runs as root; thus, the VOB's copy of db_dumper becomes a setUID-root program.

When loading a VOB database, reformatvob always invokes the same program: ccase-home-dir/etc/db_loader. This is a setUID-root program. (Running site_prep on the networkwide release host sets the permissions on the original; installation on an individual host preserves the permissions. See the Installation Guide for details.)

If reformatvob is using the copy of db_dumper stored within the VOB storage directory, it may fail with a message that db_dumper has the wrong permissions and/or ownership:

cleartool: Error: Database dumper "vob-storage-dir/db.reformat/db_dumper" must be setUID and owned by the super-user.

Note that the pathname to db_dumper is a location within the VOB's database subdirectory, which has been renamed by reformatvob to db.reformat. Enter the following commands to fix the problem; be sure to enter the pathname of the db_dumper program exactly as it appears in the error message.

% su root

Password: <enter root password>

% chown root vob-storage-dir/db.reformat/db_dumper

% chmod 4555 vob-storage-dir/db.reformat/db_dumper

% exit

The db_loader program is not setUID-root, and thus does not work correctly, if the ccase-home-dir/etc/db_loader file is located on a remote host and the local host accesses this program through a file-system mount that uses a nosuid option.

Windows Systems-reformatvob invokes a VOB's own copy of db_dumper: when the VOB is created with mkvob, a db_server running on the VOB host copies file ccase-home-dir\bin\db_dumper.exe into the new VOB's database subdirectory.

When loading a VOB database, reformatvob always invokes the same program: ccase-home-dir\bin\db_loader.

RESTRICTIONS

Identities: You must have one of the following identities:

VOB owner

root (UNIX)
Member of the ClearCase group (ClearCase on Windows)
Local administrator of the ClearCase LT server host (ClearCase LT on Windows)

Locks: No locks apply.

Mastership: (Replicated VOBs) No mastership restrictions.

Other: In ClearCase and Attache, the VOB storage directory must physically reside on either the host where you enter this command or a supported network-attached storage device mounted by that host. In ClearCase LT, you must enter this command at the ClearCase LT server host.

In all cases, the current working directory must not be at or below the VOB storage directory. Your shell or command interpreter must not have a set view context or working directory view context.

OPTIONS AND ARGUMENTS

PARTIAL REFORMAT. Default: Performs a complete reformat, including both the dump and load phases.

-dum·p: Performs only the first phase of the reformatting process-creating an ASCII dump of the current VOB database.
-loa·d: Performs only the second phase of the reformatting process-creating a new VOB database using a previously created ASCII dump.

PRESERVING A BACKUP OF THE VOB DATABASE. Default: The original VOB database directory (subdirectory db of the VOB storage directory) is preserved through renaming. During the dump phase, it is renamed to db.reformat; during the load phase, it is renamed again, to a name that includes a date stamp (for example, db.02.18).

-rm: Deletes the original VOB database during the load phase.

CONFIRMATION STEP. Default: Before beginning its work, reformatvob prompts you to confirm that you want to reformat the VOB database.

-f·orce: Suppresses the confirmation step.

ALTERNATE LOCATION FOR ASCII DUMP FILES. Default: The dump phase creates the ASCII dump files within the VOB storage directory.

-to dumpfile-dir-pname: (Do not use in conjunction with -load) Creates the ASCII dump files within the specified directory, which must not already exist.

VOB REGISTRY OPTIONS. Default: Using the vob-storage-dir-pname argument, reformatvob creates or updates the vob_object registry file; it leaves the vob_tag registry file unchanged. The following options update the VOB-tag entry.

-hos·t hostname
-hpa·th local-pname
-gpa·th global-pname: See the mkstgloc reference page for information on these options.

SPECIFYING THE VOB. Default: None.

vob-storage-dir-pname: The pathname of a VOB storage directory. If you use ClearCase or Attache, also refer to the descriptions of -host, -hpath, and -gpath in the mkstgloc reference page.

EXAMPLES

The UNIX examples in this section are written for use in csh. If you use another shell, you may need to use different quoting and escaping conventions.

The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.

In cleartool single-command mode, cmd-context represents the UNIX shell or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt. In Attache, cmd-context represents the workspace prompt.

Reformat a VOB whose storage directory is /home/jones/tut/tut.vbs.

NOTE: This example shows selected status messages only; reformatvob actually produces more verbose messages. See the checkvob reference page for the setup output.

% cd

cmd-context reformatvob /home/jones/tut/tut.vbs Reformat versioned object base "/home/jones/tut/tut.vbs"? [no] y Dumping database... Dumper done. Dumped versioned object base "/home/jones/tut/tut.vbs". Loading database... Loader done. Loaded versioned object base "/home/jones/tut/tut.vbs".