3 =head1 NAME $RCSfile: Vob.pm,v $
5 Object oriented interface to a Clearcase VOB
13 Andrew DeFaria <Andrew@ClearSCM.com>
21 Thu Dec 29 12:07:59 PST 2005
25 $Date: 2011/11/16 19:46:13 $
31 Provides access to information about a Clearcase VOB. Note that information
32 about the number of elements, branches, etc. that is provided by countdb are not
33 initially instantiated with the VOB object, rather those member variables are
34 expanded if and when accessed. This helps the VOB object to be more efficient.
37 my $vob = new Clearcase::Vob (tag => "/vobs/test");
39 # Access member variables...
40 display "Tag:\t\t" . $vob->tag;
41 display "Global path:\t" . $vob->gpath;
42 display "Sever host:\t" . $vob->shost;
43 display "Access:\t\t" . $vob->access;
44 display "Mount options:\t" . $vob->mopts;
45 display "Region:\t\t" . $vob->region;
46 display "Active:\t\t" . $vob->active;
47 display "Replica UUID:\t" . $vob->replica_uuid;
48 display "Host:\t\t" . $vob->host;
49 display "Access path:\t" . $vob->access_path;
50 display "Family UUID:\t" . $vob->family_uuid;
52 # This members are not initially expanded until accessed
53 display "Elements:\t" . $vob->elements;
54 display "Branches:\t" . $vob->branches;
55 display "Versions:\t" . $vob->versions;
56 display "DB Size:\t" . $vob->dbsize;
57 display "Adm Size:\t" . $vob->admsize;
58 display "CT Size:\t" . $vob->ctsize;
59 display "DO Size:\t" . $vob->dosize;
60 display "Src Size:\t" . $vob->srcsize;
61 display "Size:\t\t" . $vob->size;
64 display "Umounting " . $vob->tag . "...";
68 display "Mounting " . $vob->tag . "...";
74 This module, and others below the Clearcase directory, implement an object
75 oriented approach to Clearcase. In general Clearcase entities are made into
76 objects that can be manipulated easily in Perl. This module is the main or
77 global module. Contained herein are members and methods of a general or global
78 nature. Also contained here is an IPC interface to cleartool such that cleartool
79 runs in the background andcommands are fed to it via the exec method. When
80 making repeated calls to cleartool this can result in a substantial savings of
81 time as most operating systems' fork/exec sequence is time consuming. Factors of
82 8 fold improvement have been measured.
84 Additionally a global variable, $cc, is implemented from this module such that
85 you should not need to instantiate another one, though you could.
89 The following routines are exported:
93 package Clearcase::Vob;
102 my ($class, $tag) = @_;
108 Construct a new Clearcase VOB object. Note that not all members are
109 initially populated because doing so would be time consuming. Such
110 member variables will be expanded when accessed.
114 =for html <blockquote>
120 VOB tag to be instantiated. You can use either an object oriented call
121 (i.e. my $vob = new Clearcase::Vob (tag => "/vobs/test")) or the
122 normal call (i.e. my $vob = new Clearcase::Vob ("/vobs/test")). You
123 can also instantiate a new vob by supplying a tag and then later
124 calling the create method.
128 =for html </blockquote>
132 =for html <blockquote>
136 =item Clearcase VOB object
140 =for html </blockquote>
148 $class->updateVobInfo;
164 =for html <blockquote>
172 =for html </blockquote>
176 =for html <blockquote>
184 =for html </blockquote>
198 Returns the VOB global path
202 =for html <blockquote>
210 =for html </blockquote>
214 =for html <blockquote>
222 =for html </blockquote>
226 return $self->{gpath};
236 Returns the VOB server host
240 =for html <blockquote>
248 =for html </blockquote>
252 =for html <blockquote>
256 =item VOB's server host
260 =for html </blockquote>
264 return $self->{shost};
278 Returns the type of VOB access
282 =for html <blockquote>
290 =for html </blockquote>
294 =for html <blockquote>
300 Returns either public for public VOBs or private for private VOBs
304 =for html </blockquote>
308 return $self->{access};
318 Returns the mount options
322 =for html <blockquote>
330 =for html </blockquote>
334 =for html <blockquote>
338 =item VOB's mount options
342 =for html </blockquote>
346 return $self->{mopts};
356 Returns the region for this VOB tag
360 =for html <blockquote>
368 =for html </blockquote>
372 =for html <blockquote>
380 =for html </blockquote>
384 return $self->{region};
394 Returns that active status (whether or not the vob is currently mounted) of the
399 =for html <blockquote>
407 =for html </blockquote>
411 =for html <blockquote>
415 =item Returns YES for an active VOB or NO for an inactive one
419 =for html </blockquote>
423 return $self->{active};
426 sub replica_uuid () {
433 Returns the VOB replica_uuid
437 =for html <blockquote>
445 =for html </blockquote>
449 =for html <blockquote>
453 =item VOB replica_uuid
457 =for html </blockquote>
461 return $self->{replica_uuid};
475 =for html <blockquote>
483 =for html </blockquote>
487 =for html <blockquote>
495 =for html </blockquote>
499 return $self->{host};
509 Returns the VOB access path
513 =for html <blockquote>
521 =for html </blockquote>
525 =for html <blockquote>
529 =item VOB access path
531 This is the path relative to the VOB's host
535 =for html </blockquote>
539 return $self->{access_path};
549 Returns the VOB family UUID
553 =for html <blockquote>
561 =for html </blockquote>
565 =for html <blockquote>
569 =item VOB family UUID
573 =for html </blockquote>
577 return $self->{family_uuid};
580 sub vob_registry_attributes () {
585 =head2 vob_registry_attributes
587 Returns the VOB Registry Attributes
591 =for html <blockquote>
599 =for html </blockquote>
603 =for html <blockquote>
607 =item VOB Registry Attributes
611 =for html </blockquote>
615 return $self->{vob_registry_attributes};
616 } # vob_registry_attributes
618 sub expand_space () {
621 my ($status, @output) = $Clearcase::CC->execute ("space -vob $self->{tag}");
623 # Initialize fields in case of command failure
625 $self->{admsize} = 0;
628 $self->{srcsize} = 0;
632 if (/(\d*\.\d).*VOB database(.*)/) {
633 $self->{dbsize} = $1;
634 } elsif (/(\d*\.\d).*administration data(.*)/) {
635 $self->{admsize} = $1;
636 } elsif (/(\d*\.\d).*cleartext pool(.*)/) {
637 $self->{ctsize} = $1;
638 } elsif (/(\d*\.\d).*derived object pool(.*)/) {
639 $self->{dosize} = $1;
640 } elsif (/(\d*\.\d).*source pool(.*)/) {
641 $self->{srcsize} = $1;
642 } elsif (/(\d*\.\d).*Subtotal(.*)/) {
650 sub expand_description () {
653 my ($status, @output) = $Clearcase::CC->execute ("describe -long vob:$self->{tag}");
655 for (my $i = 0; $i < @output; $i++) {
656 if ($output[$i] =~ /created (\S+) by (.+) \((\S+)\)/) {
657 $self->{created} = $1;
658 $self->{ownername} = $2;
660 } elsif ($output[$i] =~ /^\s+\"(.+)\"/) {
661 $self->{comment} = $1;
662 } elsif ($output[$i] =~ /master replica: (.+)/) {
663 $self->{masterReplica} = $1;
664 } elsif ($output[$i] =~ /replica name: (.+)/) {
665 $self->{replicaName} = $1;
666 } elsif ($output[$i] =~ /VOB family featch level: (\d+)/) {
667 $self->{featureLevel} = $1;
668 } elsif ($output[$i] =~ /database schema version: (\d+)/) {
669 $self->{schemaVersion} = $1;
670 } elsif ($output[$i] =~ /modification by remote privileged user: (.+)/) {
671 $self->{remotePrivilege} = $1;
672 } elsif ($output[$i] =~ /atomic checkin: (.+)/) {
673 $self->{atomicCheckin} = $1;
674 } elsif ($output[$i] =~ /VOB ownership:/) {
675 while ($output[$i] !~ /Additional groups:/) {
678 if ($output[$i++] =~ /owner (.+)/) {
682 if ($output[$i++] =~ /group (.+)/) {
689 while ($output[$i] !~ /ACLs enabled/) {
690 if ($output[$i++] =~ /group (.+)/) {
695 $self->{groups} = \@groups;
697 if ($output[$i++] =~ /ACLs enabled: (.+)/) {
698 $self->{aclsEnabled} = $1;
703 while ($i < @output and $output[$i] !~ /Hyperlinks:/) {
704 if ($output[$i] !~ /Attributes:/) {
705 my ($key, $value) = split / = /, $output[$i];
707 # Trim leading spaces
708 $key =~ s/^\s*(\S+)/$1/;
710 # Remove unnecessary '"'s
711 $value =~ s/\"(.*)\"/$1/;
713 $attributes{$key} = $value;
719 $self->{attributes} = \%attributes;
725 while ($i < @output and $output[$i]) {
726 my ($key, $value) = split " -> ", $output[$i++];
728 # Trim leading spaces
729 $key =~ s/^\s*(\S+)/$1/;
731 $hyperlinks{$key} = $value;
734 $self->{hyperlinks} = \%hyperlinks;
741 sub masterReplica() {
747 Returns the VOB master replica
751 =for html <blockquote>
759 =for html </blockquote>
763 =for html <blockquote>
767 =item VOB master replica
771 =for html </blockquote>
777 $self->expand_description unless $self->{masterReplica};
779 return $self->{masterReplica}
788 Returns the date the VOB was created
792 =for html <blockquote>
800 =for html </blockquote>
804 =for html <blockquote>
808 =item Date the VOB was created
812 =for html </blockquote>
818 $self->expand_description unless $self->{created};
820 return $self->{created}
829 Returns the VOB ownername
833 =for html <blockquote>
841 =for html </blockquote>
845 =for html <blockquote>
853 =for html </blockquote>
859 $self->expand_description unless $self->{ownername};
861 return $self->{ownername}
870 Returns the VOB owner
874 =for html <blockquote>
882 =for html </blockquote>
886 =for html <blockquote>
890 =item VOB master replica
894 =for html </blockquote>
900 $self->expand_description unless $self->{owner};
902 return $self->{owner}
911 Returns the VOB comment
915 =for html <blockquote>
923 =for html </blockquote>
927 =for html <blockquote>
935 =for html </blockquote>
941 $self->expand_description unless $self->{comment};
943 return $self->{comment}
952 Returns the VOB replicaName
956 =for html <blockquote>
964 =for html </blockquote>
968 =for html <blockquote>
972 =item VOB replica name
976 =for html </blockquote>
982 $self->expand_description unless $self->{replicaName};
984 return $self->{replicaName}
993 Returns the VOB featureLevel
997 =for html <blockquote>
1005 =for html </blockquote>
1009 =for html <blockquote>
1013 =item VOB feature level
1017 =for html </blockquote>
1023 $self->expand_description unless $self->{featureLevel};
1025 return $self->{featureLevel}
1028 sub schemaVersion() {
1032 =head2 schemaVersion
1034 Returns the VOB schemaVersion
1038 =for html <blockquote>
1046 =for html </blockquote>
1050 =for html <blockquote>
1054 =item VOB schema version
1058 =for html </blockquote>
1064 $self->expand_description unless $self->{schemaVersion};
1066 return $self->{schemaVersion}
1069 sub remotePrivilege() {
1073 =head2 remotePrivilege
1075 Returns the VOB remotePrivilege
1079 =for html <blockquote>
1087 =for html </blockquote>
1091 =for html <blockquote>
1095 =item Remote Privilege capability
1099 =for html </blockquote>
1105 $self->expand_description unless $self->{remotePrivilege};
1107 return $self->{remotePrivilege}
1110 sub atomicCheckin() {
1114 =head2 atomicCheckin
1116 Returns the VOB atomicCheckin
1120 =for html <blockquote>
1128 =for html </blockquote>
1132 =for html <blockquote>
1136 =item Whether atomic check in enabled
1140 =for html </blockquote>
1146 $self->expand_description unless $self->{atomicCheckin};
1148 return $self->{atomicCheckin}
1157 Returns the VOB group
1161 =for html <blockquote>
1169 =for html </blockquote>
1173 =for html <blockquote>
1181 =for html </blockquote>
1187 $self->expand_description unless $self->{group};
1189 return $self->{group}
1198 Returns the VOB groups
1202 =for html <blockquote>
1210 =for html </blockquote>
1214 =for html <blockquote>
1222 =for html </blockquote>
1228 $self->expand_description unless $self->{groups};
1230 return @{$self->{groups}}
1239 Returns the VOB aclsEnabled
1243 =for html <blockquote>
1251 =for html </blockquote>
1255 =for html <blockquote>
1259 =item VOB aclsEnabled
1263 =for html </blockquote>
1269 $self->expand_description unless $self->{aclsEnabled};
1271 return $self->{aclsEnabled}
1280 Returns the VOB attributes
1284 =for html <blockquote>
1292 =for html </blockquote>
1296 =for html <blockquote>
1300 =item VOB attributes
1304 =for html </blockquote>
1310 $self->expand_description unless $self->{attributes};
1312 return %{$self->{attributes}};
1321 Returns the VOB hyperlinks
1325 =for html <blockquote>
1333 =for html </blockquote>
1337 =for html <blockquote>
1341 =item VOB hyperlinks
1345 =for html </blockquote>
1351 $self->expand_description unless $self->{hyperlinks};
1353 return %{$self->{hyperlinks}};
1359 # Set values to zero in case we cannot get the right values from countdb
1360 $self->{elements} = 0;
1361 $self->{branches} = 0;
1362 $self->{versions} = 0;
1364 # Countdb needs to be done in the vob's db directory
1368 chdir "$self->{gpath}/db";
1370 my $cmd = "$Clearcase::COUNTDB vob_db 2>&1";
1371 my @output = `$cmd`;
1382 if (/^ELEMENT\s*:\s*(\d*)/) {
1383 $self->{elements} = $1;
1384 } elsif (/^BRANCH\s*:\s*(\d*)/) {
1385 $self->{branches} = $1;
1386 } elsif (/^VERSION\s*:\s*(\d*)/) {
1387 $self->{versions} = $1;
1403 Returns the number of elements in the VOB (obtained via countdb)
1407 =for html <blockquote>
1415 =for html </blockquote>
1419 =for html <blockquote>
1423 =item number of elements
1427 =for html </blockquote>
1431 $self->countdb if !$self->{elements};
1433 return $self->{elements};
1443 Returns the number of branch types in the vob
1447 =for html <blockquote>
1455 =for html </blockquote>
1459 =for html <blockquote>
1463 =item number of branch types
1467 =for html </blockquote>
1471 $self->countdb if !$self->{branches};
1473 return $self->{branches};
1483 Returns the number of element versions in the VOB
1487 =for html <blockquote>
1495 =for html </blockquote>
1499 =for html <blockquote>
1503 =item number of element versions
1507 =for html </blockquote>
1511 $self->countdb if !$self->{versions};
1513 return $self->{versions};
1523 Returns the size of the VOB's database
1527 =for html <blockquote>
1535 =for html </blockquote>
1539 =for html <blockquote>
1547 =for html </blockquote>
1551 $self->expand_space if !$self->{dbsize};
1553 return $self->{dbsize};
1563 Returns the size of administrative data in the VOB
1567 =for html <blockquote>
1575 =for html </blockquote>
1579 =for html <blockquote>
1583 =item adminstrative size
1587 =for html </blockquote>
1591 $self->expand_space if !$self->{admsize};
1593 return $self->{admsize};
1603 Returns the size of the cleartext pool
1607 =for html <blockquote>
1615 =for html </blockquote>
1619 =for html <blockquote>
1623 =item cleartext pool size
1627 =for html </blockquote>
1631 $self->expand_space if !$self->{ctsize};
1633 return $self->{ctsize};
1643 Returns the size of the derived object pool
1647 =for html <blockquote>
1655 =for html </blockquote>
1659 =for html <blockquote>
1663 =item derived object pool size
1667 =for html </blockquote>
1671 $self->expand_space if !$self->{dosize};
1673 return $self->{dosize};
1683 Returns the size of the source pool
1687 =for html <blockquote>
1695 =for html </blockquote>
1699 =for html <blockquote>
1703 =item source pool size
1707 =for html </blockquote>
1711 $self->expand_space if !$self->{srcsize};
1713 return $self->{srcsize};
1723 Returns the size of the VOB
1727 =for html <blockquote>
1735 =for html </blockquote>
1739 =for html <blockquote>
1747 =for html </blockquote>
1751 $self->expand_space if !$self->{size};
1753 return $self->{size};
1763 Mount the current VOB
1767 =for html <blockquote>
1775 =for html </blockquote>
1779 =for html <blockquote>
1785 Status of the mount command
1789 An array of lines output from the cleartool mount command
1793 =for html </blockquote>
1797 return 0 if $self->{active} && $self->{active} eq "YES";
1799 my ($status, @output) = $Clearcase::CC->execute ("mount $self->{tag}");
1801 return ($status, @output);
1811 Unmounts the current VOB
1815 =for html <blockquote>
1823 =for html </blockquote>
1827 =for html <blockquote>
1833 Status from cleartool
1837 Ouput from cleartool
1841 =for html </blockquote>
1845 my ($status, @output) = $Clearcase::CC->execute ("umount $self->{tag}");
1847 return ($status, @output);
1857 Returns true or false if the VOB exists
1861 =for html <blockquote>
1869 =for html </blockquote>
1873 =for html <blockquote>
1881 =for html </blockquote>
1885 my ($status, @output) = $Clearcase::CC->execute ("lsvob $self->{tag}");
1890 sub create (;$$$%) {
1891 my ($self, $host, $vbs, $comment, %opts) = @_;
1897 Creates a VOB. First instantiate a VOB object with a tag. Then call create. A
1898 small subset of parameters is supported for create.
1902 =for html <blockquote>
1906 =item $host (optional)
1908 Host to create the vob on. Default is the current host.
1910 =item $vbs (optional)
1912 VOB storage area. This is a global pathname to the VOB storage
1913 area. Default will attempt to use -stgloc -auto.
1915 =item $comment (optional)
1917 Comment for this VOB's creation. Default is -nc
1921 =for html </blockquote>
1925 =for html <blockquote>
1931 Status from cleartool
1935 Ouput from cleartool
1939 =for html </blockquote>
1943 return (0, ()) if $self->exists;
1945 $comment = Clearcase::_setComment $comment;
1947 my ($status, @output);
1949 my $additionalOpts = '';
1952 $additionalOpts .= "-$_ ";
1953 $additionalOpts .= "$opts{$_} " if $opts{$_};
1956 if ($host && $vbs) {
1957 $additionalOpts .= '-ucmproject' if $self->{ucmproject};
1959 ($status, @output) = $Clearcase::CC->execute (
1960 "mkvob -tag $self->{tag} $comment $additionalOpts -host $host -hpath $vbs "
1961 . "-gpath $vbs $vbs");
1963 # Note this requires that -stgloc's work and that using -auto is not a
1965 ($status, @output) =
1966 $Clearcase::CC->execute ("mkvob -tag $self->{tag} $comment $additionalOpts -stgloc -auto");
1969 $self->updateVobInfo;
1971 return ($status, @output);
1985 =for html <blockquote>
1993 =for html </blockquote>
1997 =for html <blockquote>
2003 Status from cleartool
2007 Ouput from cleartool
2011 =for html </blockquote>
2015 return $Clearcase::CC->execute ("rmvob -force $self->{gpath}");
2018 sub updateVobInfo ($$) {
2021 my ($status, @output) = $Clearcase::CC->execute ("lsvob -long $self->{tag}");
2023 # Assuming this vob is an empty shell of an object that the user may possibly
2024 # use the create method on, return our blessings...
2025 return if $status != 0;
2028 if (/Global path: (.*)/) {
2029 $self->{gpath} = $1;
2030 } elsif (/Server host: (.*)/) {
2031 $self->{shost} = $1;
2032 } elsif (/Access: (.*)/) {
2033 $self->{access} = $1;
2034 } elsif (/Mount options: (.*)/) {
2035 $self->{mopts} = $1;
2036 } elsif (/Region: (.*)/) {
2037 $self->{region} = $1;
2038 } elsif (/Active: (.*)/) {
2039 $self->{active} = $1;
2040 } elsif (/Vob tag replica uuid: (.*)/) {
2041 $self->{replica_uuid} = $1;
2042 } elsif (/Vob on host: (.*)/) {
2044 } elsif (/Vob server access path: (.*)/) {
2045 $self->{access_path} = $1;
2046 } elsif (/Vob family uuid: (.*)/) {
2047 $self->{family_uuid} = $1;
2048 } elsif (/Vob registry attributes: (.*)/) {
2049 $self->{vob_registry_attributes} = $1;
2062 =head3 ClearSCM Perl Modules
2064 =for html <p><a href="/php/scm_man.php?file=lib/Clearcase.pm">Clearcase</a></p>
2066 =for html <p><a href="/php/scm_man.php?file=lib/OSDep.pm">OSdep</a></p>
2068 =head2 BUGS AND LIMITATIONS
2070 There are no known bugs in this module
2072 Please report problems to Andrew DeFaria <Andrew@ClearSCM.com>.
2074 =head2 LICENSE AND COPYRIGHT
2076 Copyright (c) 2007, ClearSCM, Inc. All rights reserved.