READLOCK |
Readlock is used to perform read operations on a table with an access key or temporary index, locking the record read.
Readlock [ class ] [ key ] read_mode
[ value_key ]
[ With lockwait = exp_times ]
|
Element |
Description |
Restrictions |
||||||||
|
key |
Indicates the key for a file
in one of the following forms forms: |
The key must be defined in an Order By clause or in the table parameters |
||||||||
|
exp_ind |
Integer expression of the number of parts of the keys used. The whole key is used by default. |
0 <=exp_ind <= number of components of the key (8 max). |
||||||||
|
||||||||||
|
value_key |
List of expressions separated by ';' matching the values of the sub-keys. |
Value compatible with type of sub-key |
||||||||
|
exp_times |
Numerical expression giving the number of seconds Adonix will try to lock the record. |
exp_times >= 0 |
||||||||
# Read and lock loop for the first record in
the
# table [CLI] as long as it is not
unlocked.
Trbegin CLEINT [CLI]
Repeat : Readlock [CLI]CLE First With lockwait = 1 : Until fstat = 0
Commit
# Attempt to read and lock a record from the
# STK file until it is unlocked. CLE
consists of
# a numerical element and an
alphanumerical element.
Repeat Readlock [STK]CLE =
[L]NUMPRO;[F:MAG]MAGAS Until fstat = 0
# ... continuation of routine
Unlock [STK]
# Read and lock the last record in the
sequence of the
# key CLE2 (a date element, an
alphanumeric element, an integer element),
# for which there is a partial key less
than the given values.
# The file read is the default file
Readlock CLE2(2) <
[29/05/1959]; "BOPP"
Readlock is used to read a table using the various modes listed in the above table, locking the record read.
If no key values are given for modes that require one ( '<', '>', '<=', '>=', '=' ), the current value for class [F] variables for the file is used.
It is important to perform an Unlock on the file as soon as possible in order not to block other users and to release system locks used by the Readlock.
If there is no With lockwait clause, Readlock tries to lock the record for a number of seconds defined by the Adonix system variable [S]lockwait. Otherwise Readlock tries to do it for the number of seconds given, without modifying the value of [S]lockwait. If the number is equal to zero, one test will be performed. If it is negative, the lock will be attempted without a time limit.
The keys that may be used in Readlock are:
·
when scanning a table using the abbreviation defined in the File
command (explicitly or implicitly):
- the key defined by the Order By clause of the File or Filter;
- otherwise, one of the keys defined in the file parameters;
·
when scanning a table with the link abbreviation (Link):
- the key defined by the Order By clause of the Link or Filter;
- otherwise the key defined by the Order By clause of the File of the main file
(if there is one);
- otherwise one of the keys defined in the parameters of the main file.
When the link abbreviation is used (defined during a previous Link) in a Readlock, Adonix tries to read a record from the main file according to the key given, then a record in each file linked according to the key and the read mode given in Link.
The file abbreviation or key name may be omitted from the Readlock syntax:
· in the former case, the file used is the first from the list of default tables;
· in the second case, the key used is the current one. Its number is given by the Adonix system variable currind. The default read mode is Curr.
The fstat variable indicates the progress of the operations.
|
fstat |
Code |
Read |
Lock |
Explanation |
|
0 |
|
Yes |
Yes |
Read and lock correct. |
|
1 |
ERLOCK |
Yes |
No |
The record read was already locked. |
|
2 |
ERECIND |
Yes |
Yes |
In read mode <= or >= , indicates that read and lock have taken place, but the key found is < or > the set value. |
|
4 |
ERDEBF |
NO |
|
Start / End of file (Next, Prev, First, Last). |
|
5 |
ERPALEC |
NO |
|
No record matches the values requested (>=, >,=,<,<=). |
When the read operation has succeeded (that is, if fstat is null or may be set to ERLOCK or ERECIND), the class [F] variables for the file contain the values of the record read. This record becomes the current record of the file. Otherwise, nothing is modified.
The records are unlocked by:
· Unlock on the file concerned;
· Close of the file concerned;
· an end of transaction (whether by Commit or Rollback);
· the end of the routine that has locked.
If a transaction is in progress, however, the locks are only removed at the end of the transaction.
A successful Readlock instruction involves the system allocating a lock (without considering system optimisations) to allow exclusive access to a record (this also happens with File and Lock on a table). Any database uses its own locks, and the maximum number of these is one of the database parameters. This limit may need to be increased (contact your system engineer for this). If it is reached, an Adonix error no. 43 (FISLOCK) will be generated.
The locks are only removed at the end of the transaction, so it is essential to write transactions as short as possible to prevent any "blockage". Outside a transaction, Unlock will be used as soon possible to avoid this problem.
Once there are several records to read in a table, rather than Readlock the For instruction is preferable, with the With Lock option, which is simpler to write, since among other things, it performs the Readlock Next instructions necessary internally and speeds up access when working on an Oracle database, since Readlock has the same optimisation problems as Read. Refer to the documentation for this instruction.
|
Error |
Description |
|
MODIN (22) |
Read mode incorrect |
|
ERINDI (8) |
The number of values given, or the index indicated, exceeds the number of elements in the key. |
|
PACLE (21) |
The key does not exist on this file. |
|
ERCLAS (7) |
The file class does not exist (file not open). |
|
FISLOCK (43) |
No more locks available. |
UNLOCK - READ - FILE - LINK - REWRITE - LOOK - TRBEGIN - FSTAT - LOCKWAIT - UPDATE - FILTER - FOR
|
|