In computer science, locking is a synchronization mechanism for enforcing limits on access to a resource in an environment where there are many threads of execution (multiple-user environment). Locks are one way of enforcing concurrency control policies. 

In EPLAN API, the term 'locking an object' means to set an object reference to a state, where it can be edited by the current user/process, whereas no other user/process can edit it. In general, the user can always get an object in an un-locked/read-only way, even if it is locked by another user. If even this read-only access is not possible, we speak of an 'exclusive lock'. Exclusive locking is necessary, if e.g. the structure of an EPLAN project is changed or if a project is copied, renamed or a backup is done. 

Please take into account that API locking only wraps P8 locking techniques. For further details about this functionality please refer to EPLAN Help->Editing and Managing Project->Multi-user Operation chapter of P8 help. 

What can be locked 'automatically'?

• All project data - this can be done by getting Project from SelectionSet (in addins) or when opening it by ProjectManager. This depends on property LockProjectByDefault (by default set on true). Also getting the selected project by method HeServices.SelectionSet.GetCurrentProject locks the project completely (and its data). Please take into account that read-only access is still possible from other P8 instances.
• Exclusive project locking - this is done by switching USER.TrDMProject.OperationMode.OpenProjectsExclusive setting on true before opening it. As mentioned above, some project-wide operations need such an exclusive lock of a project where it can be used by only 1 P8 instance.
• Selected elements - this is possible by setting property SelectionSet.LockSelectionByDefault on true. By default the option is enabled (set on true), so when getting selected elements of a project, they can be changed in API without setting the property.

SafetyPoint

SafetyPoint class provides automatic locking of DataModel objects. The mechanism is enabled since creation and until disposal of a SafetyPoint object, so the recommended way is to use it with using keyword:

var project = new ProjectManager {LockProjectByDefault = false}.OpenProject(@"$(MD_PROJECTS)\EPLAN-DEMO.elk");
//view placement '8' (on page =EB3+ETM/4)
ViewPlacement viewPlacement8 = project
.Pages[42]
.AllFirstLevelPlacements
.OfType<ViewPlacement>()
.FirstOrDefault(item => item.Properties.DMG_VIEWPLACEMENT_DESIGNATION.ToString() == "8");
using (SafetyPoint safetyPoint = SafetyPoint.Create())
{               
    Console.WriteLine(viewPlacement8.IsLocked);     //false
    viewPlacement8.Scale = 44.44;                   //set another scale
    Console.WriteLine(viewPlacement8.IsLocked);     //true                  
    safetyPoint.Commit();                           //necessary, otherwise changes are rolled-back
}
Console.WriteLine(viewPlacement8.IsLocked);         //again false

 Automatic means that they are locked internally before any change and unlocked after disposing SafetyPoint. This way is recommended in case of necessity to lock as little as possible and is not clear which objects need to be locked to perform a change. After the SafetyPoint block, please call Commit method, otherwise the changes are rolled-back.

What is a LockingStep?

LockingStep is an object for automatically unlocking API resources (as Projects, Functions, etc). There are 2 ways of creating this object:

• Explicit. Must be done in modeless dialog boxes and in offline API applications:

using(LockingStep oLockingStep = new LockingStep())
{
   ....
}

When there is necessary access to some resources and the LockingStep is not created, an exception will be thrown (NoLockingStepException)

• Actions and scripts by the P8 framework

There however is no Unlock method in any DataModel class. The LockingStep class remembers all locks set during its lifespan and releases them when the LockingStep is being disposed. This guarantees that objects are released, even if an exception was thrown inside the block. 

In rare cases however it may be necessary to switch off creating LockingStep (manually or automatically). This can be done by the methods PauseManualLock() and ResumeManualLock() of the LockingVector class. Please use them only in exceptional cases, i.e. when there is necessary to 'manually' decide what to lock instead of relying on P8 framework (see bellow). 

Manual locking mode

Apart from automatic locking mechanism there is also possible to call locking methods directly on required objects. This low-level type of locking can be used concurrently with 'automatic' one or as the only locking. 

• Locking single StorableObject. This is done by calling LockObject on required object. Please take into account that only properties directly connected with objects can be locked this way (like internal/ normal properties, sub-Functions or sub-Placements are excluded). 

• Locking all placements of a Page in exclusive mode. This can be done by calling Page::LockAllObjects. Please consider that it is different than calling Page::LockObject, where only properties of a Page are locked. 

• Locking all objects of a project. This can be done by Project::LockAllObjects. 

• Locking all objects of a device. This is done by Function::LockDevice. Calling the method also locks all Functions placed on the same page as Functions of a device. 

Guideline to Locking of DataModel objects

If you don't need to mind multiple-user issues, e.g. if you create a new project with your own schematics generator, you should always lock the complete project. The project is locked by default, when it is opened or created using the respective methods (OpenProject(...) / CreateProject(...)) of the ProjectManager class in DataModel . Also getting the selected project by the method GetCurrentProject(...) in HeServices.SelectionSet class, will lock the project completely. 

In case you need to consider other users, or processes working on the same project, please lock as little of the project data as possible. To do this you should first get, open, or create the project in an un-locked way. This can be done by setting the LockProjectByDefault property of a ProjectManager or the SelectionSet object to false. Having this not-locked project object you just lock the object (e.g. Page) you want to change. Also mind, that the locks are only released when disposing the respective LockingSteps, so set as few as possible locks in one LockingStep. 

Differences between Add-Ins and offline API 

The main difference between Locking in Add-Ins and offline API applications is that the Execute(...) method of the IEplAction interface, is already surrounded by a Locking step, while the API programmer needs to implement the LockingStep(s) in an offline application by himself. 

API Verifications 

Methods of verification which are called by EPLAN framework are not surrounded by a Locking step. If it is necessary then user needs to implement it by himself. Please have in mind that creating a Locking step inside verification method has a big influence on performance of whole check. This is why this should be done as little as possible. 

Locking in Service methods (HeServices/Actions) 

All service functionality, to which you pass a project resource as a string parameter, will always automatically care for locking/unlocking said resource. If the locking is not possible, due to multiple-user issues, an exception will be thrown. This applies to all command line actions, which only have string parameters. HeServices classes most of the time have method overloads with both string-based and object passed parameters. If you pass an object to the method, you need to take care for the locking. 

Determining, which users currently have the project open 

In order to find out, which users currently work on the project, the Project class provides a CurrentUsers property, which returns an array of UserInfo structures of the users accessing the project.