VMware vSphere SDKs and Tools 6.7

8.0 7.0 6.7 6.5

Step 2: (Optional) Define Script-Specific Command-Line Options

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 Table 1). 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 Table 1 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,
     },
);
    Table 1 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.
    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()
.
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...

Content feedback and comments