{INCLUDE _LOGOS_C.HTM}

Item Locks

Setting locks in a web environement is conceptually a bit different from setting locks in a traditional terminal stream environment. Specifically, you application gets no indicatation if the user leaves, spawns multiple browsers, or executes pages in an unusual manner. This means the use of locks must compromise several behaviours in order to co-exist with the nature of the web.

PicLan-IP provides a utility function to allow applications to set standard item locks from within a web application. Theoretically, any application can use this utility subroutine, but only web applications should need it. There are several rules regarding locks that should be mentioned first.

Setting Standard Locks within Web Pages

It is premissible to use the READU types of statements to set item-locks during page execution provided that you guarantee that the lock will not be set when the page exits. This means that standard item-locks are perfectly acceptable for access control to shared data structures (such as alternate index files), but should not be used for program flow control. If you need to set a lock that lives from page to page, then you must use the PLW.ILOCK subroutine described below instead of directly setting item-locks with READU type statements.

You must also insure that you never release locks that your application did not set. The PicLan-IP Web Server thread processes typically run with several item-locks that are continually set. It is important that you application not release these locks with a general RELEASE statement.

Web Lock Concepts

Setting a lock within a web application involves the following steps:

On the web page where the lock is set:

Setting the lock
Saving the lock 'handle' in a hidden input field on the web page

On the web page where the data is to be updated:

Check to see if the lock is still valid.
If the lock is not valid, branch to an error page
Update the application's data files
Release the lock

The aspects of web locks that differ from standard item locks are:

Web locks can timeout. You get to specify the amount of time that a web lock is valid for.
Web locks have handles. You must save this handle from web page to web page in order to access it again. A web handle should be treated as a string that is guaranteed not to contain any dynamic array delimiters although it is usually just a number.
Your application must check to see if it still owns a lock
Your application must deal with the scenario of reaching an update operation when it does not own the lock

PLW.ILOCK(cmd,a1,a2,a3,res,r2)

This is the subroutine that is used to manipulate item-locks that are compatible with web applications. A single subroutine is used for three different calls:

CALL PLW.ILOCK('LOCK',file,item,timeout,res,r2)

This call will set a lock. Your program supplies file, item, and timeout values. file is the name of the file in which the lock resides. item is the item-id of the item to lock. timeout is the number of seconds that the lock will be held. After this period of time, the lock will be automatically released.

The results to this call are res, and r2. res contains a string:

OK - The lock was set correctly, r2 contains a 'handle' for the lock that must be used in future calls to refer to this lock.
LOCKED - The lock was not set because it is already set. r2 contains either the Pick process port number that holds the lock or the string WEB to indicate that another web application holds the lock.
ERROR - The lock was not set because of an error further described in r2.

CALL PLW.ILOCK('CHECK',handle,timeout,'',res,r2)

This call will check to see if you still 'own' a lock. Because locks time out, you should always check to see if the lock is still yours before updating any data. Your program supplies handle, and timeout. handle is the returned handle from a previous call to PLW.ILOCK('LOCK'...) and was presumably saved in a form's hidden input field, cookie, or other state area. timeout, is the number of additional seconds that you wish the lock held for. Be sure to set timeout to a large enough value for you to complete your update.

The results of this call are res, and r2. res contains a string:

OK - The lock is still held. r2 is returned null.
NOT LOCKED - You no longer own the lock. This occurs because either you released the lock, or it timed out.
ERROR - The lock was not queries because of an error further described in r2.

CALL PLW.ILOCK('UNLOCK',handle,'','',res,r2)

This call will release a lock that was previously set. Your program supplies handle which was previously returned in r2 from a previous call to PLW.ILOCK('LOCK'...).

The results of this call are res, and r2. res contains a string:

OK - The lock was released. r2 is returned null.
NOT LOCKED - You no longer own the lock. This occurs because either you released the lock, or it timed out.

ERROR

{INCLUDE _GEN_FTR.HTM}