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, $region) = @_;
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>
144 $region ||= $Clearcase::CC->region;
151 $class->updateVobInfo;
167 =for html <blockquote>
175 =for html </blockquote>
179 =for html <blockquote>
187 =for html </blockquote>
201 Returns the VOB global path
205 =for html <blockquote>
213 =for html </blockquote>
217 =for html <blockquote>
225 =for html </blockquote>
229 return $self->{gpath};
239 Returns the VOB server host
243 =for html <blockquote>
251 =for html </blockquote>
255 =for html <blockquote>
259 =item VOB's server host
263 =for html </blockquote>
267 return $self->{shost};
282 Returns the type of VOB access
286 =for html <blockquote>
294 =for html </blockquote>
298 =for html <blockquote>
304 Returns either public for public VOBs or private for private VOBs
308 =for html </blockquote>
312 return $self->{access};
322 Returns the mount options
326 =for html <blockquote>
334 =for html </blockquote>
338 =for html <blockquote>
342 =item VOB's mount options
346 =for html </blockquote>
350 return $self->{mopts};
360 Returns the region for this VOB tag
364 =for html <blockquote>
372 =for html </blockquote>
376 =for html <blockquote>
384 =for html </blockquote>
388 return $self->{region};
398 Returns that active status (whether or not the vob is currently mounted) of the
403 =for html <blockquote>
411 =for html </blockquote>
415 =for html <blockquote>
419 =item Returns YES for an active VOB or NO for an inactive one
423 =for html </blockquote>
427 return $self->{active};
437 Returns the VOB replica_uuid
441 =for html <blockquote>
449 =for html </blockquote>
453 =for html <blockquote>
457 =item VOB replica_uuid
461 =for html </blockquote>
465 return $self->{replica_uuid};
479 =for html <blockquote>
487 =for html </blockquote>
491 =for html <blockquote>
499 =for html </blockquote>
503 return $self->{host};
513 Returns the VOB access path
517 =for html <blockquote>
525 =for html </blockquote>
529 =for html <blockquote>
533 =item VOB access path
535 This is the path relative to the VOB's host
539 =for html </blockquote>
543 return $self->{access_path};
553 Returns the VOB family UUID
557 =for html <blockquote>
565 =for html </blockquote>
569 =for html <blockquote>
573 =item VOB family UUID
577 =for html </blockquote>
581 return $self->{family_uuid};
584 sub vob_registry_attributes() {
589 =head2 vob_registry_attributes
591 Returns the VOB Registry Attributes
595 =for html <blockquote>
603 =for html </blockquote>
607 =for html <blockquote>
611 =item VOB Registry Attributes
615 =for html </blockquote>
619 return $self->{vob_registry_attributes};
620 } # vob_registry_attributes
625 my ($status, @output) = $Clearcase::CC->execute ("space -vob $self->{tag}");
627 # Initialize fields in case of command failure
629 $self->{admsize} = 0;
632 $self->{srcsize} = 0;
636 if (/(\d*\.\d).*VOB database(.*)/) {
637 $self->{dbsize} = $1;
638 } elsif (/(\d*\.\d).*administration data(.*)/) {
639 $self->{admsize} = $1;
640 } elsif (/(\d*\.\d).*cleartext pool(.*)/) {
641 $self->{ctsize} = $1;
642 } elsif (/(\d*\.\d).*derived object pool(.*)/) {
643 $self->{dosize} = $1;
644 } elsif (/(\d*\.\d).*source pool(.*)/) {
645 $self->{srcsize} = $1;
646 } elsif (/(\d*\.\d).*Subtotal(.*)/) {
654 sub expand_description() {
657 my ($status, @output) = $Clearcase::CC->execute("describe -long vob:$self->{tag}");
659 for (my $i = 0; $i < @output; $i++) {
660 if ($output[$i] =~ /created (\S+) by (.+) \((\S+)\)/) {
661 $self->{created} = $1;
662 $self->{ownername} = $2;
664 } elsif ($output[$i] =~ /^\s+\"(.+)\"/) {
665 $self->{comment} = $1;
666 } elsif ($output[$i] =~ /master replica: (.+)/) {
667 $self->{masterReplica} = $1;
668 } elsif ($output[$i] =~ /replica name: (.+)/) {
669 $self->{replicaName} = $1;
670 } elsif ($output[$i] =~ /VOB family featch level: (\d+)/) {
671 $self->{featureLevel} = $1;
672 } elsif ($output[$i] =~ /database schema version: (\d+)/) {
673 $self->{schemaVersion} = $1;
674 } elsif ($output[$i] =~ /modification by remote privileged user: (.+)/) {
675 $self->{remotePrivilege} = $1;
676 } elsif ($output[$i] =~ /atomic checkin: (.+)/) {
677 $self->{atomicCheckin} = $1;
678 } elsif ($output[$i] =~ /VOB ownership:/) {
679 while ($output[$i] !~ /Additional groups:/) {
682 if ($output[$i++] =~ /owner (.+)/) {
686 if ($output[$i++] =~ /group (.+)/) {
693 while ($output[$i] !~ /ACLs enabled/) {
694 if ($output[$i++] =~ /group (.+)/) {
699 $self->{groups} = \@groups;
701 if ($output[$i++] =~ /ACLs enabled: (.+)/) {
702 $self->{aclsEnabled} = $1;
707 while ($i < @output and $output[$i] !~ /Hyperlinks:/) {
708 if ($output[$i] !~ /Attributes:/) {
709 my ($key, $value) = split / = /, $output[$i];
711 # Trim leading spaces
712 $key =~ s/^\s*(\S+)/$1/;
714 # Remove unnecessary '"'s
715 $value =~ s/\"(.*)\"/$1/;
717 $attributes{$key} = $value;
723 $self->{attributes} = \%attributes;
729 while ($i < @output and $output[$i]) {
730 my ($key, $value) = split " -> ", $output[$i++];
732 # Trim leading spaces
733 $key =~ s/^\s*(\S+)/$1/;
735 $hyperlinks{$key} = $value;
738 $self->{hyperlinks} = \%hyperlinks;
745 sub masterReplica() {
751 Returns the VOB master replica
755 =for html <blockquote>
763 =for html </blockquote>
767 =for html <blockquote>
771 =item VOB master replica
775 =for html </blockquote>
781 $self->expand_description unless $self->{masterReplica};
783 return $self->{masterReplica}
792 Returns the date the VOB was created
796 =for html <blockquote>
804 =for html </blockquote>
808 =for html <blockquote>
812 =item Date the VOB was created
816 =for html </blockquote>
822 $self->expand_description unless $self->{created};
824 return $self->{created}
833 Returns the VOB ownername
837 =for html <blockquote>
845 =for html </blockquote>
849 =for html <blockquote>
857 =for html </blockquote>
863 $self->expand_description unless $self->{ownername};
865 return $self->{ownername}
874 Returns the VOB owner
878 =for html <blockquote>
886 =for html </blockquote>
890 =for html <blockquote>
894 =item VOB master replica
898 =for html </blockquote>
904 $self->expand_description unless $self->{owner};
906 return $self->{owner}
915 Returns the VOB comment
919 =for html <blockquote>
927 =for html </blockquote>
931 =for html <blockquote>
939 =for html </blockquote>
945 $self->expand_description unless $self->{comment};
947 return $self->{comment}
956 Returns the VOB replicaName
960 =for html <blockquote>
968 =for html </blockquote>
972 =for html <blockquote>
976 =item VOB replica name
980 =for html </blockquote>
986 $self->expand_description unless $self->{replicaName};
988 return $self->{replicaName}
997 Returns the VOB featureLevel
1001 =for html <blockquote>
1009 =for html </blockquote>
1013 =for html <blockquote>
1017 =item VOB feature level
1021 =for html </blockquote>
1027 $self->expand_description unless $self->{featureLevel};
1029 return $self->{featureLevel}
1032 sub schemaVersion() {
1036 =head2 schemaVersion
1038 Returns the VOB schemaVersion
1042 =for html <blockquote>
1050 =for html </blockquote>
1054 =for html <blockquote>
1058 =item VOB schema version
1062 =for html </blockquote>
1068 $self->expand_description unless $self->{schemaVersion};
1070 return $self->{schemaVersion}
1073 sub remotePrivilege() {
1077 =head2 remotePrivilege
1079 Returns the VOB remotePrivilege
1083 =for html <blockquote>
1091 =for html </blockquote>
1095 =for html <blockquote>
1099 =item Remote Privilege capability
1103 =for html </blockquote>
1109 $self->expand_description unless $self->{remotePrivilege};
1111 return $self->{remotePrivilege}
1114 sub atomicCheckin() {
1118 =head2 atomicCheckin
1120 Returns the VOB atomicCheckin
1124 =for html <blockquote>
1132 =for html </blockquote>
1136 =for html <blockquote>
1140 =item Whether atomic check in enabled
1144 =for html </blockquote>
1150 $self->expand_description unless $self->{atomicCheckin};
1152 return $self->{atomicCheckin}
1161 Returns the VOB group
1165 =for html <blockquote>
1173 =for html </blockquote>
1177 =for html <blockquote>
1185 =for html </blockquote>
1191 $self->expand_description unless $self->{group};
1193 return $self->{group}
1202 Returns the VOB groups
1206 =for html <blockquote>
1214 =for html </blockquote>
1218 =for html <blockquote>
1226 =for html </blockquote>
1232 $self->expand_description unless $self->{groups};
1234 return @{$self->{groups}}
1243 Returns the VOB aclsEnabled
1247 =for html <blockquote>
1255 =for html </blockquote>
1259 =for html <blockquote>
1263 =item VOB aclsEnabled
1267 =for html </blockquote>
1273 $self->expand_description unless $self->{aclsEnabled};
1275 return $self->{aclsEnabled}
1284 Returns the VOB attributes
1288 =for html <blockquote>
1296 =for html </blockquote>
1300 =for html <blockquote>
1304 =item VOB attributes
1308 =for html </blockquote>
1314 $self->expand_description unless $self->{attributes};
1316 return %{$self->{attributes}};
1325 Returns the VOB hyperlinks
1329 =for html <blockquote>
1337 =for html </blockquote>
1341 =for html <blockquote>
1345 =item VOB hyperlinks
1349 =for html </blockquote>
1355 $self->expand_description unless $self->{hyperlinks};
1357 return %{$self->{hyperlinks}};
1363 # Set values to zero in case we cannot get the right values from countdb
1364 $self->{elements} = 0;
1365 $self->{branches} = 0;
1366 $self->{versions} = 0;
1368 # Countdb needs to be done in the vob's db directory
1372 chdir "$self->{gpath}/db";
1374 my $cmd = "$Clearcase::COUNTDB vob_db 2>&1";
1375 my @output = `$cmd`;
1386 if (/^ELEMENT\s*:\s*(\d*)/) {
1387 $self->{elements} = $1;
1388 } elsif (/^BRANCH\s*:\s*(\d*)/) {
1389 $self->{branches} = $1;
1390 } elsif (/^VERSION\s*:\s*(\d*)/) {
1391 $self->{versions} = $1;
1407 Returns the number of elements in the VOB (obtained via countdb)
1411 =for html <blockquote>
1419 =for html </blockquote>
1423 =for html <blockquote>
1427 =item number of elements
1431 =for html </blockquote>
1435 $self->countdb if !$self->{elements};
1437 return $self->{elements};
1447 Returns the number of branch types in the vob
1451 =for html <blockquote>
1459 =for html </blockquote>
1463 =for html <blockquote>
1467 =item number of branch types
1471 =for html </blockquote>
1475 $self->countdb if !$self->{branches};
1477 return $self->{branches};
1487 Returns the number of element versions in the VOB
1491 =for html <blockquote>
1499 =for html </blockquote>
1503 =for html <blockquote>
1507 =item number of element versions
1511 =for html </blockquote>
1515 $self->countdb if !$self->{versions};
1517 return $self->{versions};
1527 Returns the size of the VOB's database
1531 =for html <blockquote>
1539 =for html </blockquote>
1543 =for html <blockquote>
1551 =for html </blockquote>
1555 $self->expand_space if !$self->{dbsize};
1557 return $self->{dbsize};
1567 Returns the size of administrative data in the VOB
1571 =for html <blockquote>
1579 =for html </blockquote>
1583 =for html <blockquote>
1587 =item adminstrative size
1591 =for html </blockquote>
1595 $self->expand_space if !$self->{admsize};
1597 return $self->{admsize};
1607 Returns the size of the cleartext pool
1611 =for html <blockquote>
1619 =for html </blockquote>
1623 =for html <blockquote>
1627 =item cleartext pool size
1631 =for html </blockquote>
1635 $self->expand_space if !$self->{ctsize};
1637 return $self->{ctsize};
1647 Returns the size of the derived object pool
1651 =for html <blockquote>
1659 =for html </blockquote>
1663 =for html <blockquote>
1667 =item derived object pool size
1671 =for html </blockquote>
1675 $self->expand_space if !$self->{dosize};
1677 return $self->{dosize};
1687 Returns the size of the source pool
1691 =for html <blockquote>
1699 =for html </blockquote>
1703 =for html <blockquote>
1707 =item source pool size
1711 =for html </blockquote>
1715 $self->expand_space if !$self->{srcsize};
1717 return $self->{srcsize};
1727 Returns the size of the VOB
1731 =for html <blockquote>
1739 =for html </blockquote>
1743 =for html <blockquote>
1751 =for html </blockquote>
1755 $self->expand_space if !$self->{size};
1757 return $self->{size};
1767 Mount the current VOB
1771 =for html <blockquote>
1779 =for html </blockquote>
1783 =for html <blockquote>
1789 Status of the mount command
1793 An array of lines output from the cleartool mount command
1797 =for html </blockquote>
1801 return 0 if $self->{active} && $self->{active} eq "YES";
1803 my ($status, @output) = $Clearcase::CC->execute("mount $self->{tag}");
1805 return ($status, @output);
1815 Unmounts the current VOB
1819 =for html <blockquote>
1827 =for html </blockquote>
1831 =for html <blockquote>
1837 Status from cleartool
1841 Ouput from cleartool
1845 =for html </blockquote>
1849 my ($status, @output) = $Clearcase::CC->execute("umount $self->{tag}");
1851 return ($status, @output);
1861 Returns true or false if the VOB exists
1865 =for html <blockquote>
1873 =for html </blockquote>
1877 =for html <blockquote>
1885 =for html </blockquote>
1889 my ($status, @output) = $Clearcase::CC->execute("lsvob -region $self->{region} $self->{tag}");
1895 my ($self, $host, $vbs, $comment, %opts) = @_;
1901 Creates a VOB. First instantiate a VOB object with a tag. Then call create. A
1902 small subset of parameters is supported for create.
1906 =for html <blockquote>
1910 =item $host (optional)
1912 Host to create the vob on. Default is the current host.
1914 =item $vbs (optional)
1916 VOB storage area. This is a global pathname to the VOB storage
1917 area. Default will attempt to use -stgloc -auto.
1919 =item $comment (optional)
1921 Comment for this VOB's creation. Default is -nc
1925 =for html </blockquote>
1929 =for html <blockquote>
1935 Status from cleartool
1939 Ouput from cleartool
1943 =for html </blockquote>
1947 return (0, ()) if $self->exists;
1949 $comment = Clearcase::_setComment $comment;
1951 my ($status, @output);
1953 my $additionalOpts = '';
1956 $additionalOpts .= "-$_ ";
1957 $additionalOpts .= "$opts{$_} " if $opts{$_};
1960 if ($host && $vbs) {
1961 $additionalOpts .= '-ucmproject' if $self->{ucmproject};
1963 ($status, @output) = $Clearcase::CC->execute(
1964 "mkvob -tag $self->{tag} $comment $additionalOpts -host $host -hpath $vbs "
1965 . "-gpath $vbs $vbs");
1967 # Note this requires that -stgloc's work and that using -auto is not a
1969 ($status, @output) =
1970 $Clearcase::CC->execute("mkvob -tag $self->{tag} $comment $additionalOpts -stgloc -auto");
1973 $self->updateVobInfo;
1975 return ($status, @output);
1989 =for html <blockquote>
1997 =for html </blockquote>
2001 =for html <blockquote>
2007 Status from cleartool
2011 Ouput from cleartool
2015 =for html </blockquote>
2019 return $Clearcase::CC->execute("rmvob -force $self->{gpath}");
2022 sub updateVobInfo ($$) {
2025 my ($status, @output) = $Clearcase::CC->execute("lsvob -long $self->{tag}");
2027 # Assuming this vob is an empty shell of an object that the user may possibly
2028 # use the create method on, return our blessings...
2029 return if $status != 0;
2032 if (/Global path: (.*)/) {
2033 $self->{gpath} = $1;
2034 } elsif (/Server host: (.*)/) {
2035 $self->{shost} = $1;
2036 } elsif (/Access: (.*)/) {
2037 $self->{access} = $1;
2038 } elsif (/Mount options: (.*)/) {
2039 $self->{mopts} = $1;
2040 } elsif (/Region: (.*)/) {
2041 $self->{region} = $1;
2042 } elsif (/Active: (.*)/) {
2043 $self->{active} = $1;
2044 } elsif (/Vob tag replica uuid: (.*)/) {
2045 $self->{replica_uuid} = $1;
2046 } elsif (/Vob on host: (.*)/) {
2048 } elsif (/Vob server access path: (.*)/) {
2049 $self->{access_path} = $1;
2050 } elsif (/Vob family uuid: (.*)/) {
2051 $self->{family_uuid} = $1;
2052 } elsif (/Vob registry attributes: (.*)/) {
2053 $self->{vob_registry_attributes} = $1;
2066 =head3 ClearSCM Perl Modules
2068 =for html <p><a href="/php/scm_man.php?file=lib/Clearcase.pm">Clearcase</a></p>
2070 =for html <p><a href="/php/scm_man.php?file=lib/OSDep.pm">OSdep</a></p>
2072 =head2 BUGS AND LIMITATIONS
2074 There are no known bugs in this module
2076 Please report problems to Andrew DeFaria <Andrew@ClearSCM.com>.
2078 =head2 LICENSE AND COPYRIGHT
2080 Copyright (c) 2007, ClearSCM, Inc. All rights reserved.