1 10/04/85  set_lock_
 2 
 3 The set_lock_ subroutine enables cooperating processes to coordinate
 4 their use of shared resources.
 5 
 6 
 7 Entry points in set_lock_:
 8    (List is generated by the help command)
 9 
10 
11 :Entry: lock:  10/04/85  set_lock_$lock
12 
13 
14 Function:  This entry point attempts to place the lock identifier of
15 the calling process in the given lock word.
16 
17 
18 Usage:
19 declare set_lock_$lock entry (bit(36) aligned, fixed bin,
20      fixed bin(35));
21 call set_lock_$lock (lock_word, wait_time, code);
22 
23 
24 Arguments:
25 lock_word
26    is the word to be locked.  (Input/Output)
27 wait_time
28    indicates the length of real time, in seconds, that the
29    set_lock_$lock entry point should wait for a validly locked lock
30    word to be unlocked before returning unsuccessfully.  (Input) A
31    value of -1 indicates no time limit.
32 
33 
34 code
35    is a standard status code.  (Output) It can be one of the following:
36    error_table_$invalid_lock_reset
37         indicates that the lock word was successfully locked, but the
38         lock word previously contained an invalid lock identifier that
39         was overwritten
40    error_table_$locked_by_this_process
41         indicates that the lock word already contained the lock
42         identifier of the calling process and was not modified
43    error_table_$lock_wait_time_exceeded
44         indicates that the lock word contained a valid lock identifier
45         of another process and could not be locked in the given time
46         limit
47 
48 
49    error_table_$no_w_permission
50         indicates that calling process does not have proper write
51         permission to lock_word
52 
53 
54 Notes:
55 It is suggested that set_lock_$lock be called as follows for
56 applications where efficiency is important:
57 
58    if ^stacq (lock_word, static_var_initialized_to_lock_id, ""b)
59       then call set_lock_$lock (lock_word, wait_time, code);
60       else code = 0;
61 
62 
63 :Entry: unlock:  10/04/85  set_lock_$unlock
64 
65 
66 Function:  This entry point attempts to reset a given lock word to "0"b
67 and is successful if the lock word contained the lock identifier of the
68 calling process.
69 
70 
71 Usage:
72 declare set_lock_$unlock entry (bit(36) aligned, fixed bin (35));
73 call set_lock_$unlock (lock_word, code);
74 
75 
76 Arguments:
77 lock_word
78    is the lock word to be reset.  (Input/Output)
79 code
80    is a standard status code.  (Output)
81    error_table_$lock_not_locked
82         indicates that the lock was not locked
83    error_table_$locked_by_other_process
84         indicates that the lock was not locked by this process and
85         therefore was not unlocked
86    error_table_$no_w_permission
87         indicates that calling process does not have proper write
88         permission to lock_word
89 
90 
91 Notes:
92 It is suggested that set_lock_$unlock be called as follows for
93 applications where efficiency is important:
94 
95    if ^stacq (lock_word, ""b, static_var_initialized_to_lock_id)
96       then call set_lock_$unlock (lock_word, code);
97       else code = 0;