OPC 10001-7 specifies the AddIn model as a mechanism to add dedicated features to an Object or ObjectType using aggregation.

The following features are based on this AddIn model.

The transfer of information (Parameters) between offline nodes and the physical device is supported through OPC UA Methods. These Methods are built on device specific knowledge and functionality.

The transfer is usually terminated if an error occurs for any of the Parameters. No automatic retry will be conducted by the Server. However, whenever possible after a failure, the Server should bring the Device back into a functional state. The Client has to retry by calling the transfer Method again.

The transfer may involve thousands of Parameters so that it can take a long time (up to minutes), and with a result that may be too large for a single response. Therefore, the initiation of the transfer and the collection of result data are performed with separate Methods.

The Device shall have been locked by the Client prior to invoking these Methods (see 8.3).

The TransferServicesType provides the Methods needed to transfer data to and from the online Device. Figure 32 shows the TransferServicesType definition. It is formally defined in Table 44.

Figure 32 – TransferServicesType

Table 44 – TransferServicesType definition

Attribute	Value
BrowseName	TransferServicesType
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
Subtype of the BaseObjectType defined in OPC 10000-5
HasComponent	Method	TransferToDevice			Mandatory
HasComponent	Method	TransferFromDevice			Mandatory
HasComponent	Method	FetchTransferResultData			Mandatory

The StatusCode Bad_MethodInvalid shall be returned from the Call Service for Objects where locking is not supported. Bad_UserAccessDenied shall be returned if the Client User does not have the permission to call the Methods.

The support of TransferServices for an Object is declared by aggregating an instance of the TransferServicesType as illustrated in Figure 33.

Figure 33 – TransferServices

This Object is used as container for the TransferServices Methods and shall have the BrowseName Transfer. HasComponent is used to reference from a Device to its “TransferServices” Object.

The TransferServiceType and each instance may share the same Methods.

TransferToDevice initiates the transfer of offline configured data (Parameters) to the physical device. This Method has no input arguments. Which Parameters are transferred is based on Server-internal knowledge.

The Server shall ensure integrity of the data before starting the transfer. Once the transfer has been started successfully, the Method returns immediately with InitTransferStatus = 0. Any status information regarding the transfer itself has to be collected using the FetchTransferResultData Method.

The Server will reset any cached value for Nodes in the online instance representing Parameters affected by the transfer. That way the cache will be re-populated from the Device next time they are requested.

The signature of this Method is specified below. Table 45 and Table 46 specify the arguments and AddressSpace representation, respectively.

Signature

TransferToDevice(

[out] Int32 TransferID,

[out] Int32 InitTransferStatus);

Table 45 – TransferToDevice Method arguments

Argument	Description
TransferID	Transfer Identifier. This ID has to be used when calling FetchTransferResultData.
InitTransferStatus	Specifies if the transfer has been initiated. 0 – OK -1 – E_NotLocked – the Device is not locked by the calling Client -2 – E_NotOnline – the Device is not online / cannot be accessed

Table 46 – TransferToDevice Method AddressSpace definition

Attribute	Value
BrowseName	TransferToDevice
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

TransferFromDevice initiates the transfer of values from the physical device to corresponding Parameters in the offline representation of the Device. This Method has no input arguments. Which Parameters are transferred is based on Server-internal knowledge.

Once the transfer has been started successfully, the Method returns immediately with InitTransferStatus = 0. Any status information regarding the transfer itself has to be collected using the FetchTransferResultData Method.

The signature of this Method is specified below. Table 47 and Table 48 specify the arguments and AddressSpace representation, respectively.

Signature

TransferFromDevice(

[out] Int32 TransferID,

[out] Int32 InitTransferStatus);

Table 47 – TransferFromDevice Method arguments

Argument	Description
TransferID	Transfer Identifier. This ID has to be used when calling FetchTransferResultData.
InitTransferStatus	Specifies if the transfer has been initiated. 0 – OK -1 – E_NotLocked – the Device is not locked by the calling Client -2 – E_NotOnline – the Device is not online / cannot be accessed

Table 48 – TransferFromDevice Method AddressSpace definition

Attribute	Value
BrowseName	TransferFromDevice
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

The TransferToDevice and TransferFromDevice Methods execute asynchronously after sending a response to the Client. Execution status and execution results are collected during execution and can be retrieved using the FetchTransferResultData Method. The TransferID is used as identifier to retrieve the data.

