checkvob

Finds and fixes inconsistencies within and between VOBs

Applicability

Product

Command type

ClearCase®

cleartool subcommand

Platform

UNIX

Linux

Windows

Synopsis

  • Check/fix storage pools
    checkvob [ –vie/w view-tag ] [ –log log-dir-pname ]
    [ –fix [ –f/orce ] [ –ign/ore ] [ –process_loc/ked ]]

    [ –dat/a ] [ –pro/tections ] [ –deb/ris ] [ –set/up ]

    {

    –poo/l [ –trs/size max-transaction-size ] [ –sou/rce ] [ –der/ived ] [ –cle/artext ]

    { vob-stg-pname | pname-in-vob } | [ –loc/k ]

    pname ...

    }

  • Check/fix hyperlinks
    checkvob –hli/nks [ –to | –fro/m ] [ –hlt/ype hltype-selector ]
    [ –f/orce ] [ –pna/me ] object-selector ...
  • Check/fix global types
    checkvob –glo/bal [ –log log-pname ] [ –fix [ –f/orce ] ]
    [ –acq/uire ] [ –pro/tections ] [ –loc/k | –unl/ock ]

    { vob-selector | global-type-selector }

  • Check/fix relationships between a UCM PVOB and a project's components or ClearQuest® database
    checkvob –ucm [ –vie/w view-tag ] [ –log log-dir-pname]
    [ –fix [ –f/orce ] ]

    [ –verbose ] [ –crm_only | –vob/_only ]

    [ –com/ponent component-selector ] object-selector...

  • Find evil twins:
    checkvob –evil_twin [ –view view-tag ] [ vob-tag ]
  • Chec/fix rolemap protections:
    checkvob –rolemap_protect [ –view view-tag ] [ –fix ] [ vob-tag ]

Description

checkvob can find and fix problems with storage pools, with hyperlinks, and with global types in an administrative VOB hierarchy. It can also find and fix inconsistencies between PVOBs, components, and an optional ClearQuest database in a UCM environment. For more information, see the DevOps Code ClearCase Administrator's Guide.

Restrictions

Identities

For –fix, you must have one of the following identities:

  • VOB owner
  • root (UNIX and Linux)
  • Member of the ClearCase administrators group (ClearCase on Windows)

For –hlinks, you must have one of the following identities:

  • Object owner
  • Object group member
  • VOB owner
  • root (UNIX and Linux)
  • Member of the ClearCase administrators group (ClearCase on Windows)

Locks

Without –fix (check-only mode), no locks apply. With –fix, the following restrictions apply:

  • The VOB must be unlocked (or locked with lock –nusers user-running-checkvob).
  • Problems cannot be fixed if the affected object is locked.

It may be difficult to fix ownership and naming problems with global types if local copies or eclipsing ordinary types are locked.

Mastership

(Replicated VOBs only) No mastership restrictions.

Options and arguments

The following sections describe the options and arguments for storage pool mode, hyperlink mode, global types mode, and UCM mode. For more information about fix-mode processing, see the DevOps Code ClearCase Administrator's Guide.

Storage pool mode

Specifying a view

Default
Uses the current view context. If you attempt to run checkvob without a view context, you are prompted to continue. Without a view context, checkvob cannot generate VOB pathnames in problem object reports, so it reports OIDs instead of pathnames. In general, run checkvob from a view.
–vie/w view-tag
Uses view view-tag to resolve any pname arguments, and to construct VOB object pathnames in output. This option exists primarily to permit checkvob to run on VOB servers where the MVFS is not installed (hosts where you cannot establish a working view context). When used with this option, the pname argument must specify a directory. This example is valid:

checkvob -view myview  /vobstore/v1

whereas this example is invalid:

checkvob -view myview  /vobstore/v1/e4.txt 

Log file directory

Default
checkvob creates in the current directory a log file directory named checkvob.date-time. With –pool, several log files are created, including a summary file and one file per pool analyzed. Otherwise, a single transcript file stores a report on each individual file examined.
–log log-dir-pname
Specifies an alternative directory for the log file directory. If log-dir-pname exists, checkvob returns an error.

Fix mode

Default
Reports any problems, but does not try to fix them.
Important:

