Rational ClearCase Commands Reference: dospace

Commands Index:

  * intro
  annotate
  apropos
  catcr
  catcs
  cc.icon
  cc.magic
  cd
  chactivity
  chbl
  checkin
  checkout
  checkvob
  chevent
  chflevel
  chfolder
  chmaster
  chpool
  chproject
  chstream
  chtype
  chview
  clearaudit
  clearbug
  cleardescribe
  cleardiffbl
  cleardiff
  clearexport_ccase
  clearexport_cvs
  clearexport_pvcs
  clearexport_rcs
  clearexport_sccs
  clearexport_ssafe
  clearfsimport
  cleargetlog
  clearhistory
  clearimport
  clearjoinproj
  clearlicense
  clearmake
  clearmake.options
  clearmrgman
  clearprojexp
  clearprompt
  cleartool
  clearviewupdate
  clearvobadmin
  comments
  config_ccase
  config_spec
  cptype
  credmap
  creds
  deliver
  describe
  diffbl
  diffcr
  diff
  dospace
  edcs
  endview
  env_ccase
  events_ccase
  export_mvfs
  exports_ccase
  file
  find
  findmerge
  fmt_ccase
  getcache
  get
  getlog
  help
  hostinfo
  init_ccase
  ln
  lock
  lsactivity
  lsbl
  lscheckout
  lsclients
  lscomp
  lsdo
  lsfolder
  lshistory
  ls
  lslock
  lsmaster
  lspool
  lsprivate
  lsproject
  lsregion
  lsreplica
  lssite
  lsstgloc
  lsstream
  lstype
  lsview
  lsvob
  lsvtree
  makefile_aix
  makefile_ccase
  makefile_gnu
  makefile_pmake
  makefile_smake
  makefile_sun
  man
  merge
  mkactivity
  mkattr
  mkattype
  mkbl
  mkbranch
  mkbrtype
  mkcomp
  mkdir
  mkelem
  mkeltype
  mkfolder
  mkhlink
  mkhltype
  mklabel
  mklbtype
  mkpool
  mkproject
  mkregion
  mkstgloc
  mkstream
  mktag
  mktrigger
  mktrtype
  mkview
  mkvob
  mount_ccase
  mount
  msdostext_mode
  mvfslog
  mvfsstorage
  mvfstime
  mvfsversion
  mv
  omake
  pathnames_ccase
  permissions
  profile_ccase
  promote_server
  protect
  protectvob
  pwd
  pwv
  query_language
  quit
  rebase
  recoverview
  reformatview
  reformatvob
  register
  relocate
  rename
  reqmaster
  reserve
  rgy_backup
  rgy_check
  rgy_passwd
  rgy_switchover
  rmactivity
  rmattr
  rmbl
  rmbranch
  rmcomp
  rmdo
  rmelem
  rmfolder
  rmhlink
  rmlabel
  rmmerge
  rmname
  rmpool
  rmproject
  rmregion
  rmstgloc
  rmstream
  rmtag
  rmtrigger
  rmtype
  rmver
  rmview
  rmvob
  schedule
  schemes
  scrubber
  setactivity
  setcache
  setcs
  setplevel
  setsite
  setview
  shell
  snapshot.conf
  softbench_ccase
  space
  startview
  type_manager
  umount
  uncheckout
  unlock
  unregister
  unreserve
  update
  version_selector
  view_scrubber
  vob_restore
  vob_scrubber
  vob_sidwalk
  vob_snapshot
  vob_snapshot_setup
  wildcards_ccase
  winkin
  xclearcase
  xcleardiff
  xmldiffmrg

dospace

Reports on VOB disk space used for shared derived objects

APPLICABILITY

Product	Command type
ClearCase	cleartool subcommand

Platform
UNIX
Windows

SYNOPSIS

Report VOB disk space used for shared derived objects:
dospace [ –upd·ate ] [ –sin·ce date-time ] [ –bef·ore date-time ]
[ –ref·erences {0,1,n} ]
[ –top number | –a·ll ] [ –siz·e size ] [ –reg·ion network-region ]
[ –poo·l pool-name ] vob-tag ...
Report disk space in raw format:
dospace [ –upd·ate ] –dum·p [ –reg·ion network-region ] vob-tag...
Generate and cache data on disk space used for local VOBs:
dospace –gen·erate [ –scr·ub days ] [ vob-tag ... ]