The Client is assumed to fetch the result data in a timely manner. However, because of the asynchronous execution and the possibility of data loss due to transmission errors to the Client, the Server shall wait some time (some minutes) before deleting data that have not been acknowledged. This should be even beyond Session termination, i.e. Clients that have to re-establish a Session after an error may try to retrieve missing result data.

Result data will be deleted with each new transfer request for the same Device.

FetchTransferResultData is used to request the execution status and a set of result data. If called before the transfer is finished it will return only partial data. The amount of data returned may be further limited if it would be too large. “Too large” in this context means that the Server is not able to return a larger response or that the number of results to return exceeds the maximum number of results that was specified by the Client when calling this Method.

Each result returned to the Client is assigned a sequence number. The Client acknowledges that it received the result by passing the sequence number in the new call to this Method. The Server can delete the acknowledged result and will return the next result set with a new sequence number.

Clients shall not call the Method before the previous one returned. If it returns with an error (e.g. Bad_Timeout), the Client can call the FetchTransferResultData with a sequence number 0. In this case the Server will resend the last result set.

The Server will return Bad_NothingToDo in the Method-specific StatusCode of the Call Service if the transfer is finished and no further result data are available.

The signature of this Method is specified below. Table 49 and Table 50 specify the arguments and AddressSpace representation, respectively.

Signature

FetchTransferResultData(

[in] Int32 TransferID,

[in] Int32 SequenceNumber,

[in] Int32 MaxParameterResultsToReturn,

[in] Boolean OmitGoodResults,

[out] FetchResultType FetchResultData);

Table 49 –FetchTransferResultData Method arguments

Argument	Description
TransferID	Transfer Identifier returned from TransferToDevice or TransferFromDevice.
SequenceNumber	The sequence number being acknowledged. The Server may delete the result set with this sequence number. “0” is used in the first call after initialising a transfer and also if the previous call of FetchTransferResultData failed.
MaxParameterResultsToReturn	The number of Parameters in TransferResult.ParameterDefs that the Client wants the Server to return in the response. The Server is allowed to further limit the response, but shall not exceed this limit. A value of 0 indicates that the Client is imposing no limitation.
OmitGoodResults	If TRUE, the Server will omit data for Parameters which have been correctly transferred. Note that this causes all good results to be released.
FetchResultData	Two subtypes are possible: TransferResultError Type is returned if the transfer failed completely TransferResultData Type is returned if the transfer was performed. Status information is returned for each transferred Parameter.

Table 50 – FetchTransferResultData Method AddressSpace definition

Attribute	Value
BrowseName	FetchTransferResultData
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

The FetchResultDataType is an abstract type. It is the base DataType for concrete result types of the FetchTransferResultData. Its elements are defined in Table 51.

Table 51 – FetchResultDataType structure

Attribute		Value
BrowseName		FetchResultDataType
IsAbstract		True
Subtype of Structure defined in OPC 10000-3
References	NodeClass		BrowseName	DataType
HasSubtype	DataType		TransferResultErrorDataType	Defined in Table 52.
HasSubtype	DataType		TransferResultDataDataType	Defined in Table 53.

The TransferResultErrorDataType is a subtype of the FetchResultDataType and represents an error result. It is defined in Table 52.

Table 52 – TransferResultError DataType structure

Name	Type	Description
TransferResultError DataType	Structure	This structure is returned in case of errors. No result data are returned. Further calls with the same TransferID are not possible.
status	Int32	-1 – Invalid TransferID: The Id is unknown. Possible reason: all results have been fetched or the result may have been deleted. -2 – Transfer aborted: The transfer operation was aborted; no results exist. -3 – DeviceError: An error in the device or the communication to the Device occurred. “diagnostics” may contain device- or protocol-specific error information. -4 – UnknownFailure: The transfer failed. “diagnostics” may contain Device- or Protocol-specific error information.
diagnostics	DiagnosticInfo	Diagnostic information. This parameter is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request. The DiagnosticInfo type is defined in OPC 10000-4.

The TransferResultData DataType is a subtype of the FetchResultDataType and includes parameter-results from the transfer operation. It is defined in Table 53.

Table 53 – TransferResultData DataType structure

