view release on metacpan or  search on metacpan

lib/AFS/Command/VOS.pod  view on Meta::CPAN

		print "IP Address: $address\n";
	    }
	}
    }

If a specific 'host' or 'uuid' is specified, then only one object will
be returned (assuming the specified host or uuid is valid, of course,
otherwise, you get nothing).

B<AFS::Object::FileServer>

This object will have one or more of the following attributes,
depending on the choice of arguments to the method, as well as the
ability of vos to map the IP addresses back into hostnames.

    Attributes			Values
    ----------			------
    hostname			Server's hostname (duh)
    addresses			ARRAY reference of IP addresses
    uuid			Servers's UUID (duh)

The 'uuid' will be present if the 'printuuid' or 'uuid' arguments were
passed to the method call.  The 'addresses' will be present either
'noresolve' was specified, or vos has problems with hostname
resolution.

=back

=head2 listpart

=over

=item Arguments

The vos help string is:

    vos listpart: list partitions
    Usage: vos listpart -server <machine name> [-cell <cell name>] [-noauth]
			[-localauth] [-verbose] [-encrypt]

The corresponding method invocation looks like:

    my $result = $vos->listpart
      (
       # Required arguments
       server			=> $server,
       # Optional arguments
       cell			=> $cell,
       noauth			=> 1,
       localauth		=> 1,
       verbose			=> 1,
       encrypt			=> 1,
      );

=item Return Values

This method returns an AFS::Object::FileServer object, which
contains one or more AFS::Object::Partition objects.  Because
'listpart' returns nothing other than the partition names, the
underlying Partition objects have only one attribute ('partition'), so
the API for access this data is trivial:

    my $result = $vos->listpart
      (
       server			=> 'fs1.ms.com',
      ) || die $vos->errors();

    foreach my $partition ( $result->getPartitionNames() ) {
	print "Server '$server' has partition '$partition'\n";
    }

The FileServer object has no attributes at all, it merely contains the
Partition objects.  Since the Partition objects are indexed by name,
there's no need to extract the partition objects and query their
attributes, since once you have the names, you have all the information
already.

Compare this with 'vos partinfo', which provides a lot more
information.  For pedantic completeness (the author is kinda
anal-retentive in that way), here's the description of the complete
interface.

B<AFS::Object::FileServer>

This object has no attributes, and is merely a container for the
AFS::Object::Partition objects.  It has the following methods
for extracting the objects is contains.

    Methods			Returns
    -------			-------
    getPartitionNames()		list of strings (partition names)
    getPartitions()		list of AFS::Object::Partition objects
    getPartition($partname)	a single AFS::Object::Partition object,
				for the partition named $partname

B<AFS::Object::Partition>

This object has one boring attribute:

    Attributes			Values
    ----------			------
    partition			Fileserver /vice partition name

