Optionally, you can define script-specific command-line options.

When you run a script from the command line, you usually specify connection information and might also specify other information such as a virtual machine that you want to power off or a host for which you need status information. vSphere SDK for Perl lets you specify these options in a variety of ways. See Specifying Options.

A number of common command-line options, most of them connection options, are already defined for all utility applications (see Options Available for All SDK for Perl Commands). In addition, most applications have application-specific options you pass to the script at execution time.

The vSphere SDK for Perl has defined all common options using attributes and subroutines specified in the VILib::Opts package. You can similarly use the VILib::Opts package to create custom options for your own applications and scripts, to simplify use of your script, or to allow users to specify other information.

Sample Script (Commented Version) defines an entity option that must be made available to the script at runtime. The option specifies which of the available entity types is passed as a parameter to the Vim::find_entity_views() subroutine for further processing. Any direct or indirect subclass of ManagedEntity is a valid option (for example HostSystem, ResourcePool, or VirtualMachine). The example creates and parses a new command-line option.

  1. The example declares the option as a hash. The hash key is the option name, and the value is a hashref containing Getopt::Long-style option attributes. See Attributes for Defining New Options for attribute details.

    Sample Script (Commented Version) creates a required command-line option that accepts a string value, as follows. 

    my %opts = (
         entity => {
         type => "=s",
         variable => "VI_ENTITY",
         help => "ManagedEntity type: HostSystem, etc",
         required => 1,
     },
);

    Attributes for Defining New Options lists all attributes you can use to define command-line options. The code fragment in Step 1: Import the vSphere SDK for Perl Modules above uses only type, variable, help, and required. For related information, see the documentation for the Getopt::Long module.

    Table 1. Attributes for Defining New Options
    Attribute Description
    default Default value used if the option is not explicitly set. An unset option with no default returns undef to the calling script.
    func Enables creating derived options. Set func to an external code reference to run the code when the SDK queries the value of the option.
    help Descriptive text explaining the option, displayed in the script’s help message.
    required If this attribute is set to 1, users must provide a value for this option or the script exits and display the help message. Set to 1 to require a value. Set to 0 if the value is optional.
    variable Allows you to specify the option in an environment variable or a configuration file. See Specifying Options.
    type Uses Perl Getopt-style syntax to specify option type and whether the option is required or optional.

    Use double quotes to indicate that option doesn’t accept a value. The default numeric value is 0. The default string value is " " (empty string). You can use one of the following:

    • Equal sign (=) — mandatory
    • Colon (:) — optional
    • s — string
    • i — integer
    • f — float
  2. The example adds the option to the default options by using the Opts::add_options() subroutine. 
    Opts::add_options(%opts);
  3. The example parses and validates the options before connecting to the server, as follows. 
    Opts::parse();
Opts::validate();

In Sample Script (Commented Version), the entity option is required, so the script cannot run unless the user passes in the option name and value (see Specifying Options).

The Vim::find_entity_views() subroutine uses the value the user passes in later in the script. The value must be one of the managed-entity types listed as view_type parameter supported by Vim::find_entity_views().

Note:

Your script must call Opts::parse() and Opts::validate() to process the options available for all scripts, even if you do not define script-specific command-line options.

When you attempt to run a script and do not supply all necessary options, the vSphere SDK for Perl displays usage help for the script, as in the following example. 

perl simpleclient.pl
Required command option 'entity' not specified
Common VI options:
. . .

Command-specific options:
--entity (required)
ManagedEntity type: ClusterComputeResource, ComputeResource, Datacenter,
Folder, HostSystem, ResourcePool, VirtualMachine...