LOCK

Contents


Lock is used to lock a symbol or a file.

 

Syntax

   SYNTAX 1

   Lock list_class [ With lokwait = exp_num ]

   SYNTAX 2

   Lock list_symb [ With lokwait = exp_num ]

 

Parameters

Element

Description

Restrictions

list_class

List ofclasses to be locked, separated by the character ','.

None.

class

class: to lock the whole of a table

class indicates the abbreviation for an open table.

list_symb

List ofsymb to be locked, separated by the character ','.

None.

symb

to lock a symbol indicated in the form:
symbol [From [server@] appli]
'='expr_c [From [server@] appli]

None

symbol

nom_de_variable.

None.

expr_c

Alphanumeric expression whose result is a nom_de_variable.

None.

server

name of a table server

None.

application

nom_de_variable.

None.

expr_num

Numerical expression giving the number of seconds for testing

-2^31 -1 < n >2^31

 

Examples

   # Locking a symbol linked to the file and the current key.
     SYMBOLE = "ABV"+num$([F:ABV]NOMCLE)
    
Lock = SYMBOLE With lockwait = 0
     If [S]fstat : Errbox "Record locked": Endif

   # Locking 3 files before starting
     Lock [ART], [CLI], [REP]
     If [S]fstat : Errbox "Files already locked": Endif

# Check there is no other interface operational
# Exclusive FUNSTOACC routine
CTL_OK = 1
SYMBOLE = "FUNSTOACC"
Lock =SYMBOLE With lockwait = 0
If fstat
    CTL_OK = 0
    If GSERVEUR
    # "Accouting interface already operational"
    ERR_TRA = mess(270,197,1)
    Call ECR_TRACE(ERR_TRA,1) From GESECRAN
    Else
    Call ERREUR(mess(270,197,1)) From GESECRAN
Endif
Goto FIN_TRT
Endif

# Incrementation of the exports counter
# contained in the global variable EXPORT
If [M:EXP2]CHRONO=2
    Lock EXPORT
    If fstat
        # Modification in progress on another station
        Call ECR_TRACE(mess(30,100,1),1) From GESECRAN
        Return
    Endif
...
Endif

# Consistency between the Lock and Unlock is required. There are two ways to write: #either
SYMBOLE = "FUNSTOACC"
Lock =SYMBOLE With lockwait = 0
...
Unlock =SYMBOLE

# or
Lock FUNSTOACC With lockwait = 0
...
Unlock FUNSTOACC

 

Description and comments

The instruction Lock is used to lock tables globally, or to lock symbols. When a symbol is locked, it may not be locked by another user at the same time. This means that access to a routine, a shared variable (counter), etc. may be controlled, for example. In the event of failure, Lock retries for as many seconds remaining according to the variable [S]lockwait. It is important to perform an Unlock on tables or symbols, when they no longer need to be locked, so that they are not blocked to other users wishing to access them.

In the event of failure after the allocated time, the Adonix system variable fstat is set to 1. If the locks have been applied, fstat is equal to 0.

The syntax using "With lockwait = " is used to assign [S]lockwait at any time, with the following value. After this, [S]lockwait resumes its initial value.

When an attempt is made to lock several OBJects in one Lockcommand, all OBJects are fully locked; if one of the locks cannot be applied, all of the OBJects are released and fstat is set to 1.

 

Comments

The global locking/unlocking mechanism for several OBJects is used to avoid "fatal embraces" (interlocking of two programmes trying to lock several identical OBJects at the same time, but not in the same order). A programmer will, if forewarned, be able to avoid this kind of situation (the figure written before each Lock instruction defines the order of execution):

PROGRAMME A

PROGRAMME B

1 Lock AA 
3
Lock BB

wait since BB is locked by B

2 Lock BB
4
Lock AA

wait since AA is locked by A

The instruction Lock is used to lock a file globally; a record is only locked with the Readlock instruction or by a For loop with the option With Lock.

The instruction "Lock file" will fail on a station (fstat equals 1) if the same "Lock file" or a record from this file has already been
locked from another station. When a file is locked with the
Lockinstruction, all the record locks requested by other stations will fail.

A symbol is an identifier that can be locked with Lock or unlocked with Unlock; these operations are the only ones that can be performed on a symbol. A symbol is not declared (it is not a variable). When this mechanism is used to control access to a counter for example, a symbol with the same name as the counter is normally chosen; this does not mean that the counter is locked.

These symbols correspond to records in a special table whose name is given by the variable [S]adxtlk. This table can be set for each application in a parameter. In particular, it may be helpful to increase the length of the LCKSYM zone of this table, setting the maximum number of characters in the symbol name. Its shortcut may also be changed if necessary. These are, a priori, the only safe modifications to be made in this table handled automatically by Adonix.

A symbol from another application may be locked. The server on which it is located must be specified if working in client-server mode and if not on the current server.
Since these symbols belong to Adonix, they cannot therefore provide protection against the use of tables by other applications.

To remove a lock from a file, records or a symbol, the Unlock instruction is used, with the system locks that may be used for Lock being released. Unlock will only be effective at the end of the transaction, if necessary, however.

A lock on a file is automatically released when the file is closed, as is always the case at the end of a transaction.
Rollback and Commit cancel all the locks placed on files, as well as locks on symbols, but only those applied since the start of the transaction (Trbegin).

For an entire database, the number of locks is a parameter of the database. If this resource is used up an Adonix error n43 (FISLOCK) will be generated.

When symbols are locked on an application other than the current one, the Unlock instruction on one symbol removes all the locks applied in this application.

It is not possible to use the link abbreviation to lock a table (this abbreviation exists if links have been defined on this file with the Link instruction).

A symbol may be locked outside a transaction. But in this case, Adonix will itself run a transaction, since it involves a write to a table.

 

Associated errors

Error

Description

ERCLAS ( 7)

The file abbreviation given does not match a currently opened file.

ERMODE (10)

expr_c is not alphanumeric

FISLOCK(43)

No more locks available.

 

Associated key words

UNLOCK - READLOCK - FOR - FSTAT - TRBEGIN - ROLLBACK - COMMIT - ADXTLK


CONTENTS


Copyright © Sage 1999 - 2007