datLocked

See if an object is locked

Description:

This function returns a value that indicates if the object specified by the supplied locator has been locked for use by one or more threads. A thread can lock an object either for read-only access or for read-write access. The lock management functions (datLock and datUnlock) will ensure that any thread that requests and is given a read-write lock will have exclusive access to the object - no other locks of either type will be issued to other threads until the first thread releases the read-write lock using datUnlock. If a thread requests and is given a read-only lock, the lock management functions may issue read-only locks to other threads, but it will also ensure that no other thread is granted a read-write lock until all read-only locks have been released.

Invocation

locked = datLocked( const HDSLoc locator, int recursive, int status );

Arguments

locator = const HDSLoc (Given)
A locator for the object to be checked.
recursive = int (Given)
If non-zero, then all descendants of the supplied object are also checked in the same way.
status = int (Given and Returned)
Pointer to global status.

Notes:

Returned function value

A value indicating the status of the supplied Object:

0: the supplied object is unlocked. If " recursive" is non-zero, then all descendant objects are also unlocked, and this is then the condition that must be met for the current thread to be able to lock the supplied object for read-write access using function datLock. This condition can be achieved by releasing any existing locks using datUnlock.

1: the supplied object is locked for reading and writing by the current thread. This is the condition that must be met for the current thread to be able to use the supplied object in any HDS function that might modify the object (except for the locking and unlocking functions - see below). If " recursive" is non-zero, then all descendant objects are also locked for reading and writing. This condition can be achieved by calling datLock.

2: the supplied object is locked for reading and writing by a different thread. An error will be reported if the current thread attempts to use the object in any other HDS function. If " recursive" is non-zero, then either the object itself or one of its descendant objects is locked for reading and writing.

3: the supplied object is locked read-only by the current thread (and maybe other threads as well). If " recursive" is non-zero, then all descendant objects are also locked read-only by the current thread. This is the condition that must be met for the current thread to be able to use the supplied object in any HDS function that cannot modify the object. An error will be reported if the current thread attempts to use the object in any HDS function that could modify the object. This condition can be achieved by calling datLock.

4: the supplied object is not locked by the current thread, but is locked read-only by one or more other threads. An error will be reported if the current thread attempts to use the object in any other HDS function. If " recursive" is non-zero, then all descendant objects are also locked read-only by one or more other threads.

5: Some complex mix of locked and unlocked descendants not covered by any of the above values.