DESCRIPTION

The dospace command displays data on VOB disk space used for shared derived objects. The report shows which views refer to shared DOs and shows how much disk space is used by the shared DOs that each view refers to.

You can use this information to identify views that should no longer refer to the DOs. Removing references to the DOs in those views can allow the disk space used by the DOs in the VOB to be reclaimed. When a DO no longer appears in any view, the scrubber utility, usually run as a periodically scheduled job, can remove the DO and its associated storage from the VOB.

The dospace command has a number of options that determine the range of derived objects and views it reports. By default, the command displays total disk space used for DOs in the specified VOBs and then lists the top 10 views in order of disk space used by DOs that appear in those views.

By default, dospace uses previously generated, cached data. The –update option generates fresh data and updates the cache before displaying the report.

The –generate option is intended for use by scheduled jobs. By default, the ClearCase scheduler periodically runs dospace with the –generate option to generate and cache data on disk space used by derived objects for all local VOBs. For information about describing and changing scheduled jobs, see the schedule reference page.

RESTRICTIONS

Identities

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

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

Locks

No locks apply.

Mastership

(Replicated VOBs only) No mastership restrictions.

Other

With –update, you must have Change or Full access in the ClearCase scheduler ACL on the host where each VOB storage directory resides. See the schedule reference page.

OPTIONS AND ARGUMENTS

Specifying Creation Times of DOs in the Report

Default: No restrictions.
–sin·ce date-time: Restricts the report to DOs that were last accessed at or after date-time. For the format of date-time, see the lshistory reference page.
–bef·ore date-time: Restricts the report to DOs that were last accessed before date-time. For the format of date-time, see the lshistory reference page.

Specifying Reference Counts of DOs in the Report

Default: Reports disk space used by DOs with reference counts greater than or equal to 1.
–ref·erences {0,1,n}: Restricts the report to DOs with the specified reference counts. The reference count is the number of views in which a DO appears. A value of n reports on DOs that appear in two or more views. Each time the DO is winked in to another view, its reference count is incremented. Each time the DO is deleted from a view, its reference count is decremented.

Specifying Number of Views in the Report

Default: Lists top 10 views in space used.
–top number | –a·ll: Restricts the report to the top number of views (default 10) in amount of VOB disk space used by DOs that appear in those views. The –all option reports all views that have references to DOs in the specified VOBs, subject to any restrictions imposed by other options.

Specifying Minimum Disk Space Used by Each View in the Report

Default: No restrictions.
–siz·e size: Restricts the report to those views each of which accounts for at least size kilobytes of VOB disk space used by DOs that appear in that view.

Specifying the Storage Pool

Default: All derived object pools.
–poo·l pool-name: Restricts disk space data in the report to the derived object storage pool whose name is pool-name.

Specifying the VOB

Default: For the –generate option, all local VOBs. Otherwise, no default; you must specify a VOB tag.
vob-tag ...: One or more VOB tags that specify the VOBs to report. Each VOB tag must be valid in the region specified by –region.
–reg·ion network-region: Specifies the network region in which each vob-tag resides. The default is the region of the local host.

Reporting Raw Data

Default: Formatted report data.
–dum·p: Reports data in a raw form, with no filtering options (such as –since or –size) applied. This form is intended for use by user-created scripts or other programs that do advanced data analysis or formatting.

Displaying and Caching Up-To-Date Data

Default: Uses cached data.
–upd·ate: Computes and caches data on DO disk space used at the time the command is issued, instead of using cached data, and then displays a report. The computation can take a significant amount of time.

Generating, Caching, and Scrubbing Data

Default: None.
–gen·erate: Computes and caches data on DO disk space used at the time the command is issued but does not display a report. The VOB storage directories for all specified VOBs must reside on the local host. If no vob-tag argument is specified, the command generates data for all VOBs on the local host. The computation can take a significant amount of time. This option is intended to be used by periodic jobs run by the ClearCase scheduler.
–scr·ub days: Deletes cached records of data on DO disk space used that are older than the specified number of days. A value of –1 deletes all cached records other than the one generated by the current invocation of the command, if any. This option is intended to be used in conjunction with the –generate option by periodic jobs run by the ClearCase scheduler. The default scheduled job specifies a value of –1 for the –scrub option.

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.

