fwGeneral
8.4.1
|
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) |
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.
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. |
exceptions | when 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.
dpeWithConfig | (input) the DP Element (optionally with a config) being checked |
exceptions | if 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.
dpeWithConfig | : the name of the dp element, optionally with the config name |
lockDetails | if 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 |
exceptionInfo | details of any errors are returned here |
: | 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.
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;
|
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. |
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.
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) |
nothing | - all exceptions handled through the exceptionInfo variable |