READLOCK

Contents


Readlock is used to perform read operations on a table with an access key or temporary index, locking the record read.

 

Syntaxes

   Readlock [ class ] [ key ] read_mode [ value_key ]
   [ With lockwait = exp_times ]

 

Parameters

Element

Description

Restrictions

key

Indicates the key for a file in one of the following forms forms:
nom_de_variable
nom_de_variable '(' exp_ind ')'

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).

read_mode

One of the following key-words, or one of the following operators:

key-word

operator

Read mode used

First
Last
Curr
Prev
Next






>=
>
=
<
<=

1st record
Last record
Current record
Previous record
Next record
Key >= value_key
Key > value_key
Key = value_key
Key < value_key
Key <= value_key

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

 

Examples

   # 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"

 

Description and comments

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.

 

Comment

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.

 

Associated errors

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.

 

Associated keywords

UNLOCK - READ - FILE - LINK - REWRITE - LOOK - TRBEGIN - FSTAT - LOCKWAIT - UPDATE - FILTER - FOR


CONTENTS


Copyright © Sage 1999 - 2007