Understanding Operations and Methods

The vSphere SDK for Perl runtime maps server-side operations to client-side Perl view object methods. For each operation defined on a server managed object, the vSphere SDK for Perl creates a corresponding view method when it creates the view object.

Non-Blocking and Blocking Methods

All server-side operations available in the vSphere API are non-blocking operations listed in the vSphere API Reference Guide. The vSphere SDK for Perl provides a non-blocking method corresponding to the server-side operation, and also provides a blocking (synchronous) method (<opname>() method).

■

Non-blocking methods – Asynchronous methods that return control to the client immediately after invocation and return a task object to the calling program. Non-blocking methods allow you to monitor progress (of the *_Task object) outside the main processing logic of the script. This monitoring can be useful during long-running operations. These methods also allow you to interleave local (client-side) processing and server-side processing.

■	Blocking methods – Synchronous methods that fully process the operation before returning control to the client script. Does not return a reference to a task object.If you use a blocking method, you do not have to handle a task object with additional code.

Examples of Operations

The following table lists some of the operations available for a VirtualMachine managed object.

Examples for Asynchronous and Synchronous Methods 

vSphere API Non-blocking (asynchronous)	vSphere SDK for Perl Non-blocking (asynchronous)	vSphere SDK for Perl Only Blocking (synchronous)
PowerOnVM_Task()	PowerOnVM_Task()	PowerOnVM()
CloneVM_Task()	CloneVM_Task()	CloneVM()
SuspendVM_Task()	SuspendVM_Task()	SuspendVM()

See the vSphere API Reference Guide for lists of all operations for each managed object.

Calling Methods

After you have retrieved the view object that corresponds to a managed object, you can run methods on that view to make use of the managed object’s services. You run a method by specifying the method’s name parameter, for example:

$vm->MigrateVM (name => 'productionVM');

The type of parameter required by the method depends on the operation defined in the vSphere API. It might be a simple type, data object, or managed object reference. For information about specific parameters and data types, see the vSphere API Reference Guide.

Blocking operations are run as methods on a view object. For example, to suspend a virtual machine, call:

$vm_view->SuspendVM();

You can execute any operation that is defined for a managed object as a method on a corresponding view object. Because the vSphere SDK for Perl creates an accessor and a mutator method (getter and setter method) for each property defined in the managed object, you can reference the name of any property as a method call of the view, for example:

my $network_name = $network_view->name

The vSphere SDK for Perl allows you to pass a view object to a method that requires a ManagedObjectReference. For example, if you have the view that represents a host ($host), you can pass the view to the powerOn() method as follows:

my $host = Vim::find_entity_view (view_type => 'HostSystem', name => 'my host');

my $vm = Vim::find_entity_view (view_type => 'VirtualMachine', name => 'my virtual machine');

$vm->powerOn (host => $host)

Note Specifying Untyped Arguments in Scheduled Tasks and Callbacks discusses using the vSphere SDK for Perl PrimType structure in some calls.

Omitting Optional Arguments in Method Calls

When you call a vSphere API method using vSphere SDK for Perl, and want to omit an optional argument, you can do one of two things:

■	You can omit the argument:

$vm->PowerOnVM(host => $host); # with the optional host argument

$vm->PowerOnVM(); # without the optional host argument

■	You can supply undef as the value of the optional argument:

$vm->PowerOnVM(host => undef);

Supplying undef as the value of the optional argument is useful when the value of an argument, which might or might not be undef, is contained in a variable, as in the following example:

my $host = Vim::find_entity_view(

view_type => 'HostSystem',

filter => { name => 'preferredHost' }

);

$vm->PowerOnVM(host => $host);

You cannot use the empty string or the value 0 to represent undef or an unset parameter.