Export (0) Print
Expand All
Expand Minimize

Set-SCVirtualCOMPort

Updated: September 27, 2012

Applies To: System Center 2012 - Virtual Machine Manager

Set-SCVirtualCOMPort

Changes properties of a virtual COM port associated with a virtual machine, virtual machine template, or hardware profile.

Syntax

Parameter Set: NamedPipe
Set-SCVirtualCOMPort [-VirtualCOMPort] <VirtualCOMPort> -NamedPipe <String> [-JobGroup <Guid> ] [-JobVariable <String> ] [-PROTipID <Guid> ] [-RunAsynchronously] [ <CommonParameters>]

Parameter Set: NewParentJobGroupHostPort
Set-SCVirtualCOMPort -GuestPort <Byte> -JobGroup <Guid> -VMHostCOMPort <Byte> [-JobVariable <String> ] [-PROTipID <Guid> ] [-RunAsynchronously] [-VMMServer <ServerConnection> ] [-WaitForModem <Boolean> ] [ <CommonParameters>]

Parameter Set: NewParentJobGroupNamedPipe
Set-SCVirtualCOMPort -GuestPort <Byte> -JobGroup <Guid> -NamedPipe <String> [-JobVariable <String> ] [-PROTipID <Guid> ] [-RunAsynchronously] [-VMMServer <ServerConnection> ] [ <CommonParameters>]

Parameter Set: NewParentJobGroupNoAttach
Set-SCVirtualCOMPort -GuestPort <Byte> -JobGroup <Guid> -NoAttach [-JobVariable <String> ] [-PROTipID <Guid> ] [-RunAsynchronously] [-VMMServer <ServerConnection> ] [ <CommonParameters>]

Parameter Set: NewParentJobGroupTextFile
Set-SCVirtualCOMPort -GuestPort <Byte> -JobGroup <Guid> -TextFile <String> [-JobVariable <String> ] [-PROTipID <Guid> ] [-RunAsynchronously] [-VMMServer <ServerConnection> ] [ <CommonParameters>]

Parameter Set: NoAttach
Set-SCVirtualCOMPort [-VirtualCOMPort] <VirtualCOMPort> -NoAttach [-JobGroup <Guid> ] [-JobVariable <String> ] [-PROTipID <Guid> ] [-RunAsynchronously] [ <CommonParameters>]

Parameter Set: TextFile
Set-SCVirtualCOMPort [-VirtualCOMPort] <VirtualCOMPort> -TextFile <String> [-JobGroup <Guid> ] [-JobVariable <String> ] [-PROTipID <Guid> ] [-RunAsynchronously] [ <CommonParameters>]

Parameter Set: VMHostCOMPort
Set-SCVirtualCOMPort [-VirtualCOMPort] <VirtualCOMPort> -VMHostCOMPort <Byte> [-JobGroup <Guid> ] [-JobVariable <String> ] [-PROTipID <Guid> ] [-RunAsynchronously] [-WaitForModem <Boolean> ] [ <CommonParameters>]




Detailed Description

The Set-SCVirtualCOMPort cmdlet changes one or more properties of a virtual communications (COM) port associated with a virtual machine, virtual machine template, or hardware profile used in a System Center Virtual Machine Manager (VMM) environment.

CONNECTING A VIRTUAL COM PORT

-----------------------------

Depending on the type of host on which a virtual machine is, or will be, deployed, you can use Set-SCVirtualCOMPort to connect a virtual COM port to a physical COM port on a host server, to a text file, or to a named pipe, or you can use it to disconnect a virtual COM port. Connecting a virtual COM port on a virtual machine to a physical COM port on its host lets the virtual machine use the physical COM port for input and output.

Type of Host Available Virtual COM Port Connection Types

------------ -------------------------------------------

Hyper-V Connects to a named pipe only

VMware ESX Connects to a physical COM port, text file, or named pipe

Citrix XenServer Not Supported

THE WAITFORMODEM PARAMETER

---------------------------

You can use the Set-SCVirtualCOMPort cmdlet with the WaitForModem parameter to specify whether a virtual COM port on a virtual machine will connect immediately to a physical COM port on the host when the virtual machine starts.

If WaitForModem is set to TRUE, the virtual machine attempts to connect to the physical COM port on the host only when a program running on the virtual machine sends a modem command to the physical COM port. If the COM port on the host is already connected, the virtual machine cannot connect to it. If the virtual machine successfully connects to the physical COM port, the virtual machine will later release the physical COM port back to the host operating system if the program on the virtual machine that uses the COM port stops using the COM port.

If WaitForModem is set to FALSE, the virtual machine attempts to connect to the physical COM port on the host as soon as the virtual machine starts. If the COM port on the host is already captured, the virtual machine cannot connect to it (same behavior as for TRUE). If the virtual machine successfully connects to the physical COM port, the virtual machine will not release the physical COM port back to the host operating system until the virtual machine is shut down (behavior for FALSE differs from behavior for TRUE).

