Using vSphere SDK for Perl

This section explains how to get started with vSphere SDK for Perl by looking at two typical usage scenarios. It also lists common vSphere SDK for Perl tasks and discusses programming conventions.

Getting Started

If you want to use the SDK to retrieve performance information for a host, you might perform the following tasks:

1	Check the vSphere SDK for Perl Utility Applications Reference or the apps directory for a script that retrieves performance information.

Check /usr/lib/vmware-vcli/apps on Linux and Program Files\VMware vSphere CLI\Perl\apps on Windows. All utility applications are fully supported.

The viperformance.pl script retrieves performance counters from the host.

Note If you cannot find a utility application, examine the sample scripts. You can use sample scripts as starting points for your application. On Linux, /usr/share/doc/vmware-vcli/samples, on Windows, Program Files\VMware\VMware vSphere CLI\Perl\samples. Sample scripts are not supported.

2	Run the script with the --help option or without any options to see its online documentation. More detailed information is in the Utility Applications Reference included in the vSphere SDK for Perl documentation set and available from the VMware Web site.

3	Run the viperformance.pl script.

viperformance.pl --url https://<host>:<port>/sdk/vimService --username nemo --password fi\$h --host Aquarium --countertype net --interval 30 --samples 3

Escape characters must precede special characters in passwords. See Options Available for all vSphere SDK for Perl Scripts for a complete list of connection parameters.

If you want to use the SDK for a task that none of the utility applications can perform, you might perform the following tasks:

1	Check the /samples folder for a sample script that performs a similar task. The scripts in the samples folder are available for customization.

2	If a script that performs a similar task is available, modify the script. If none of the scripts is suitable, write a new script using the vSphere SDK for Perl subroutines.

The following materials are available for modifying or writing scripts:

Source	Description
Writing vSphere SDK for Perl Scripts.	In-depth discussion of scripts that includes an example.
vSphere SDK for Perl Subroutine Reference.	Reference to vSphere SDK for Perl subroutines.
Web Services for Management Perl Library.	Allows you to write scripts that retrieve CIM data from the ESX/ESXi host using CIMOM, a service that provides standard CIM management functions over a WBEM (Web-Based Enterprise Management).
Credential Store Perl Library.	Allows vSphere SDK for Perl applications to manage the vSphere credential store.
vSphere API Reference documentation.	Reference to the server-side object your script interacts with.

3	Follow these programming conventions when you modify or create vSphere SDK for Perl scripts:

■	Use parameter names followed by parameter values, as follows:

Vim::<subroutine>(<parameter_name>=><value>, <parameter_name>=><value> );

Util::<subroutine>(<parameter_name>=><value>, <parameter_name>=><value> );

Opts::<subroutine>(<parameter_name>=><value>, <parameter_name>=><value> );

■	Use the options in Options Available for all vSphere SDK for Perl Scripts to specify connection information.

■	Use the mechanism discussed in Step 2: (Optional) Define Script-Specific Command-Line Options for specifying additional script-specific options.

Common vSphere SDK for Perl Tasks

The vSphere SDK for Perl includes utility applications and sample scripts for common administration tasks.

Common Administrative Tasks and SDK Utilities 

Task	Script	Location
Discovery (logging in)	connect.pl	/apps/general
Performance monitoring	viperformance.pl (retrieves performance counters from host)	/apps/performance
Virtual machine power operations	vmcontrol.pl	/apps/vm
Virtual machine snapshot and restore functionality	vmsnapshot.pl, snapshotmanager.pl	/apps/vm
Virtual machine migration	vmmigrate.pl	/apps/vm
Host operations, for example, adding a standalone host to a vCenter Server system, shutting down and rebooting a host, and so on	hostops.pl	/apps/host
Viewing or changing of CPU or memory share allocation on a virtual machine	sharesmanager.pl	/apps/vm

Some tasks require additional scripting. See Writing vSphere SDK for Perl Scripts.

vSphere SDK for Perl Programming Conventions

Several programming conventions are different than you might expect because the SDK interacts with a server using SOAP/WSDL.

■	Boolean data types – SDK applications send and receive Boolean values as follows:

■	Input (sending from the client application):

	false:	Use 0, '0', or 'false' (capitalization ignored)
	true:	Use 1, '1', or 'true' (capitalization ignored)

■	Output (receiving from the server):

	false:	Return value is 0
	true:	Return value is 1

To match Boolean values in a filter, use the strings true and false. See Creating and Using Filters.

■	Date/Time – The server returns a SOAP dateTime value. You can use the Date::Parse Perl module to process these objects.

The vSphere SDK for Perl accepts only native SOAP dateTime values using standard date time format with or without fractional seconds, and with or without GMT (Z) time zone:

YYYY-MM-DDThh:mm:ssTZD, for example, 1997-07-16T19:20:30+01:00
YYYY-MM-DDThh:mm:ss.sTZD, for example, 1997-07-16T19:20:30.45+01:00

The SDK always returns dateTime values in the standard date time format.

■	SOAP error message – Most likely indicates an error on the server, not an error with the communication to the server.