Fixing problems detected with –data can update the VOB irreversibly. If source or DO data containers are missing from the storage pools when checkvob runs, it updates the VOB database, dereferencing these containers with the equivalents of rmver -data (for missing source containers) and rmdo (for missing DO containers).

–fix
Directs checkvob to try to correct any problems it finds. Without –force, –fix prompts you before fixing any problem object. You must run checkvob from the VOB server host to use –fix.

For details about how checkvob tries to fix the various problems it detects, see the DevOps Code ClearCase Administrator's Guide.

–f/orce
Minimizes interactive prompts when checkvob runs with –fix.
–ign/ore
Ignores element and pool locks during fix processing. Use of –ignore requires that the VOB be locked for all users except the user running checkvob (lock –nusers). This option is not recommended for general use. It exists primarily to support automatic checkvob invocations when vob_restore is run.
–process_loc/ked

By default, the checkvob command skips an element that is already locked and indicates the element was skipped. The checkvob command can analyze the locked element for a problem if invoked with the -process_locked argument. Additionally, the checkvob [-process_loc/ked] command indicates for any issue found in the locked element, though the issue cannot be fixed.

Database/pool inconsistencies

Default
Scans pools or individual file containers looking for all detectable problems.
–dat/a
Identifies missing data containers. checkvob scans the VOB database and source pools to confirm the existence of each data container known to the database.
Note:

During check processing, a "healthy" element is one whose containers have the right names, in the right locations, with the right permissions. checkvob does not detect container data corruption.

–pro/tections
Identifies access control problems on data containers.
–deb/ris
Scans storage pools for data containers not referenced by the VOB database. –debris is meaningful only when used with –pool. In general, checkvob –fix –debris moves debris to the applicable pool's lost_found directory. See the DevOps Code ClearCase Administrator's Guide for details.

Setup mode

Default
None. Specify –setup to run checkvob in setup mode.
–set/up
Prepares newly reformatted VOB for checkvob processing.

Prepares a VOB for vob_snapshot/vob_restore/checkvob processing. See the DevOps Code ClearCase Administrator's Guide.

Pool mode

When checking/fixing the storage pools of a feature level 8 VOB, checkvob –pool compares and shows the file ACLs instead of file mode for the pool container files. If there is a misprotected pool container file, the command displays a container problem report that lists the expected and actual protections of the pool.

Default
None. Specify –pool and a vob-stg-pname argument in order to process one or more storage pools.
–poo/l
Runs checkvob in pool mode. See the DevOps Code ClearCase Administrator's Guide.
–sou/rce –der/ived –cle/artext
Processes the VOB's source, derived object (DO), and/or cleartext pools. If you omit all of these options, checkvob processes all pool kinds.
vob-stg-pname pname-in-vob
Identifies the VOB; required with –pool.
–trs/size max-transaction-size
Specify the maximum size of any database transaction that checkvob holds during pool mode processing. max-transaction-size is an integer value between 1 and 128. The default is 64. Lower values for max-transaction-size reduce the length of time that VOB locks are held during pool mode processing, but increase the length of time that checkvob requires to complete the processing.

Individual file mode

Default
None. If you do not use the –pool option, you must specify one or more file-pname arguments.
–loc/k
Locks each element during check processing. checkvob always locks an element during fix processing.
file-pname ...
Specifies one or more VOB objects having associated data containers—file elements, versions, or DOs. checkvob compares each data container's location and permissions against what is expected by the VOB database.

Hyperlink mode

Hyperlink mode

Default
None. Use –hlinks to run checkvob in hyperlink mode. checkvob prompts for confirmation before deleting each partially unavailable hyperlink it detects.
Important:

Do not run checkvob –hlinks on a UCM VOB before you run checkvob –ucm. checkvob –hlinks may prompt you to remove hyperlinks that checkvob –ucm could fix. Unless you are certain that checkvob has found a cross-VOB hyperlink that refers to a VOB that has been deleted, accept the default and leave the hyperlink in place. This is especially important when using MultiSite. Hyperlink removals performed by checkvob –hlinks are replayed at other replicas where the hyperlinks may still be valid, which can cause problems for administrative VOB hierarchies.

