Subroutines in the Vim Package

The Vim package includes the following subroutines:

■	clear_session

■	find_entity_view

■	find_entity_views

■	get_service_instance

■	get_service_content

■	get_session_id

■

get_view

■

get_views

■	load_session

■

login

■

logout

■	save_session

■	update_view_data

clear_session

Terminates the current session loaded by the load_session() subroutine.

Parameters

No parameters.

Returns

Returns nothing.

find_entity_view

Searches the inventory tree for a managed entity that matches the specified entity type. The search begins with the root folder unless the begin_entity parameter is specified.

In most cases, you specify a filter or property when using this command to avoid performance problems. See Creating and Using Filters and Filtering Views Selectively Using Properties.

Parameters

Parameter	Description
view_type	Managed entity type specified as one of these strings: ■ “ClusterComputeResource” ■ “ComputeResource” ■ “Datacenter” ■ “Datastore” ■ “DistributedVirtualSwitch” ■ “Folder” ■ “HostSystem” ■ “Network” ■ “ResourcePool” ■ “VirtualApp” ■ “VirtualMachine”
begin_entity (optional)	Managed object reference that specifies the starting point for the search in the inventory. This parameter helps you narrow the scope.
filter	Hash of one or more name-value pairs. The name represents the property value to test and the value represents a pattern that the property must match. If more than one pair is specified, all the patterns must match. Use filters to avoid performance problems. See Creating and Using Filters and Filtering Views Selectively Using Properties.

Returns

Reference to a view object containing the same properties as the managed entity. If more than one managed entity matches the specified entity type, the subroutine returns only the first managed entity found. If no matching managed entities are found, the subroutine returns undef.

find_entity_views

Searches the inventory tree for managed objects that match the specified entity type.

To avoid performance problems, use this command with a filter or specify the properties argument. By default, this subroutine retrieves all properties of an entity. See Creating and Using Filters and Filtering Views Selectively Using Properties.

See the vSphere SDK for Perl API Reference for a list of properties. You can specify properties inherited from ManagedEntity or local to a specific entity type.

Parameters

Parameter	Description
view_type	Managed entity type specified as one of these strings: ■ “ClusterComputeResource” ■ “ComputeResource” ■ “Datacenter” ■ “Datastore” ■ “DistributedVirtualSwitch” ■ “Folder” ■ “HostSystem” ■ “Network” ■ “ResourcePool” ■ “VirtualApp” ■ “VirtualMachine”
begin_entity (optional)	Managed object reference that specifies the starting point for search in the inventory. This parameter helps you narrow the scope.
filter (optional)	Hash of one or more name-value pairs. The name represents the property value to test and the value represents a pattern that the property must match. If more than one pair is specified, all the patterns must match.
properties	Properties to retrieve. Default is all properties. Use a filter or properties to avoid performance problems. See Filtering Views Selectively Using Properties.

Returns

Reference to an array of view objects containing static copies of property values for the matching inventory objects. If no matching entities are found, the array is empty.

Example

The following example, originally published in VMware Communities in post #1272780, retrieves the name property from each inventory object. Note that $entity_views extracted from the server-side managed object is an array reference, not a scalar.

...

my %opts = (

      entity => {

      type => "=s",

      variable => "VI_ENTITY",

      help => "ManagedEntity type: HostSystem, etc",

      required => 1, },

);

Opts::add_options(%opts);

Opts::parse();

Opts::validate();

Util::connect();

 

# Obtain all inventory objects of the specified type

my $entity_type = Opts::get_option('entity');

my $entity_views = Vim::find_entity_views();

      view_type => $entity_type,

      properties => [ 'name' ]);

...

get_service_instance

Retrieves a ServiceInstance object, which can be used to query the server time or to retrieve the ServiceContent object.

Parameters

No parameters.

Returns

Returns a ServiceInstance object.

get_service_content

Retrieves properties of the service instance enabling access to the managed objects of the service. Alternatively, you can use get_views(), get_view(), and other subroutines to access the objects more directly. If you start with the service content to work with the Web service, you can navigate to the object of interest.

Parameters

No parameters.

Returns

Reference to ServiceContent object, which contains managed object references to all inventory content, including the root folder.

get_session_id

Retrieves the session ID corresponding to the current session.

Parameters

No parameters.

Returns

Session ID cookie for use by load_session().

get_view

Retrieves the properties of a single managed object.

Parameters

Parameter	Description
mo_ref	Managed object reference obtained from a property of another managed object or a view.
view_type (optional)	Type of view to construct from the managed object. If the parameter is absent, the subroutine constructs a view with a type that matches the managed object type name.

Returns

View object containing static copies of a managed object’s property values.

get_views

Retrieves the properties of a set of managed objects.

Parameters

Parameter	Description
mo_ref_array	Reference to an array of managed object references.
view_type (optional)	Type of view to construct from the managed object. If the parameter is absent, the subroutine constructs a view with a type that matches the name of the managed object type.

Returns

Reference to an array of view objects containing copies of property values for multiple managed objects.

Notes

The Vim::get_views() subroutine takes a reference to an array of managed object references and returns a reference to an array of view objects. Although the array can contain multiple managed object types, objects of only one type can be obtained at the same time.

load_session

Uses a saved session file or session cookie for connecting to a server. Use Util::connect() instead of Vim::login() after loading the session.

You can use save_session() to get a session file or get_session_id() to get a session ID.

Parameters

Parameter	Description
service_url	URL of the server to which the client connects (optional if using session_file).
session_file	Full path and filename for a session file returned by save_session(). You must specify either session_file or session_id. You must pass in the filename as a hash.
session_id	Session ID returned by get_session_id(). You must specify either session_file or session_id.

Returns

Returns the vSphere object instance.

Example

To load a session using a session file: load_session(session_file => $filename);

To load a session using a session ID: load_session(service_url => $url, session_id => $sessionid);

login

Establishes a session with the Web service running on the vCenter Server or ESX/ESXi system using the user name and password credentials provided using the command-line, environment variables, or configuration file.

Note In most cases, you use Util::connect() instead to establish a connection.

Parameters

Parameter	Description
service_url	URL of the server to which the client connects.
user_name	User account on the ESX/ESXi or vCenter Server system.
password	Password for the user account.

Returns

Returns the vSphere object instance.

logout

Disconnects the client from the server and closes the connection to the Web service. Use this subroutine if you connected using Vim::login(). Otherwise, use Util::disconnect().

Parameters

No parameters.

Returns

Returns nothing.

save_session

Saves a session cookie, which is a text file. See Using a Session File.

Parameter

Parameter	Description
session_file	Full path and filename where the token should be saved. The session times out after 30 minutes. You pass in the filename as a hash.

Returns

Returns nothing.

Example

save_session (session_file => $filename);

update_view_data

Refreshes the property values of a view object.

Parameters

No parameters.

Returns

Returns nothing.