Name	Type	Description
TransferResultData DataType	Structure	A set of results from the transfer operation.
sequenceNumber	Int32	The sequence number of this result set.
endOfResults	Boolean	TRUE – all result data have been fetched. Additional FetchTransferResultData calls with the same TransferID will return a FetchTransferError with status=InvalidTransferID. FALSE – further result data shall be expected.
parameterDefs	ParameterResult DataType []	Specific value for each Parameter that has been transferred. If OmitGoodResults is TRUE, parameterDefs will only contain Parameters which have not been transferred correctly.
NodePath	QualifiedName[]	List of BrowseNames that represent the relative path from the Device Object to the Parameter following hierarchical references. The Client may use these names for TranslateBrowsePathsToNodeIds to retrieve the Parameter NodeId for the online or the offline representation.
statusCode	StatusCode	OPC UA StatusCode as defined in OPC 10000-4 and in OPC 10000-8.
diagnostics	DiagnosticInfo	Diagnostic information. This parameter is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request. The DiagnosticInfo type is defined in OPC 10000-4.

Locking is the means to avoid concurrent modifications to a TopologyElement or Network and their components. Clients shall use the locking services if they need to make a set of changes (for example, several Write operations and Method invocations) and where a consistent state is available only after all of these changes have been performed. The main purpose of locking a TopologyElement is avoiding concurrent modifications. The main purpose of locking a Network is avoiding concurrent topology changes.

A lock from one Client usually allows other Clients to view (navigate/read) the locked element. Servers may choose to implement an exclusive locking where other Clients have no access at all (e.g. in cases where even read operations require certain settings in a TopologyElement).

When locking a TopologyElement, the lock applies to the complete TopologyElement (including all components such as blocks or modules).

Servers may allow independent locking of component TopologyElements, if no lock is applied to the top-level TopologyElement.

If the Online/Offline model is supported (see 7.3), the lock always applies to both the online and the offline version.

When locking a Network, the lock applies to the Network and all connected TopologyElements. If any of the connected TopologyElements provides access to a sub-ordinate Network (like a gateway), the sub-ordinate Network and its connected TopologyElements are locked as well.

The LockingServicesType provides the Methods needed to lock or unlock. Figure 34 shows the LockingServicesType definition. It is formally defined in Table 54.

Figure 34 – LockingServicesType

Table 54 – LockingServicesType definition

Attribute	Value
BrowseName	LockingServicesType
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
Subtype of the BaseObjectType defined in OPC 10000-5.
HasComponent	Method	InitLock			Mandatory
HasComponent	Method	RenewLock			Mandatory
HasComponent	Method	ExitLock			Mandatory
HasComponent	Method	BreakLock			Mandatory
HasProperty	Variable	0:DefaultInstanceBrowseName	QualifiedName	PropertyType
HasProperty	Variable	Locked	Boolean	PropertyType	Mandatory
HasProperty	Variable	LockingClient	String	PropertyType	Mandatory
HasProperty	Variable	LockingUser	String	PropertyType	Mandatory
HasProperty	Variable	RemainingLockTime	Duration	PropertyType	Mandatory

The StatusCode Bad_MethodInvalid shall be returned from the Call Service for Objects where locking is not supported. Bad_UserAccessDenied shall be returned if the Client User does not have the permission to call the Methods.

The DefaultInstanceBrowseName Property – defined in OPC 10000-3 – is used to specify the recommended BrowseName for instances of the LockingServicesType. Its Value is defined in Table 55.

Table 55 – LockingServicesType Additional Variable Attributes

Source Path	Value	Description
0:DefaultInstanceBrowseName	Lock

The following LockingServices Properties offer lock-status information.

Locked when True indicates that this element has been locked by some Client and that no or just limited access is available for other Clients.

LockingClient contains the ApplicationUri of the Client as provided in the CreateSession Service call (see OPC 10000-4).

LockingUser contains the identity of the user. It is obtained directly or indirectly from the UserIdentityToken passed by the Client in the ActivateSession Service call (see OPC 10000-4).

RemainingLockTime denotes the remaining time in milliseconds after which the lock will automatically be timed out by the Server. This time is based upon MaxInactiveLockTime (see 8.3.4).

The support of LockingServices for an Object is declared by aggregating an instance of the LockingServicesType as illustrated in Figure 35.

Figure 35 – LockingServices

This Object is used as container for the LockingServices Methods and Properties and should have the BrowseName Lock. HasComponent or HasAddIn are used to reference from a TopologyElement (for example, a Device) to its “LockingServices” Object.

