Write-TcValue
SYNOPSIS
Write values to TwinCAT devices.
SYNTAX
NetIdPortSymbol (Default)
Write-TcValue [-NetId <AmsNetId[]>] -Port <Int32> [-Value <Object>] [-Path] <String> [-Encoding <Encoding>]
[-Timeout <Int32>] [-Force] [-ResetSymbols] [-Quiet] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm]
[<CommonParameters>]
NetIdPortIndexed
Write-TcValue [-NetId <AmsNetId[]>] -Port <Int32> [-Value <Object>] [-IndexGroup] <UInt32>
[[-IndexOffset] <UInt32>] [-Size <Int32>] [-Encoding <Encoding>] [-Timeout <Int32>] [-Force] [-Quiet]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
RouteIndexed
Write-TcValue -Route <IRoute[]> -Port <Int32> [-Value <Object>] [-IndexGroup] <UInt32>
[[-IndexOffset] <UInt32>] [-Size <Int32>] [-Encoding <Encoding>] [-Timeout <Int32>] [-Force] [-Quiet]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
RouteSymbol
Write-TcValue -Route <IRoute[]> -Port <Int32> [-Value <Object>] [-Path] <String> [-Encoding <Encoding>]
[-Timeout <Int32>] [-Force] [-ResetSymbols] [-Quiet] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm]
[<CommonParameters>]
AddressIndexed
Write-TcValue -Address <String[]> -Port <Int32> [-Value <Object>] [-IndexGroup] <UInt32>
[[-IndexOffset] <UInt32>] [-Size <Int32>] [-Encoding <Encoding>] [-Timeout <Int32>] [-Force] [-Quiet]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
AddressSymbol
Write-TcValue -Address <String[]> -Port <Int32> [-Value <Object>] [-Path] <String> [-Encoding <Encoding>]
[-Timeout <Int32>] [-Force] [-ResetSymbols] [-Quiet] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm]
[<CommonParameters>]
SessionIndexed
Write-TcValue -Session <ISession[]> [-Value <Object>] [-IndexGroup] <UInt32> [[-IndexOffset] <UInt32>]
[-Size <Int32>] [-Encoding <Encoding>] [-Timeout <Int32>] [-Force] [-Quiet]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
SessionSymbol
Write-TcValue -Session <ISession[]> [-Value <Object>] [-Path] <String> [-Encoding <Encoding>]
[-Timeout <Int32>] [-Force] [-ResetSymbols] [-Quiet] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm]
[<CommonParameters>]
SessionIdIndexed
Write-TcValue -SessionId <Int32[]> [-Value <Object>] [-IndexGroup] <UInt32> [[-IndexOffset] <UInt32>]
[-Size <Int32>] [-Encoding <Encoding>] [-Timeout <Int32>] [-Force] [-Quiet]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
SessionIdSymbol
Write-TcValue -SessionId <Int32[]> [-Value <Object>] [-Path] <String> [-Encoding <Encoding>] [-Timeout <Int32>]
[-Force] [-ResetSymbols] [-Quiet] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm]
[<CommonParameters>]
InputObject
Write-TcValue [-Value <Object>] [-InputObject] <ISymbol> [-Encoding <Encoding>] [-Timeout <Int32>] [-Force]
[-Quiet] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
DESCRIPTION
This Cmdlet writes values to TwinCAT Devices.
The devices can be accessed via different ValueProviders.
All sorts of ADS-addressing will be supported by this Cmdlet: Addressing by IndexGroup / IndexOffset (see IndexGroup, IndexOffset paramters) Addressing by Instance Path (see path parameter) Addressing by Symbol (see InputObject / Symbol parameter)
IMPORTANT: Writing values should be done with highest care because it could destabilize the TwinCAT System when the write operation is not addressed properly.
While writing with available symbol information is not critical and should be preferred the size and position of symbol data is known within the process image), the access via Instance path is less secure.
The size of the overwritten data is not known and therefore not checked by the Cmdlet.
The highest attention should be taken with write IndexGroup / IndexOffset write operations because beneath the unknown data size even the position of the data is not checked.
The data is written directly into the process image.
EXAMPLES
EXAMPLE 1
PS> $session = New-TcSession -NetId 1.2.3.4.5.6 -Port 851
PS> $projectNameSymbol = $session | Get-TcSymbol -path "*ProjectName"
PS> $projectNameSymbol
InstanceName DataType Size InstancePath
------------ -------- ---- ------------
ProjectName STRING(63) 64 TwinCAT_SystemInfoVarList._AppInfo.ProjectName
PS> $projectNameSymbol | Read-TcValue
OldProjectName
PS> $projectNameSymbol | Write-TcValue -Value "NewProjectName" -force
PS> $projectNameSymbol | ReadTcValue
NewProjectName
This example shows how to create a session, determining the Symbol 'ProjectName within the _AppInfo Struct on a running PLC project and reading its value.
After that, the Value will be overwritten with 'NewProjectName'.
EXAMPLE 2
Write-TcValue -session $session -IndexGroup 0x4040 -IndexOffset 0x1247A8 -Value "NewProjectName"
Writes a string typed Value to the specified IndexGroup/IndexOffset Address.
PARAMETERS
-NetId
The ADS target NetID(s) of the system(s) where to write the Value.
More than one target will be supported.
Type: AmsNetId[]
Parameter Sets: NetIdPortSymbol, NetIdPortIndexed
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Route
The target system (as Route) where to write the value.
Type: IRoute[]
Parameter Sets: RouteIndexed, RouteSymbol
Aliases: Destination
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Address
The target address where to write the Value.
The Address can consist of RouteName, NetId, HostName or IPAddress.
Wildcards are permitted.
Type: String[]
Parameter Sets: AddressIndexed, AddressSymbol
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True
-Session
The session object represents the target session where to write the value.
Type: ISession[]
Parameter Sets: SessionIndexed, SessionSymbol
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False
-SessionId
The session ID represents the target session where to write the value.
Type: Int32[]
Parameter Sets: SessionIdIndexed, SessionIdSymbol
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Port
The Port, where to write the value.
This Parameter is used in combination with the NetId, Route or Address input parameter.
Type: Int32
Parameter Sets: NetIdPortSymbol, NetIdPortIndexed, RouteIndexed, RouteSymbol, AddressIndexed, AddressSymbol
Aliases:
Required: True
Position: Named
Default value: 10000
Accept pipeline input: False
Accept wildcard characters: False
-Value
The value to write.
If no additional Length parameter is set, the Write-TcValue Cmdlet marshalls this value to its appropiate size.
To not overwrite data of other symbols within the process image, special attention must be taken (see the Confirm and Whatif parameters).
Type: Object
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-IndexGroup
IndexGroup of the Value to write, only for IndexGroup/IndexOffset access.
IMPORTANT: Please be aware, that writing data via IndexGroup/IndexOffset simply overwrites data in the ProcessImage and can destabilize the system.
No validity check is done for the symbol alignment and therefore this should be done with highest care!
If applicable writing data via symbolic information should be preferred!
Type: UInt32
Parameter Sets: NetIdPortIndexed, RouteIndexed, AddressIndexed, SessionIndexed, SessionIdIndexed
Aliases: IG
Required: True
Position: 1
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-IndexOffset
IndexOffset of the Value to write, only for IndexGroup/IndexOffset access.
IMPORTANT: Please be aware, that writing data via IndexGroup/IndexOffset simply overwrites data in the ProcessImage and can destabilize the system.
No validity check is done for the symbol alignment and therefore this should be done with highest care!
If applicable writing data via symbolic information should be preferred!
Type: UInt32
Parameter Sets: NetIdPortIndexed, RouteIndexed, AddressIndexed, SessionIndexed, SessionIdIndexed
Aliases: IO
Required: False
Position: 2
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-Size
The Length of the data that will be overwritten within the process image.
IMPORTANT: Please be aware, that writing data via IndexGroup/IndexOffset simply overwrites data in the ProcessImage and could destabilize the system.
No further validity check is done for the symbol alignment and therefore this should be done with highest care (best with use of the -Confirm and -Whatif Cmdlet arguments).
If applicable writing data via symbolic information should be preferred!
Type: Int32
Parameter Sets: NetIdPortIndexed, RouteIndexed, AddressIndexed, SessionIndexed, SessionIdIndexed
Aliases: Length, WriteSize
Required: False
Position: Named
Default value: -1
Accept pipeline input: False
Accept wildcard characters: False
-Path
The instance path to the symbol to write (Symbolic access).
Wildcards are permitted.
Type: String
Parameter Sets: NetIdPortSymbol, RouteSymbol, AddressSymbol, SessionSymbol, SessionIdSymbol
Aliases:
Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: True
-InputObject
The symbol object on which to write the value.
Type: ISymbol
Parameter Sets: InputObject
Aliases: Symbol
Required: True
Position: 1
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False
-Encoding
Specifies the Encoding for strings.
The Default is ANSI with actual code page.
Type: Encoding
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: System.Text.SBCSCodePageEncoding
Accept pipeline input: False
Accept wildcard characters: False
-Timeout
The communication ADS timeout in milliseconds.
A value of 0 disables the timeout.
A value \<= 0 sets the Default (5000 ms).
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: -1
Accept pipeline input: False
Accept wildcard characters: False
-Force
Forces the write operation, even if the FailFastHandler is active.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-ResetSymbols
Resets the symbols and datatypes cache when using symbolic access.
Type: SwitchParameter
Parameter Sets: NetIdPortSymbol, RouteSymbol, AddressSymbol, SessionSymbol, SessionIdSymbol
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-Quiet
The Quiet parameter suppresses the 'ShouldProcess' messsage and the Cmdlet will be processed without further user confirmation.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: Silent
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-Confirm
Prompts you for confirmation before running the cmdlet.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ProgressAction
{{ Fill ProgressAction Description }}
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-WhatIf
Shows what would happen if the cmdlet runs.
The cmdlet is not run.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
INPUTS
TwinCAT.ISession[]
The session object represents the target session where to write the value.
TwinCAT.TypeSystem.ISymbol
The symbol object on which to write the value.