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.
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 |