Derived object reference counts

A reference count of a DO is the number of times the derived object appears in HCL VersionVault dynamic views throughout the network.

VersionVault also tracks the identifiers for the views that reference the DO. When a new derived object is created, clearmake sets its reference count to 1, indicating that it is visible in one view. Thereafter, each winkin of the DO to an additional view increments the reference count.

The lsdo -long command lists the reference count and referencing views for a DO. For example:

cleartool lsdo -long 
01-Sep-06.18:56:45     Suzanne Lee (sgl.user@neon)
  create derived object "file.txt@@01-Sep.18:56.2147483683"
  size of derived object is: 10
  last access: 01-Sep-06.18:56:46
  references: 1  => neon:/home/sgl/views/sgl_test.vws
01-Sep-06.19:03:19     Suzanne Lee (sgl.user@neon)
  create derived object "util@@01-Sep.19:03.81"
  size of derived object is: 10
  last access: 01-Sep-06.19:03:33
  references: 2 (shared)
  => neon:/home/sgl/views/sgl_test.vws
  => neon:/home/sgl/views/point_of.vws

For a nonshareable DO, the reference count is always 1.

You can also create OS-level hard links to an existing shareable DO, each of which increments the reference count. Such additional hard links are sometimes subject to winkin:

• If the additional hard link was created in the same build script as the original DO, a winkin of the DO during a subsequent clearmake build causes a winkin of the additional hard link.
• Additional hard links that you create manually are not winked in during subsequent builds.

A reference count can also decrease. When a program running in any of the views that reference a shared derived object overwrites or deletes that object, the link is broken and the reference count is decremented. That is, the program deletes the reference of the view to the DO, but the DO itself remains in VOB storage. This occurs most often when a compiler overwrites an old build target. You can also remove the derived object with a standard rm command, or if the makefile has a clean rule, by running clearmake clean.

The reference count of a derived object can become zero. For example, suppose you build a program hello and rebuild it a few minutes later. The second hello overwrites the first hello, decrementing its reference count. Because the reference count probably was 1 (no other view has winked it in), it now becomes 0. Similarly, the reference counts of old DOs, even of DOs that are widely shared, eventually decrease to zero as development proceeds and new DOs replace the old ones.

The lsdo command ignores such DOs by default, but you can use the -zero option to list them:

cleartool lsdo -zero -long hello.o
  .
  .
08-Mar-06.12:47:54     Allison K. Pak (akp.user@cobalt)
  create derived object "hello.o@@08-Mar.12:47.259"
  references: 0
  ...

A derived object that is listed with references: 0 annotation does not currently appear in any view. However, some or all of its information might still be available:

• If the DO was ever promoted to VOB storage, its data container is still in the VOB storage pool (unless it has been scrubbed), and its CR is still in the VOB database. You can use catcr and diffcr to work with the CR. You can get to its file system data by performing a clearmake build in an appropriately configured view or by using the winkin command.
• If the DO was never promoted, its CR might be gone forever. Until the scrubber runs and deletes the data container, the catcr command prints the message Config record data no longer available for DO-pname.