********************************************************************** FTSC FIDONET TECHNICAL STANDARDS COMMITTEE ********************************************************************** Publication: FRL-1014 Revision: 1 Title: Hudson Message Base (HMB) locking semantics Authors: Andrew Milner Issue Date: 10 February 2005 Review Date: N/A ---------------------------------------------------------------------- Contents: 1. RALCK003.DOC ---------------------------------------------------------------------- Status of this document ----------------------- This document is a Fidonet Reference Library document (FRL). This document preserves the contents of RALCK003.DOC intact - see below for Copyright, etc. 1. RALCK003.DOC --------------- Name : RALCK003.DOC Rev : 003 Date : 29 Jan 1992 Subject : RemoteAccess Message database locking for multiuser applications. Author : Andrew Milner This document (C) Copyright 1991,1992 by Andrew Milner. It may be freely distributed and/or included in other publications in it's entire and unmodified form only. PURPOSE ------- The purpose of this document is to describe the locking technique that is used by RemoteAccess 1.11 to ensure the integrity of it's message database in a multi-user environment. Developers of third party software that requires access to the database files are strongly encouraged to implement the described locking scheme. The locking method is relatively simple; any competent developer should have no trouble implementing it. This document assumes that the reader knows how to call an interrupt with appropriate parameters, and read the values returned. LOCKING METHOD -------------- All message database files must be opened in DENYNONE mode. 1. Use the INT 21 5Ch function to lock a region of the MSGINFO.BBS file; This region starts at byte 407, and is 1 byte long. Locking a region beyond the physical file size is considered valid by SHARE, and ensures that other applications may access information contained in the file for read purposes while it is locked. If an error occurred, the carry flag is set and the error returned in AX: 01h = Invalid function number, means SHARE is not installed. How this is handled will vary - RemoteAccess disables all locking and proceeds with the update. (See note 5 below). 06h = Invalid handle 21h = Lock violation - this means that another application is performing an update. Keep trying to get the lock for 15 seconds, then abort the update with an error message if unsuccessful. 2. Perform the delete, add or modify operation. 3. Unlock the region that was locked in step 1. NOTES ----- 1. The lock need only be applied for a delete, modify or add operation. Simply reading the database does not require any special treatment. 2. Terminating an application does NOT automatically remove this type of lock. This means that if the application which created the lock terminates abnormally before the lock is removed, no other application will be able to update the message database. Only a reset will remove the lock. 3. RemoteAccess 1.10 introduced an extension to the locking specification. If unable to get a lock on the message database, RemoteAccess will create (or touch the timestamp if it already exists) a zero-length semaphore file called MBUNLOCK.NOW, in the message-base directory. Applications which lock the message-base for longer than 15 seconds continuously should check for the presence of this file, and if it has been created or touched, release the lock temporarily to allow RemoteAccess to perform an update operation. 4. Applications should never assume that MSGINFO.BBS has not changed; this file should be read after the lock (step 1) and rewritten again if appropriate before the lock is removed (step 3). 5. Many network shells also support the INT 21 5Ch function, making SHARE unnecessary. Therefore, simply doing a SHARE "installation check" is not sufficient. The application should attempt an actual lock in order to determine whether this function is supported. CREDITS ------- The locking specification described in this document was originally co-developed by Andrew Milner and Joaquim Homrighausen. The MBUNLOCK.NOW extension (see note 3) was suggested by Gerard van der Land. **********************************************************************