Subroutine:    GDS_LOCK

Purpose:       Obtain exclusive access to a set.

Category:      GDS

File:          gdsd_basic.c

Author:        J.P. Terlouw

Use:           CALL GDS_LOCK( SET,           Input     CHARACTER*(*)
                              ERROR )        Output    INTEGER
                              
               SET         Name or handle of set.
               ERROR       Error return code.

Description:   GDS_LOCK gives a task exclusive access to a set.
               The task should have write permission on the set.
               This routine should be used when a task makes a number of
               related modifications to a set which should all be completed 
               before an other task may access that set.
               When the task is finished with these modifications, it should
               release the lock by calling GDS_UNLOCK.
                              
               It is possible to 'nest' calls to GDS_LOCK and GDS_UNLOCK.
               In this case the set remains locked until all calls to GDS_LOCK
               have been cancelled by corresponding calls to GDS_UNLOCK.

               In order to prevent deadlocks, the GDS server allows only one
               client at a time to have locks. If there is already such a
               client, any requests for a lock will be delayed until all
               locks are released.

               If a task does not want to wait for any lock, it can call
               GDST_IMMEDIATE to allow the locked status to be reported.

Related documents: gds_unlock.dc2, gdst_immediate.dc2.

Updates:       Mar  3, 1994: JPT Document created.