Lock(Filename)

Lock is a crucial function if you are in a multi-user environment.
It allows you to make sure that one person, and one person only accesses a given file at any time.
The main example is a web counter where you want to make sure that all hits are taken into account. If you don't lock a file before reading and modifying it you are at risk to have a second process read an empty file insted of the modified value you intended to write. In the case of a web counter, that means that the counter can be reset to 0 unexpectedly. (And I've seen it happen, guys!)
Have a look at the counter in the examples, for a real life programing sample.
Note that locking a non existing file will result in the creation of that file, with a size of 0, if nothing is written to it. (with saveFile, apppendToFile, etc...)
Locked files are automatically unlocked at the end of your program. That means that a file cannot stay locked from one call to your aptilis program to the next, like when you call an aptilis program repeatedly at each stage of a web based data entry procedure using forms.

Lock does not work on network file types such as http: and ftp:. Indeed, you cannot lock a file residing on someone else's computer!

Lock is not blocking so that you can decide how long you may want to wait before you get a lock.
If you lock a file more than once (in the same programm) without unlocking it, then you need to call Unlock as many times as you've called Lock. This is in case you'd lock a file in a sub, then unlock it and expect it to be still locked after the sub has returned if you had locked it before the call.

Platform notes: Depending on your platform, the locking mechanism might work slightly differently. Under Unix, locking doesn't prevent the locked file to be written to or read from by another process (another program that runs at the same time). But locking prevents another locking, and that's what you must do to make sure you're doing everything right. Windows is stricter and will prevent any kind of access whatsoever. So unlike under Unix, calls to LoadFile, SaveFile, etc. will fail.
Locks work on file names. You have to be careful as under Unix, the same file can have different names, through the use of links. So if a lock unexpectedly fails, make sure the file is not already locked under another name.

Subs taking advantage/affected of the locking mechanism:
Databases: AppendRecord, LoadDatabase, SaveDatabase
General File subs: AppendToFile, DeleteFile, LoadFile, RenameFile, SaveFile
SaveGifBitmap and setFont are not affected by the locking mechanism, depending on your platform. See above for details.

Return Value:
0 if everything was OK.
-1 in case of error and the _errno variable contains more details about the error.

Example:

path = "myFile.txt" $

t = getTime()

// Let's say we will gladly want to wait 5 seconds
failed = 0
while lock(path$) = -1
if getTime() - t > 5
failed = 1
break
end if
end while


if failed = 0
n = loadFile(path$)
saveFile(path$, n + 1)
unlock(path$)
print("n=", n, "\n")
end if

45

See also: unlock.