The LockingServiceType and each instance may share the same Methods. All Properties are distinct.

The MaxInactiveLockTime Property shall be added to the ServerCapabilities Object (see OPC 10000-5).

It contains a Server-specific period of time in milliseconds until which the Server will revoke the lock. The Server will initiate a timer based on this time as part of processing the InitLock request. Calling the RenewLock Method as well as other Service calls from the Client for the locked element shall reset the timer. The lock will never be disabled during execution of a Service that requires a lock.

Inactivity for MaxInactiveLockTime will trigger a timeout. As a result the Server will release the lock.

A timeout shall not cancel any already executing Services like Write.

The MaxInactiveLockTime Property is formally defined in Table 56.

Table 56 – MaxInactiveLockTime Property definition

References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	MaxInactiveLockTime	Duration	PropertyType	Mandatory

InitLock restricts access for other Clients.

A call of this Method for an element that is already locked will be rejected. This may also be due to an implicit lock created by the Server. If InitLock is requested for a Network, it will be rejected if any of the Devices connected to this Network or any sub-ordinate Network including their connected Devices is already locked.

While locked, requests from other Clients to modify the locked element (e.g., writing to Parameters, modifying the topology, or invoking Methods) will be rejected. However, requests to read or navigate will typically work. Servers may choose to implement an exclusive locking where other Clients have no access at all (e.g. in cases where even read operations require certain settings in a TopologyElement).

The lock is removed when ExitLock is called. It is automatically removed when the Session ends. This is typically the case when the connection to the Client breaks and the Session times out. Servers shall also maintain an automatic unlock if Clients do not access the locked element for a certain time (see 8.3.4).

The signature of this Method is specified below. Table 57 and Table 58 specify the arguments and AddressSpace representation, respectively.

Signature

InitLock(

[in] String Context,

[out] Int32 InitLockStatus);

Table 57 – InitLock Method Arguments

Argument	Description
Context	A string used to provide context information about the current activity going on in the Client.
InitLockStatus	0 – OK -1 – E_AlreadyLocked – the element is already locked -2 – E_Invalid – the element cannot be locked

Table 58 – InitLock Method AddressSpace definition

Attribute	Value
BrowseName	InitLock
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

ExitLock removes the lock. This Method may only be called from the same Session from which InitLock had been called.

The signature of this Method is specified below. Table 59 and Table 60 specify the arguments and AddressSpace representation, respectively.

Signature

ExitLock(

[out] Int32 ExitLockStatus);

Table 59 – ExitLock Method Arguments

Argument	Description
ExitLockStatus	0 – OK -1 – E_NotLocked – the Object is not locked

Table 60 – ExitLock Method AddressSpace definition

Attribute	Value
BrowseName	ExitLock
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

The lock timer is automatically renewed whenever the Client initiates a request for the locked element or while Nodes of the locked element are subscribed to. RenewLock is used to reset the lock timer to the value of the MaxInactiveLockTime Property and prevent the Server from automatically aborting the lock. This Method may only be called from the same Session from which InitLock had been called.

The signature of this Method is specified below. Table 61 and Table 62 specify the arguments and AddressSpace representation, respectively.

Signature

RenewLock(

[out] Int32 RenewLockStatus);

Table 61 – RenewLock Method Arguments

Argument	Description
RenewLockStatus	0 – OK -1 – E_NotLocked – the Object is not locked

Table 62 – RenewLock Method AddressSpace definition

Attribute	Value
BrowseName	RenewLock
References	NodeClass	BrowseName		DataType	TypeDefinition	ModellingRule
HasProperty	Variable	OutputArguments	Argument[]		PropertyType	Mandatory

BreakLock allows a Client (with sufficiently high user rights) to break the lock held by another Client. This Method will typically be available only to users with administrator privileges. BreakLock should be used with care as the locked element may be in an inconsistent state.

The signature of this Method is specified below. Table 63 and Table 64 specify the arguments and AddressSpace representation, respectively.

Signature

BreakLock(

[out] Int32 BreakLockStatus);

Table 63 – BreakLock Method Arguments

Argument	Description
BreakLockStatus	0 – OK -1 – E_NotLocked – the Object is not locked

Table 64 – BreakLock Method AddressSpace definition

Attribute	Value
BrowseName	BreakLock
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory