This function locks an HDS object for use by the current thread. An object can be locked for read-only access or read-write access. Multiple threads can lock an object simultaneously for read-only access, but only one thread can lock an object for read-write access at any one time. Use of any HDS function that may modify the object will fail with an error unless the thread has locked the object for read-write access. Use of an HDS function that cannot modify the object will fail with an error unless the thread has locked the object (in this case the lock can be either for read-only or read-write access).

If " readonly" is zero (indicating the current thread wants to modify the object), this function will report an error if any other thread currently has a lock (read-only or read-write) on the object.

If " readonly" is non-zero (indicating the current thread wants read-only access to the object), this function will report an error only if another thread currently has a read-write lock on the object.

If the object is a structure, each component object will have its own lock, which is independent of the lock on the parent object. A component object and its parent can be locked by different threads. However, as a convenience function this function allows all component objects to be locked in addition to the supplied object (see " recurs" ).

The current thread must unlock the object using datUnlock before it can be locked for use by another thread. All objects are initially locked by the current thread when they are created. The type of access available to the object (" Read" , " Write" or " Update" ) determines the type of the initial lock. For pre-existing objects, this is determined by the access mode specified when calling hdsOpen. For new and temporary objects, the initial lock is always a read-write lock.

datLock( HDSLoc $\ast$locator, int recurs, int readonly, int $\ast$status );

locator = HDSLoc $\ast$ (Given)

recurs = int (Given)

readonly = int (Given)

status = int$\ast$ (Given and Returned)

• An error will be reported if the supplied object is currently locked by another thread. If " recurs" is non-zero, an error is also reported if any component objects contained within the supplied object are locked by other threads.

• The majority of HDS functions will report an error if the object supplied to the function has not been locked for use by the calling thread. The exceptions are the functions that manage these locks - datLock, datUnlock and datLocked.

• Attempting to lock an object that is already locked by the current thread will change the type of lock (read-only or read-write) if the lock types differ, but will otherwise have no effect.