API Help
EPLAN API / User Guide / API DataModel / Locking
In This Topic
    Locking
    In This Topic

    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'?

     

    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:

    C#
    Copy Code
    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:

    C#
    Copy Code
    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)

    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. 

     

    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.