–hli/nks
Runs checkvob in hyperlink mode.
–to , –fro/m
Checks only hyperlinks to or from the specified objects.
–hlt/ype hyperlink-type-selector
Checks only hyperlinks of type hyperlink-type-selector. Specify hyperlink-type-selector in the form hltype:type-name[@vob-selector]

Table

type-name

Name of the hyperlink type

vob-selector

Object-selector for a VOB, in the form [vob:]pname-in-vob. The pname-in-vob can be the pathname of the VOB tag (whether or not the VOB is mounted) or of any file system object within the VOB (if the VOB is mounted).

–f/orce
Deletes broken hyperlinks without prompting for confirmation.
–pna/me
Interprets each object-selector argument as a pathname.
object-selector ...
Specifies the objects whose broken hyperlinks are to be found and deleted. Note that if you specify a VOB, checkvob does not check all hyperlinks in that VOB; it checks only the hyperlinks attached to the VOB object itself. Specify object-selector in one of the following forms:
  • A standard or view-extended pathname to an element specifies the version in the view.
  • A version-extended pathname specifies an element, branch, or version, independent of view.
  • The pathname of a VOB symbolic link.
Note:

If pname has the form of an object selector, you must include the –pname option to indicate that pname is a pathname.

Table object-selector

vob-selector

vob:pname-in-vob

pname-in-vob can be the pathname of the VOB tag (whether or not the VOB is mounted) or of any file system object within the VOB (if the VOB is mounted). It cannot be the pathname of the VOB storage directory.

attribute-type-selector

attype:type-name[@vob-selector]

branch-type-selector

brtype:type-name[@vob-selector]

element-type-selector

eltype:type-name[@vob-selector]

hyperlink-type-selector

hltype:type-name[@vob-selector]

label-type-selector

lbtype:type-name[@vob-selector]

trigger-type-selector

trtype:type-name[@vob-selector]

pool-selector

pool:pool-name[@vob-selector]

oid-obj-selector

oid:object-oid[@vob-selector]

policy-selector

policy:policy-name[@vob-selector]

rolemap-selector

rolemap:rolemap-name[@vob-selector]

The following object selector is valid only if you use MultiSite:

replica-selector

replica:replica-name[@vob-selector]

Global types mode

Global types mode

Default
None. You must specify –global.
–global
Runs checkvob in global types mode.

Log file

Default
checkvob creates in the current directory a file named checkvob.date.time.
–log log-pname
Specifies an alternative pathname for the log file. If log-pname exists, checkvob returns an error.

Fix mode

Default
Reports any problems, but does not try to fix them.
–fix
Directs checkvob to try to correct any problems it finds. Without –force, –fix prompts you before fixing any problem object.

For details on how checkvob tries to fix the various problems it detects, see the DevOps Code ClearCase Administrator's Guide.

–f/orce
Minimizes interactive prompts when checkvob runs with –fix.
–acquire
Lists/fixes eclipsing local copies and eclipsing ordinary types
–protections
Lists/fixes mismatched protections between global types and their local copies.
–lock , –unlock
Lists/fixes eclipsing local locks. In fix mode, –lock locks the global type and –unlock removes the lock entirely.
vob-selector
Specifies a VOB in an administrative VOB hierarchy. checkvob checks/fixes all global types found in the hierarchy. Specify vob-selector in the form vob:pname-in-vob

pname-in-vob can be the pathname of the VOB tag (whether or not the VOB is mounted) or of any file system object within the VOB (if the VOB is mounted). It cannot be the pathname of the VOB storage directory.

global-type-selector
Specifies a global type to be checked for problems. Specify global-type-selector in one of the following forms:

Table global-type-selector

ute-type-selector

attype:type-name[@vob-selector]

branch-type-selector

brtype:type-name[@vob-selector]

element-type-selector

eltype:type-name[@vob-selector]

hyperlink-type-selector

hltype:type-name[@vob-selector]

label-type-selector

lbtype:type-name[@vob-selector]

UCM modes

Default
None. You must specify –ucm.
–ucm
Runs checkvob in UCM mode. There are two variants of this mode: one checks a PVOB to verify the references it holds to objects in component VOBs or records in an optional ClearQuest database, and can also check a component to verify its UCM branch and label types. The other checks a ClearQuest database to verify the references it holds to UCM objects in a PVOB.

