Unadvertized VI Perl Toolkit helper functions and options

As I’ve been getting more and more familiar with the VI Perl Toolkit over the last couple of weeks I’ve discovered that the perl modules created and provided by VMware have some options and routines that are not discussed in the programming guide. This is my attempt to document the ones that I have found useful and you may be interested in.

There are some additional helper routines that can be found in the perl modules (the files that end in .pm) provided by the Toolkit, and the VMware employee(s) who have written them have done a pretty good job of documenting them in the code. Of special note (I may add them to this post at a later date) are the HostUtil and VMUtil modules, which have routines that streamline some of the more common operations (getting host and VM views, migrating VMs, etc).

Without futher ado…

Prerequesites

If you’re a perl programmer, this isn’t for you. If you aren’t, then…

To use these functions/subroutines you must include the module(s). For the Opts module, it is included when you use VIRuntime (or VIM25Runtime). For VIExt, you must include it expressly.

use VMware::VIRuntime; # includes VICommon and VILib
use VMware::VIExt;

1 2	use VMware::VIRuntime; # includes VICommon and VILib use VMware::VIExt;

Assertions

The provided assertion is checked, and if it fails the usage message is printed.

Opts::assert_usage( assert_condition, fail_message );

Opts::assert_usage(defined(Opts::get_option('required_1')), "required_1is required");

1	Opts::assert_usage(defined(Opts::get_option('required_1')), "required_1is required");

Option Alias (aliai?)

When adding user specified options to a VI Perl script (using Opts::add_options), they are generally passed in the following manner:

my %opts = (
	'option_name' =&gt; {
		alias =&gt; "O",
		type =&gt; "=s",
		help =&gt; "some help text",
		required =&gt; 0
	}
);

Opts::add_options(%opts);

my %opts = (

'option_name' => {

alias => "O",

type => "=s",

help => "some help text",

required => 0

}

);

Opts::add_options(%opts);

The “alias” option is the short name for the option. With the above example, you could provide the option as --option_name value or -O value.

Unnamed parameter

Many of the VMware provided scripts (the vswitch scripts come to mind) have a parameter specified at the end of the line that is not preceded by a --param_name specifier. This is defined as _default_, and can be retrieved using that name. If you provide _default_ in the options hash passed to Opts::add_options the help will be provided when the usage message is written.

Example:

# command passed: script_name.pl --server your.server some_value
print Opts::get_option('_default_'); # prints "some_value"

1 2	# command passed: script_name.pl --server your.server some_value print Opts::get_option('_default_'); # prints "some_value"

Custom validation

By passing subroutines to Opts::validate() you can do your own validation of options passed validation. If they do not, then the script exits in the normal way (print usage message). Multiple subroutines can be passed as additional arguments.

Opts::validate( string sub_routine_name, string ..., ... );

Example:

# if my_validate returns false (or 0) the script will exit and print the usage message
Opts::validate(&amp;my_validate);
		
sub my_validate {
	if (defined(Opts::get_option('something_required')) {
		return 1;
	} else {
		return 0;
	}
}

# if my_validate returns false (or 0) the script will exit and print the usage message

Opts::validate(&my_validate);

sub my_validate {

if (defined(Opts::get_option('something_required')) {

return 1;

} else {

return 0;

}

Setting an Option’s value

Simply sets the value of an option to the value specified. The option must be a valid option (a predefined option such as --server or a user created option via Opts::add_options), it can not be “created” by this operation.

Opts::set_option('option_name', 'option_value');

1	Opts::set_option('option_name', 'option_value');

Get a host view easily

Using the --vihost option, get_host_view retrieves the host view of an ESX host if you are connected to VC or the host directly. If required_host is specified, it will exit if --vihost is not specified on the command line.

VIExt::get_host_view( bool required_host );

Example:

my $host = VIExt::get_host_view( 1 );

1	my $host = VIExt::get_host_view( 1 );

Fail

Shows a failure/error message and gracefully ends the script (disconnects and exits with code "1");

VIExt::fail( string message );

Example:

VIExt::fail("Unable to find host view");

1	VIExt::fail("Unable to find host view");

Get common Managed-Object-Reference (MOR) Views

Get the file manager MOR

VIExt::get_file_manager();

1	VIExt::get_file_manager();

Get the virtual disk manager MOR

VIExt::get_virtual_disk_manager();

1	VIExt::get_virtual_disk_manager();

Unadvertized VI Perl Toolkit helper functions and options

Related

2 thoughts on “Unadvertized VI Perl Toolkit helper functions and options”

Leave a Reply Cancel reply