Set-SCVirtualCOMPort

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

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

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

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. 

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

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

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

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

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

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. 

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

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

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

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

Specifies a VMM server object.

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.

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

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. 

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

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

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

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

Specifies a VMM server object.

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

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. 

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.

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

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

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

Specifies a VMM server object.

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

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. 

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" 

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

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

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

Specifies a VMM server object.

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

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. 

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.

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

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

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

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

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. 

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" 

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

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

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

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

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. 

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

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

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

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

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.

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

Examples

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"

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

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.

See Also

• VMM 2012 - Cmdlets Help Index
• Get-SCVirtualCOMPort