TOPIC
    about_obn

SHORT DESCRIPTION
    A feature for specifying an object by its name. Instead of passing an object
    to a cmdlet parameter through a pipeline or by a variable, users can
    directly assign to the parameter the object name.

LONG DESCRIPTION
    The Object-by-Name (OBN) selection is a feature for specifying an object by
    its name. Instead of passing an object to a cmdlet parameter through a
    pipeline or a variable, users can directly assign to the parameter the
    object name. A lot of PowerCLI cmdlets parameters support OBN.

Example 1: The following three lines are interchangeable:
    1. Remove-VM -VM "Win XP SP2"
    2. Get-VM -Name "Win XP SP2" | Remove-VM
    3. Remove-VM -VM (Get-VM -Name "Win XP SP2")

    If one of the provided object names is not recognized, a non-terminating
    error is generated and the cmdlet runs ignoring the invalid name. This is
    called an "OBN failure".

Example 2: An "OBN Failure".
    Set-VM -VM "VM1", "VM2", "VM3" -Server $server1, $server2 -MemoryGB 2

    If the VM2 virtual machine does not exist on either of the specified
    servers, a non-terminating error is thrown and the command runs only on the
    VM1 and VM3 virtual machines.

OBN AND WILDCARDS
    When specifying objects by name, you can use the standard PowerShell
    wildcards.

DETERMINING THE OBN SERVER LIST
    You can use the Server parameter of a cmdlet to specify the servers from
    which to retrieve the objects specified by name. In such cases, the Server
    parameter can be set only if the parameter that takes an object name is
    specified.

Example 3: Using OBN and the cmdlets Server parameter.
    Stop-VM -Server $svr1

    To make the upper command work, you must provide at least one virtual
    machine name to the cmdlet VM parameter.

    Stop-VM -Server $svr1 -VM "Win XP SP2"

    If the Server parameter is not specified, OBN uses the servers associated
    with the objects passed as arguments to the other cmdlet parameters. If the
    arguments objects are associated with different servers, OBN is aborted for
    the current call and a non-terminating error is generated. The Server
    parameter also supports OBN. You can specify servers either by their
    corresponding VIServer objects, or  by their names.

Example 4: Using OBN with a server associated with the specified objects.
    Move-VM -VM "Win XP SP2" -VMHost $myHost

    The upper command will work only if the Win XP SP2 virtual machine and the
    $myHost host are associated with one and the same server. Otherwise, an
    error is generated.
    If there are no servers specified by the Server parameter or associated with
    the provided objects, the default server is used for OBN.

Example 5: Using OBN with the default server.
    Move-VM -VM "Win XP SP2" -VMHost $myHost

    If no server is associated with the specified objects, the default server is
    used for OBN. If a cmdlet parameter receives both managed objects and names,
    the Server parameter applies only to the names and the managed objects are
    not filtered based on the servers. If all cmdlet parameters receive only
    objects, and if a server list is specified, the server list is ignored.

OBN ARGUMENT MULTIPLICITY AND PARAMETER MULTIPLICITY
    After the object selection by name is performed, the returned objects are
    passed to the parameter together with the objects specified directly, if
    any, and the process continues.

    Remove-VM -VM $vm1, $vm2, "Win XP SP2", $vm3, "linux*"
    # ...is equivalent to...
    Remove-VM -VM $vm1, $vm2, <the one or more objects named "Win XP SP2">, $vm3, <the zero or more objects, whose names start with "linux">

    If a parameter receives multiple names specified by OBN as a part of its
    argument, and if the OBN for two of these names retrieves duplicate objects,
    these duplicates are not eliminated and the cmdlet works as if invoked with
    duplicate objects.
    If the OBN selection returns no objects for a parameter that is specified as
    mandatory, or returns more than one object for a parameter that takes a
    single argument, an error is generated.

COPYRIGHT
    Copyright (C) VMware, Inc. All rights reserved. Protected by one or more
    U.S. Patents listed at http://www.vmware.com/go/patents.

