Microsoft KB Archive/97875

= Support for Locking at Byte, Field, Record and File Level =

Article ID: 97875

Article Last Modified on 10/31/2006



This article was previously published under Q97875



SUMMARY
LAN Manager can support locking at byte, field, record, and file levels by requesting byte-range locking via the [core] Lock_Byte_Range, Unlock_Byte_Range, [LM1.0+] Locking_and_X, Lock_and_Read, and Write_and_Unlock Server Message Blocks (SMBs).



MORE INFORMATION
Applications can use APIs such as the C run time &quot;locking&quot; routine to specify the:


 * Handle of the file in which to lock/unlock a range of bytes
 * Locking mode (lock, unlock, etc.)
 * Number of bytes to lock

The lock is applied to the indicated number of bytes beginning at the current seek pointer for the specified file.

If the specified handle represents a remote file (on the server), the operating system passes the request to the redirector. The redirector prepares an SMB and sends it to the server. In the case of the Lock_Byte_Range SMB, for example, the SMB specifies:


 * A file identifier known to the server (FID)
 * The number of bytes to lock
 * The byte offset within the specified file to begin the lock

The server receives the [Lock_Byte_Range] SMB request, completes the lock if there are no conflicts with pre-existing locks, and records the fact that the specified bytes are locked.

When a second application tries to lock, read, or write bytes within the locked range, the server returns an error.

Note: The older Lock_Byte_Range SMB allowed only &quot;lock out all access,&quot; but the newer Locking_and_X SMB allows designation of &quot;lock out all access&quot; or &quot;read OK while locked.&quot; However, the only APIs that allow the programmer to make this differentiation when requesting a lock are OS/2 1.2+ &quot;DosFileIO&quot; and OS/2 2.0 &quot;DosFileLock.&quot; This feature is not currently supported in the NT &quot;Lockfile&quot; function, or in any of the standard Microsoft C run time routines.

The core SMB specification document calls its locking SMBs by two names. In the back of the document (where SMBs are listed with their hex codes) it calls them &quot;Lock_Byte_Range&quot; and &quot;Unlock_Byte_Range,&quot; while in the body of the document (where SMBs are described) it calls them &quot;Lock_Record&quot; and &quot;Unlock_Record.&quot; The word &quot;record&quot; is somewhat misleading. It is indeed a byte range lock (you can lock a single byte), although many database/accounting applications use byte range locking to lock a range of bytes that the application itself knows to be a single significant record.

Applications define &quot;record&quot; differently. For example, an accounting application requires a certain number of bytes to make up a &quot;customer&quot; record (x bytes for the Name field, x bytes for the Address field, and so on). You can't tell the server to &quot;lock record 13 of the CUSTOMER.DBF file&quot; because the server has no way of knowing how many bytes are in one of this application's records. Instead, the application calculates the byte range within the CUSTOMER.DBF file that is occupied by what it refers to as &quot;record number 13,&quot; then uses the locking API to request that this specific byte range be locked. The server sees that a byte range just became locked; the application sees that record 13 just became locked.

If the application wants to lock just the &quot;Address&quot; field within record 13 of the customer database, it calculates the range of bytes that are occupied by the address field of record 13, then issues the byte range lock request.

In summary, LAN Manager supports locking at byte, field, record, and file levels.

Reference(s):

Microsoft C &quot;Run-Time Library Reference&quot;

Additional query words: 2.00 2.10 2.10a 2.20

Keywords: KB97875

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.