When used to encapsulate 'vos listpart' output, this object has no
relevant methods.  Note, however, that this version of the API reuses
this object to represent other partition-related data (see 'vos
listvol' method documentation, for example), but they are not relevant
in this usage of the object.  This multiple personality of the objects
may be changed in a future release, so don't get too attached to the
specific class names.

See the AFS::Object documentation for a discussion of the
planned evolution of the API.

=back

=head2 listvldb

=over

=item Arguments

The vos help string is:

    vos listvldb: list volumes in the VLDB
    Usage: vos listvldb [-name <volume name or ID>] [-server <machine name>]
			[-partition <partition name>] [-locked] [-quiet] [-nosort]
			[-cell <cell name>] [-noauth] [-localauth] [-verbose] [-encrypt] 
    Where: -locked     locked volumes only
	   -quiet      generate minimal information
	   -nosort     do not alphabetically sort the volume names

The corresponding method invocation looks like:

    my $result = $vos->listvldb
      (
       # Optional arguments
       name			=> $name,
       server			=> $server,
       partition		=> $partition,
       locked			=> 1,
       quiet			=> 1,
       nosort			=> 1,
       cell                     => $cell,
       noauth                   => 1,
       localauth                => 1,
       verbose                  => 1,
       encrypt                  => 1,
      );

=item Return Values

This method returns an AFS::Object::VLDB object, which has a
few attributes, and contains one or more
AFS::Object::VLDBEntry objects, which in turn contain
AFS::Object::VLDBSite objects, as well as their own
attributes.

NOTE: the VLDBEntry and VLDBSite objects are the same as those used by
the 'examine' method, since that command also queries the VLDB for
part of its return values.  See that discussion above for some
relevant details on the parsing of those objects, which will no be
repeated here.

    my $result = $vos->listvldb
      (
       cell				=> $cell,
      ) || die $vos->errors();

    print("VLDB contains " . $result->total() " volumes, " .
	  $result->locked() . " of which are locked\n");

    foreach my $entry ( $result->getVLDBEntries() ) {
	my $name = $entry->name();
	foreach my $attr ( $entry->listAttributes() ) {
	    print "Volume $name has attribute $attr => " . $entry->$attr() . "\n";
	}
	foreach my $site ( $entry->getVLDBSites() ) {
	    my %attrs = $site->getAttributes();
	    while ( my($attr,$value) = each %attrs ) {
		print "Site has attribute $attr => $value\n";
	    }
	}
    }

Another way to slice and dice this data:

    foreach my $name ( $result->getVolumeNames() ) {
	my $entry = $result->getVLDBEntry( name => $name );
	....
    }

Each of these objects has the following attributes and methods:

B<AFS::Object::VLDB>

This object has two attributes, and several methods:

    Attributes			Values
    ----------			------
    total			Number of VLDBEntries in the results
    locked			Number of locked volumes in the results

    Methods			Returns
    -------			-------
    getVolumeNames()		list of volume names in the results
    getVolumeIds()		list of numeric volume IDs
    getVLDBEntry(name => $name)	the AFS::Object::VLDBEntry for name $name
    getVLDBEntry(id => $id)	the AFS::Object::VLDBEntry for id $id
    getVLDBEntries()		list of AFS::Object::VLDBEntry objects
    getVLDBEntryByName($name)   the AFS::Object::VLDBEntry for $name
    getVLDBEntryById($id)   	the AFS::Object::VLDBEntry for $id

NOTE: name to volume mappings are one to one, but id to volume
mappings are many to one, since a single logical VLDB entry can have
several IDs associated with it (RW, RO, BK, and/or RC).

B<AFS::Object::VLDBEntry>

This object also has a few attributes, and a few methods.  The 'name'
attribute is always present, but the others vary, depending on the
volume (again, see the 'examine' documentation for more verbosity).

    Attributes			Values
    ----------			------
    name			Volume name
    rwrite			Numeric Volume ID for the RW volume
    ronly			Numeric Volume ID for the RO volume
    backup			Numeric Volume ID for the BK volume
    rclone			Numeric Volume ID for the RClone volume, if present
    locked			Boolean, indicating whether or not the VLDB entry is locked

    Methods			Returns
    -------			-------
    getVLDBSites()		list of AFS::Object::VLDBSite objects

B<AFS::Object::VLDBSite>

The following attributes are always available:

    Attributes			Values
    ----------			------
    server			Fileserver hostname
    partition			Fileserver /vice partition name
    type			"RO" | "RW" | "BK"
    status			Site status.

This object has no special methods.

=back

=head2 listvol

=over

=item Arguments

The vos help string is:

    vos listvol: list volumes on server (bypass VLDB)
    Usage: vos listvol -server <machine name> [-partition <partition name>]
		       [-fast] [-long] [-quiet] [-extended] [-cell <cell name>]
		       [-noauth] [-localauth] [-verbose] [-encrypt] 
    Where: -fast       minimal listing
	   -long       list all normal volume fields
	   -quiet      generate minimal information
	   -extended   list extended volume fields

The corresponding method invocation looks like:

    my $result = $vos->listvol
      (
       # Required arguments
       server			=> $server,
       # Optional arguments
       partition		=> $partition,
       fast			=> 1,
       long			=> 1,
       quiet			=> 1,
       extended			=> 1, # Not really... see below
       cell                     => $cell,
       noauth                   => 1,
       localauth                => 1,
       verbose                  => 1,
       encrypt                  => 1,
      );

NOTE: 'extended' is not supported in this version of the API, and
specifying it will result in a warning, but not an error.  However,
'vos examine' does parse the extended output, so if you really want
that data you can get it on a volume by volume basis.  Adding support
for 'extended' to 'vos listvol' is on the todo list.

=item Return Values

This method returns an AFS::Object::VolServer object, which
merely contains one or more AFS::Object::Partition objects,
which in turn have a few attributes and contain one or more
AFS::Object::VolumeHeader objects.

    my $result = $vos->listvol
      (
       server			=> $server,,
       cell				=> $cell,
      ) || die $vos->errors();
    foreach my $partition ( $result->getPartitions() ) {
	my $partname 		= $partition->partition();
	my $total			= $partition->total();
	my $online			= $partition->online();
	my $offline			= $partition->offline();
	my $busy			= $partition->busy();
	print("Partition $partname has $total total volumes, of which " .
	      "$online are online, $offline are offline, and $busy are busy.\n");
	foreach my $header ( $partition->getVolumeHeaders() ) {
	    # Do something interesting with $header.
	}
    }

There are several other ways to get at the headers, of course.

	foreach my $name ( $partition->getVolumeNames() ) {
	    my $header = $partition->getVolumeHeaderByName($name)
	    # Do something interesting with $header.
	}

	foreach my $id ( $partition->getVolumeIds() ) {
	    my $header = $partition->getVolumeHeaderById($id);
	    # Do something interesting with $header.
	}

And there is yet one more method to extract the headers (don't say the
author doesn't pander to lots of different programming styles,
provided of course they are one of his own).


	foreach my $name ( $partition->getVolumeNames() ) {
	    my $header = $partition->getVolumeHeader( name => $name );
	    # Do something interesting with $header.
	}

	foreach my $id ( $partition->getVolumeIds() ) {
	    my $header = $partition->getVolumeHeader( id => $id );
	    # Do something interesting with $header.
	}

Each of these objects has the following attributes and methods:

B<AFS::Object::VolServer>

This object has no attributes, and has several methods for extracting
the partition objects.