checkvob
Finds and fixes inconsistencies within and between VOBs
Applicability
Product |
Command type |
---|---|
VersionVault |
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
- 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. For more information, see the Help.
Restrictions
Identities
For –fix, you must have one of the following identities:
- VOB owner
- root (UNIX® and Linux®)
- Member of the VersionVault administrators group (VersionVault 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 VersionVault administrators group (VersionVault 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 Help.
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 Help.
- –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 Help 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 Help.
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 Help.
- –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 Help.
- –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. Checks a PVOB to verify the references it holds to objects in component VOBs, and can also check a component to verify its UCM branch and label types.
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. These options do not apply when operating on a component VOB.
- –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. 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 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 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 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.
- 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