Specifying verbosity

Default
Logs informational messages and error messages.
–verbose
Logs additional diagnostic output.

Specifying a view

Default
Uses the current view.
–vie/w view-tag
Uses the view specified in view-tag.

Restricting the search

Default
Examines references held by a PVOB to objects in all component VOBs and also to records in a ClearQuest database. These options do not apply when operating on a component VOB.
–crm_only
Examines only references to records in a ClearQuest database
–vob/_only
Examines only references to objects in components.
–com/ponent component-selector
Further restricts a –vob_only check to the component specified by component-selector
object-selector...
Specifies one or more object types to check. The type of object specified determines the type of VOB (PVOB or component) checked and the method of correcting inconsistencies if –fix is specified. Any of the following object types are allowed:

Object type

Check/fix behavior

Activity

(activity:activity-name[@vob-selector])

Verifies that activity-name has a valid change set. –fix removes invalid references to versions in component VOBs

Baseline

(baseline:baseline-name[@vob-selector])

Verifies that baseline-name has valid references to objects in the PVOB. –fix removes invalid references

Stream

(stream:stream-name[@vob-selector])

Verifies that stream-name has valid references to objects in the PVOB. –fix removes invalid references

Project

(project:project-name[@vob-selector])

Verifies that references to modifiable components are valid. Verifies that the project references a valid ClearQuest database. Checks all streams, baselines, and activities in the project. –fix removes invalid references

Folder

(folder:folder-name[@vob-selector])

Checks all projects in the folder and reports problems. To fix, rerun checkvob –ucm –fix and specify the appropriate project, stream, baseline, or activity object.

Component

(component:component-name[@vob-selector])

Verifies that references to component root directories and component initial baselines held by the PVOB are valid. Reports problems but cannot fix them.

Project VOB

(vob:vob-tag )

Checks all objects in the PVOB and reports problems. To fix, rerun checkvob –ucm –fix and specify the appropriate project, stream, baseline, or activity object.

Branch type

(brtype:type-name[@vob-selector])

Checks the specified branch type and all versions on the branch in the specified component VOB. –fix recovers versions to a new activity.

Label type

(lbtype:type-name[@vob-selector])

Checks the specified label type in the specified component VOB. –fix re-creates GlobalDefinition hyperlinks as required.

Component VOB

(vob:vob-tag)

Checks all UCM branch and label types in the specified component and reports problems. To fix, rerun checkvob –ucm –fix and specify the appropriate branch or label type.

Checking a ClearQuest database

Default
None. Unless you specify –crm_dbname, checkvob –ucm checks references held by a PVOB to objects in component VOBs and records in a ClearQuest database.
–crm_db/name user-database-name
Checks the references held in the ClearQuest database specified by user-database-name. You must use one of the –activity or –project options to specify an activity or a project record to check.
–act/ivity cq-display-name
Checks the references held by the activity record specified in cq-display-name, which must be an activity ID in the ClearQuest database.
–pro/ject cq-display-name
Checks the references held by the project record specified in cq-display-name, which must be a project name in the ClearQuest database.

Checking for the presence of evil twins

Default
None.
–evil_twin
Checks the VOB for the presence of evil twins. Evil twins are elements of the same name that have been created in different versions of the same directory element.

Checking and fixing rolemap protections

Default
Check only.
–rolemap_protect
Find objects that have not been explicitly assigned to a rolemap and that are not associated with the DefaultRolemap. This mode requires a view context.
–fix
Associate unprotected objects with the DefaultRolemap.

Examples

The UNIX system and Linux examples in this section are written for use in csh. If you use another shell, you might 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 might 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 system and Linux shells or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

Note: In this manual, a multicomponent VOB tag is by convention a two-component VOB tag of the form /vobs/vob-tag-leaf; for example, /vobs/src. A single-component VOB tag consists of a leaf only; for example, /src.
  • Check a single element's data container.

    cmd-context checkvob /vobs/lib/gui.c
    The session's log directory is 'checkvob.2006-04-11T05:21:17'.

    =================================================================
    Processing element "/vobs/lib/gui.c@@".
    Checking status of 1 referenced containers in pool "s/sdft"...
    Initial container status: 0 missing, 0 misprotected.
    =================================================================

  • On a Windows system, perform a routine check on a small, healthy VOB's source pools.

    cmd-context lsvob \vob_lib2
    * \vob_lib2    \\saturn\vobstore\vob_lib2.vbs
    cmd-context  checkvob –pool –source \\saturn\vobstore\vob_lib2.vbs
    ============================================================
    Starting "source pool" processing at 2006-04-10T06:35:11

    Running from host: saturn
    VOB hostname: saturn
    VOB host storage pathname: C:\vobstore\lib2.vbs
    VOB global storage pathname: \\saturn\vobstore\lib2.vbs
    VOB replica oid: 0cdc7b37.f48611cc.b3d5.00:01:80:02:bc:53
    VOB host reference time: 2006-04-10T06:29:59
    Processing pools: sdft
    Processing of misprotected containers is: ENABLED
    Processing of ndata containers is: ENABLED
    Processing of unreferenced containers is: ENABLED
    Fix processing mode: DISABLED

    Poolkind transcript log:
    checkvob.2006-04-20T12.10.40\poolkind_source\transcript
    =================================================================

    ... progress messages ...

    =========================================================
    Completed "source pool" processing at 2006-04-10T06:35:37

    "source pool" Processing Summary:
    Referenced Container Check Processing Time: 00:00:20
    *** Referenced Container Fix Processing was not performed.
    Unreferenced Container Check Processing Time: 00:00:05
    *** Unreferenced Container Fix Processing was not performed.

    Installed type managers are OK.

    Pool root storage areas are OK.

    Pool: s\sdft
    Referenced container check processing:
        229 containers checked
                 0 ndata          0 misprotected
        22 objects checked
                 0 ndata          0 misprotected
    Unreferenced container check processing:
        229 containers checked     (47778 kbytes)
                 0 unreferenced but under age      (0 kbytes)
                 0 unreferenced but maybe needed   (0 kbytes)
        0 unreferenced containers (0 kbytes, 0 empty)


    The VOBs source pools are healthy.

    Poolkind transcript log:
           checkvob.2006-04-20T12.10.40\poolkind_source\transcript
    =================================================================

  • Check all global types in the admin VOB hierarchy containing the VOB /vobs/dev.

     cmd-context checkvob –global vob:/vobs/dev

    The session's log file is "checkvob.2007-07-30T17:28:55".
    Starting analysis of Admin VOB hierarchy.


    Analysis of Admin VOB hierarchy complete.
    5 VOBs analyzed, no hierarchy errors found.

    Starting "global type" processing.

    Detection of eclipsing local copies is: ENABLED
    Detection of protection mis-matches is: ENABLED
    Detection of eclipsing local locks is: ENABLED
    Correction of detected errors is: DISABLED

    Completed "global type" processing.
    Processed 8 global types in 5 VOBs.

  • Find and fix obects of vob:vobs/vob1 that have not been explicitly assigned to a rolemap.
    cleartool checkvob -rolemap_protect -fix -view view1 vob:/vobs/vob1

UNIX and Linux files

  • current-dir/checkvob.date-time (default log-pname for –global)
  • current-dir/checkvob.date-time/  (default log-dir)
  • log-dir/.summary
  • log-dir/poolkind_cleartext/transcript
  • log-dir/poolkind_derived/transcript
  • log-dir/poolkind_source/transcript
  • log-dir/summary
  • vob-storage-dir/s/sdft/pool_id
  • vob-storage-dir/c/cdft/pool_id
  • vob-storage-dir/d/ddft/pool_id

Windows files

  • current-dir\checkvob.date-time (default log-pname for –global)
  • current-dir\checkvob.date-time\  (default log-dir)
  • log-dir\.summary
  • log-dir\poolkind_cleartext\transcript
  • log-dir\poolkind_derived\transcript
  • log-dir\poolkind_source\transcript
  • log-dir\summary
  • vob-storage-dir\vob_server.conf
  • vob-storage-dir\s\sdft\pool_id
  • vob-storage-dir\c\cdft\pool_id
  • vob-storage-dir\d\ddft\pool_id