Report the top 10 views in disk space used by DOs each of which appears in only one view.
cmd-context dospace –references 1 /projects/bigapp
K Bytes Date.Time VOB 141284 25-Jul-99.01:51:53 /projects/bigapp K Bytes View 11026 dave 7722 sue_bl4 7500 cindy_v3.2.1 7224 release 6263 jack_build 5159 terry_v4 4871 v3.2.1.win -region rd_windows 4855 birdseye 4268 v3.2.win -region rd_windows 3903 andrea_40
Report disk space used by DOs last accessed before June 1, 1999, and list all views that account for at least 3 MB each of DO space.
cmd-context dospace –before 01-Jun-1999 –all –size 3000 \bigapp
Using 02-May-99.01:45:06 ("3 months") for before date.time. 01-Jun-99.01:45:06 ("2 months") is next before bucket. K Bytes Date.Time VOB 159562 01-Aug-99.01:51:53 \bigapp K Bytes View 28734 v3.1.1_pfm.re 28734 v3.1.1_pfm.bld 19208 v3.1.1.bld 19197 v3.1.1.re 14169 dave 7501 cindy_v3.2.1 7231 release 4866 birdseye 4102 v3.2.win 3987 kim_v3.2 3714 v3.2_pfm.bld 3587 sue_mtypes 3538 proj_v3.nt 3386 [uuid: f532a8f2.afb711d2.a4e2.00:01:72:31:df:c2] machine1:c:\users\jack\jack_v3.3
Generate and cache data on disk space used by DOs in a VOB and then report the top 10 views in disk space used.
cmd-context dospace –update /projects/bigapp
Job is running on remote host ("server1"), waiting for it to finish. .......... Job completed successfully on remote host ("server1"). K Bytes Date.Time VOB 371523 01-Aug-99.01:45:06 /projects/bigapp K Bytes View 30428 v3.2.1.bld 30329 v3.1.1_rev.bld 30329 v3.1.1_rev.re 29986 joe_v4.0_merge 29905 v3.2.1.re 29888 v3.2_rev.bld 28152 v3.2_rev.re 26549 winapp_v4.0.bl4.nt -region rd_windows 25670 v3.2.1.bld 25663 v3.2.1.re
Report disk space used by DOs in raw format.
cmd-context dospace –dump \smallapp
start time: 932879789 run time: 14 bucket 0: 86400 1 day bucket 1: 259200 3 days bucket 2: 604800 1 week bucket 3: 1209600 2 weeks bucket 4: 2592000 1 month bucket 5: 5270400 2 months bucket 6: 7862400 3 months bucket 7: 10540800 4 months bucket 8: 13132800 5 months bucket 9: 15811200 6 months bucket 10: 23673600 9 months bucket 11: 31536000 1 year bucket 12: 47347200 1.5 years bucket 13: 63158400 2 years bucket 14: 94694400 3 years bucket 15: 0 more than 3 years pool: ddft 73e0001b.747d11cb.a0ea.08:00:09:25:75:d8 all: 0 1 0 0 0 0 0 0 92321 0 0 0 0 0 0 0 0 0 all: 0 -2 0 0 0 96198 0 0 0 27647 0 0 0 0 0 0 0 0 view: 59f62178.580511d2.af73.00:01:80:9a:19:fe machine2 C:\views\app2.1_win.vws view: 0 -2 0 0 0 96198 0 0 0 27647 0 0 0 0 0 0 0 0 view: 8054b303.63ba11d2.bcef.00:01:80:90:ae:6d machine8 D:\users\mary\vws\mary_test.vws view: 0 -2 0 0 0 96198 0 0 0 27647 0 0 0 0 0 0 0 0 view: e7ca6e7a.990811d2.a1dc.00:01:80:85:f3:f5 machine4 C:\views\jeff\jeff_build.vws view: 0 -2 0 0 0 96198 0 0 0 0 0 0 0 0 0 0 0 0 view: ac6db1f1.bd4811d2.b314.00:01:80:a2:f2:c3 machine7 D:\users\sue\views\app_axp.vws view: 0 1 0 0 0 0 0 0 92321 0 0 0 0 0 0 0 0 0

Rational ClearCase Commands Reference