PARAMETER SETS THAT USE VIRTUALCOMPORT VERSUS GUESTPORT

--------------------------------------------------------

The Set-SCVirtalCOMPort cmdlet uses the VirtualCOMPort parameter and the GuestPort parameter as follows:

- VirtualCOMPort <VirtualCOMPort>

Used with four Set-SCVirtualCOMPort parameter sets of to specify

a VirtualCOMPort object.

- GuestPort <Byte>

Used with four alternate Set-SCVirtualCOMPort parameter sets to

specify a virtual COM port by ID (0 or 1).

Review the syntax information for Set-SCVirtualCOMPort to see which parameter sets use the VirtualCOMPort parameter and which use the GuestPort parameter.

For more information about Set-SCVirtualCOMPort, type: "Get-Help Set-SCVirtualCOMPort -online".

Parameters

-GuestPort<Byte>

Specifies a virtual COM port on a virtual machine by a numerical identifier. Valid values are: 0 or 1.


Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByValue)

Accept Wildcard Characters?

false

-JobGroup<Guid>

Specifies an identifier for a series of commands that will run as a set just before the final command that includes the same job group identifier runs.


Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-JobVariable<String>

Specifies that job progress is tracked and stored in the variable named by this parameter.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-NamedPipe<String>

Specifies a named pipe to which to connect a virtual COM port. Typical uses include creating a connection between a virtual machine and a debugging program on the host (if the debugger supports the use of named pipes), or creating a virtual null modem cable between two virtual machines.

Example named pipe path: \\.\Contoso\Pipe\PipeName


Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-NoAttach

Specifies that no physical COM port on a host, named pipe, or file will be connected to a virtual COM port; or disconnects a virtual COM port that is already connected to a physical COM port to a named pipe, or to a text file.


Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-PROTipID<Guid>

Specifies the ID of the PRO tip that triggered this action. This allows for auditing of PRO tips.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-RunAsynchronously

Indicates that the job runs asynchronously so that control returns to the command shell immediately.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-TextFile<String>

Specifies a text file on the host to which to connect a virtual COM port on a virtual machine so that output from the virtual COM port can be sent to that text file. The text file can be on any valid disk drive on the host.

Example format: -TextFile "D:\ComPort.txt"


Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-VirtualCOMPort<VirtualCOMPort>

Specifies a virtual COM port object. VMM supports configuring two COM ports on a virtual machine, template, or hardware profile.


Aliases

none

Required?

true

Position?

1

Default Value

none

Accept Pipeline Input?

true (ByValue)

Accept Wildcard Characters?

false

-VMHostCOMPort<Byte>

Specifies a physical COM port object on a host server to which you can connect a virtual COM port.


Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-VMMServer<ServerConnection>

Specifies a VMM server object.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByValue)

Accept Wildcard Characters?

false

-WaitForModem<Boolean>

Specifies, when set to $True, that a virtual COM port will wait to connect to a physical COM port on the host, or, when set to $False, that the virtual COM port will connect immediately to a physical COM port on the host as soon as the virtual machine starts.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see about_CommonParameters.

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

Outputs

The output type is the type of the objects that the cmdlet emits.

  • VirtualCOMPort

Notes

  • Requires a VMM virtual COM port object. You can retrieve this object by using the Get-SCVirtualCOMPort cmdlet.

Examples

1: Connect a virtual COM port to a named pipe.

The first command gets the virtual machine object named VM02 and stores the object in the $VM variable.

The second command gets the virtual COM port named COM1 from VM02 and stores the object in the $COM1 variable.

The last command connects the virtual COM port to the named pipe \\Contoso\Pipe\PipeName.


PS C:\> $VM = Get-SCVirtualMachine -Name "VM02"PS C:\> $COM1 = Get-SCVirtualCOMPort -VM $VM | where {$_.Name -eq "COM1"}PS C:\> Set-SCVirtualCOMPort -VirtualCOMPort $COM1 -NamedPipe "\\Contoso\Pipe\PipeName"

2: Disconnect a virtual COM port.

The first command gets the virtual machine object named VM04 and stores the object in the $VM variable.

The second command gets the virtual COM port on VM04 named COM1 and stores the port object in the $COM1 variable.

The last command disconnects the virtual COM port object in $COM1 by specifying the NoAttach parameter.

NOTE: You can use this command to disconnect a virtual COM port that is currently connected to a physical COM port on a host, to a named pipe, or to a text file.


PS C:\> $VM = Get-SCVirtualMachine -Name "VM04"PS C:\> $COM1 = Get-SCVirtualCOMPort -VM $VM | where {$_.Name -eq "COM1"}PS C:\> Set-SCVirtualCOMPort -VirtualCOMPort $COM1 -NoAttach

Related topics

 
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft