fwGeneral  8.4.0
fwDPELock Manual

Files

file  fwDPELock.ctl
 The library to handle DPE locks.This library contains a set of functions that handle DPE Locks: lock, unlock, check the state of locking, as well as a lock-monitor that guards that the locked datapoints will not remain locked unnecessarily.
 

Functions

string _fwDPELock_getLockConfig (string dpeWithConfig)
 
bool fwDPELock_isLocked (string dpeWithConfig)
 
bool fwDPELock_getLocked (string dpeWithConfig, dyn_string &lockDetails, dyn_string &exceptionInfo)
 
bool fwDPELock_tryLock (string dpeWithConfig, dyn_string &exceptionInfo, int lockTimeout=1, int lockLifetime=5)
 
void fwDPELock_unlock (string dpeWithConfig, dyn_string &exceptionInfo, bool force=false)
 

Detailed Description

Function Documentation

string _fwDPELock_getLockConfig ( string  dpeWithConfig)

Finds the lock config element

The function looks up the lock config element for a specified DPE, and optionally a config. It properly recognizes the cases where the system is specified without a config, and a config specified without a system

Use: internally by other functions in fwDPELock.

Parameters
dpeWithConfig(input): the DP Element, optionally with a config, for which the lock config element is looked up. If config is not specified, the _original is assumed.
Returns
the name of the lock config element
Exceptions
exceptionswhen DPE or config do not exist
bool fwDPELock_isLocked ( string  dpeWithConfig)

Checks if DPElement (optionally with config) is locked, with handling of errors through exceptions; Note that it does not check if the owner of the lock is the current manager.

Parameters
dpeWithConfig(input) the DP Element (optionally with a config) being checked
Returns
true is the DPE is locked, false otherwise;
Exceptions
exceptionsif dpeWithConfig is invalid, or if the state of locking could not be determined
bool fwDPELock_getLocked ( string  dpeWithConfig,
dyn_string &  lockDetails,
dyn_string &  exceptionInfo 
)

Checks the state of the lock on a given DPElement

the function checks whether the DPElement (optionally with a config) is locked, and if it is, then it returns the details of who owns the lock.

Parameters
dpeWithConfig: the name of the dp element, optionally with the config name
lockDetailsif the config is locked, the details of the lock are returned here lockDetails[fwDPELock_LOCK_MANAGER_DETAIL] - The name of the manager that has control of the config lockDetails[fwDPELock_LOCK_USER_NAME] - The name of the user who has control of the config lockDetails[fwDPELock_LOCK_MANAGER_TYPE] - The type of manager that has control of the config lockDetails[fwDPELock_LOCK_MANAGER_NUMBER] - Manager number of manager that has contol of the config lockDetails[fwDPELock_LOCK_MANAGER_SYSTEM] - System name of manager that has contol of the config lockDetails[fwDPELock_LOCK_MANAGER_HOST] - The host of the manager that has control of the config lockDetails[fwDPELock_LOCK_MANAGER_REPLICA] - The redundant system replica number of the manager that has control of the config lockDetails[fwDPELock_LOCK_MANAGER_MANID] - The ManId (internal WinCC OA id) of the manager that has control of the config lockDetails[fwDPELock_LOCK_USER_ID] - User name of user who has control of the config lockDetails[fwDPELock_LOCK_TYPE] - Type of lock on the config
exceptionInfodetails of any errors are returned here
Returns
true if locked, false otherwise
Exceptions
:nothing; errors are handled through the exceptionInfo variable
bool fwDPELock_tryLock ( string  dpeWithConfig,
dyn_string &  exceptionInfo,
int  lockTimeout = 1,
int  lockLifetime = 5 
)

Try to acquire a lock on specified DPE, waiting for it to be free and assuring that it is unlocked

The function attempts to lock the specified DPElement (optionally, with specified config). In case the lock is held by other manager, it (optionally) retries for up to the lockTimeout seconds. The lock is (optionally) monitored with a timer mechanism: if it is not explicitely released within lockLifetime seconds, then the lock monitor will force-release it. This is particularly useful if the function is executed within child panels which may be closed before the corresponding unlock code is executed.

If the manager executing this code is already owning the lock, the function returns true, and the lock-monitoring timeout is reset.

In any case one should use the fwDPELock_unlockDPE to release the lock acquired by this function.

Parameters
dpeWithConfig(input) the DP Element (may also include the config) to be locked; if no config is specified, then the _original config will be locked
exceptionInfo(output) standard exception-handling variable
lockTimeout(input) the time (in seconds) for which the function will wait for the lock, default 1 second;
  • 0 - do not wait for lock at all (will exit with failure if the DPE is already locked)
  • <0 - wait with no limit until the lock is obtained.
lockLifetime(input) the maximum time for which the lock will be kept (default 5 seconds); if the lock is not released within the lockLifeTime, then it will be force-unlocked by the lock manager. Specifying the value of zero will disable the lock-monitoring mechanism for this call.
Returns
true if the lock was obtained successfully (or if this manager was already holding the lock) false if the lock was not obtained (because it was locked and timed out, or because of errors)
Exceptions
nothing- all errors handled with the exceptionInfo variable
void fwDPELock_unlock ( string  dpeWithConfig,
dyn_string &  exceptionInfo,
bool  force = false 
)

Unlocks the specified DP Element

This function allows to unlock the specified DP Element (optionally, with a config). It is possible to force-unlock a locked DPE, even if it was locked by another manager.

Parameters
dpeWithConfig(input) the DP Element (optionally with config) to be unlocked
exceptionInfo(output) standard exception-handling variable
force(input) if true, it allows to unlock the DPEs locked by other managers; default is false (ie. only allow to unlock own locks)
Exceptions
nothing- all exceptions handled through the exceptionInfo variable