PageRenderTime 47ms CodeModel.GetById 17ms RepoModel.GetById 0ms app.codeStats 1ms

/xbase64-3.1.2/html/xblock.htm

#
HTML | 281 lines | 224 code | 57 blank | 0 comment | 0 complexity | 68ce23f936f641553309d9e95a8185c8 MD5 | raw file
Possible License(s): LGPL-2.1, LGPL-2.0 
    

  1. <!DOCTYPE HTML PUBLIC>
    2. 

  2. <HTML>
    3. 

  3. <TITLE>Xbase DBMS Chapter 10</TITLE>
    4. 

  4. <BODY BGCOLOR=#FFFFFF>
    5. 

  5. <H1><p align="center">Xbase DBMS Record and File Locking</p></H1>
    6. 

  6. <p align="center">Chapter Updated 4/8/98</p><hr>
    7. 

  7. 

  8. <h3>Locking Overview</h3>
    9. 

  9. 

  10. Xbase DBMS supports multi-user processing through file and record locks.
    11. 

  11. Record locking restricts multiple cooperating programs from simultaneously 
    12. 

  12. accessing the same data and corrupting it. Without record and file locking 
    13. 

  13. in a multi-user environment, simultaneous access to the data and index files
    14. 

  14. can cause the files to become inaccurate and unusable.<br><br>
    15. 

  15. 

  16. Record locking is on by default in the Xbase DBMS library. To disable it,
    17. 

  17. comment out the LOCKING_ON option in the <em>options.h</em> file in the 
    18. 

  18. xbase/src directory.<br><br>
    19. 

  19. 

  20. The current Xbase DBMS record locking does not co-exist with other Xbase 
    21. 

  21. products and there is not yet support for locking in a DOS/Windows environment.
    22. 

  22. The locking functions do work correctly for a Xbase DBMS only configuration.
    23. 

  23. Future version of Xbase DBMS will have enhanced locking features for 
    24. 

  24. co-existing with other Xbase products and also include DOS/Windows support.
    25. 

  25. <br><br>
    26. 

  26. 

  27. The locking methods return either LOCK_FAILED or NO_ERROR.  If they return
    28. 

  28. LOCK_FAILED the actual reason can be found in the global variable 
    29. 

  29. <em>errno</em> or function <em>perror()</em> can be executed to view the
    30. 

  30. results.
    31. 

  31. <br><br>
    32. 

  32. 

  33. The errno field may contain one of the following values if the lock was not
    34. 

  34. successful.<br><br>
    35. 

  35. <TABLE BORDER>
    36. 

  36. <TR VALIGN="BASELINE">
    37. 

  37. <TR><TH ALIGN="LEFT">Error Code<TD>Description
    38. 

  38. <TR><TH ALIGN="LEFT">EBADF<TD>Invalid file descriptor
    39. 

  39. <TR><TH ALIGN="LEFT">EINVAL<TD>Invalid lock information or file does not support locks
    40. 

  40. <TR><TH ALIGN="LEFT">EACCESS<BR>EAGAIN<TD>Lock can not be set because it is blocked by an existing lock on the file.
    41. 

  41. <TR><TH ALIGN="LEFT">ENOLCK<TD>The system is out of lock resources, too many file locks in place.
    42. 

  42. <TR><TH ALIGN="LEFT">EDEADLK<TD>Deadlock condition
    43. 

  43. <TR><TH ALIGN="LEFT">EINTR<TD>Process was interrupted by a signal while it was waiting
    44. 

  44. </TABLE>
    45. 

  45. <br><br>
    46. 

  46. <h3>Types of Locks</h3>
    47. 

  47. 

  48. <li><em>Write or Exclusive Locks</em> provide exclusive access to a 
    49. 

  49. particular file location. No other process can lock the same location.<br><br>
    50. 

  50. 

  51. <li><em>Read or Shared Locks</em> prohibit any process from requesting a write 
    52. 

  52. lock on a specified part of the file.  Other processes can request 
    53. 

  53. simultaneous read locks.<br><br><br>
    54. 

  54. 

  55. <h3>DBF File Locking Techniques</h3>
    56. 

  56. 

  57. Xbase DBMS uses the following protocol for DBF file and record locking:
    58. 

  58. <br><br>
    59. 

  59. 

  60. To lock a record - the first byte of the record is locked.<br>
    61. 

  61. To lock the file - the header bytes of the file are locked.<br><br>
    62. 

  62. 

  63. When a record is being appended to the file, the header bytes are locked.<br>
    64. 

  64. When a record is being updated, the header bytes and the specific record are
    65. 

  65. locked.<br><br>
    66. 

  66. This locking protocol is probably not compatable with other Xbase type products.
    67. 

  67. However, Xbase can be safely used for multi-user access when it is not 
    68. 

  68. simultaneously updating DBF or NDX files while other products/programs are.
    69. 

  69. <br><br><br>
    70. 

  70. 

  71. <h3>NDX File Locking Techniques</h3>
    72. 

  72. 

  73. Xbase DBMS locks indexes by locking the first 512 bytes 
    74. 

  74. of the index file.
    75. 

  75. The entire index is locked because any updates to the index potentially
    76. 

  76. can modify significant portions of the index tree.
    77. 

  77. <br><br><br>
    78. 

  78. 

  79. <h3>DBT File Locking Techniques</h3>
    80. 

  80. 

  81. Xbase DBMS locks memo files by locking the first 4 bytes 
    82. 

  82. of the memo file. This effectively locks the entire file.  The entire file
    83. 

  83. is locked because any updates to the free block chain can significantly
    84. 

  84. change the structure of the file.
    85. 

  85. <br><br><br>
    86. 

  86. 

  87. 

  88. <h3>AutoLocking Features</h3>
    89. 

  89. 

  90. If LOCKING_ON is set in the <em>options.h</em> file, the locking methods 
    91. 

  91. execute any appropriate locking logic.  If LOCKING_ON is not set in the 
    92. 

  92. <em>options.h</em> file, all locking methods return NO_ERROR without 
    93. 

  93. performing any actual record or file locking.  This enables the application
    94. 

  94. program to always call locking routines regardless of the LOCKING_ON switch
    95. 

  95. in the <em>options.h</em> file.
    96. 

  96. <br><br>
    97. 

  97. By leaving the autolocking features enabled, the application program does
    98. 

  98. not need to address record, file or index locking.  All locking is handled
    99. 

  99. automatically by the Xbase routines.  However, if access to the locking 
    100. 

  100. routines is required, they are available to the applciation programmer.
    101. 

  101. <br><br>
    102. 

  102. When the files are automatically locked by the Xbase routines, the database 
    103. 

  103. file is locked first, then it locks the indexes in alphabetical order.  To 
    104. 

  104. avoid deadlock conditions, files and record locks should always be done in 
    105. 

  105. the same order.  When the files are unlocked, then indexes are unlocked
    106. 

  106. first, then the database is unlocked.
    107. 

  107. <br><br>
    108. 

  108. Auto-locking works well in an on-line transaction based environment.
    109. 

  109. However, it does not function efficiently in batch mode. If you
    110. 

  110. will be writing programs which process files in a batch mode, disabling 
    111. 

  111. auto-lock and locking the entire file at the beginning of the process 
    112. 

  112. and unlocking the file at the end of the process will significantly
    113. 

  113. reduce process time.  On a 586-200 class machine, a file with 45000 records
    114. 

  114. can be read thru in a few seconds with the file locked in batch mode. 
    115. 

  115. In record-lock mode it takes about six minutes with the same processor. 
    116. 

  116. 

  117. <br><br>For processing large files, locking the file instead of locking each
    118. 

  118. record is far more efficient.  This is how you do it.<br><br>
    119. 

  119. 

  120. For reading the file in batch mode:<br>
    121. 

  121. DBF.AutoLockOff();<br>
    122. 

  122. DBF.LockDatabase( F_SETLKW, F_RDLCK, 0L );<br><br>      
    123. 

  123. For updating the file in batch mode:<br>
    124. 

  124. DBF.AutoLockOff();<br>
    125. 

  125. DBF.LockDatabase( F_SETLKW, F_WRLCK, 0L );<br><br>      
    126. 

  126. <br> 
    127. 

  127. <hr><br>
    128. 

  128. 

  129. <h3>Method Table</h3>
    130. 

  130. 

  131. <TABLE BORDER>
    132. 

  132. <CAPTION ALIGN="TOP"><h3><Xbase Locking Method List</h3></CAPTION>
    133. 

  133. <TR VALIGN="BASELINE">
    134. 

  134. <TR><TH ALIGN="LEFT">Method<TD>Description
    135. 

  135. <TR><TH ALIGN="LEFT">DBF::AutoLockOn<TD>Turns autolocking on
    136. 

  136. <TR><TH ALIGN="LEFT">DBF::AutoLockOff<TD>Turns autolocking off
    137. 

  137. <TR><TH ALIGN="LEFT">DBF::ExclusiveLock<TD>Lock file and indexes in exclusive mode
    138. 

  138. <TR><TH ALIGN="LEFT">DBF::ExclusiveUnlock<TD>Unlock files and indexes 
    139. 

  139. <TR><TH ALIGN="LEFT">DBF::LockDatabase<TD>Locks or unlocks a DBF database
    140. 

  140. <TR><TH ALIGN="LEFT">NDX::LockIndex<TD>Locks or unlocks an NDX index
    141. 

  141. <TR><TH ALIGN="LEFT">NDX::LockMemoFile<TD>Locks or unlocks a DBT memo field file
    142. 

  142. </TABLE>
    143. 

  143. <BR><HR>
    144. 

  144. 

  145. <h4>Method Descriptions</h4>
    146. 

  146. 

  147. <h4>Method VOID DBF::AutoLockOn( VOID )</h4><br>
    148. 

  148. 

  149. This method turns automatic record locking on.  Auto record locking is on
    150. 

  150. by default if LOCKING_ON is set in the options.h file.<br><br>
    151. 

  151. 

  152. <h4>Example Program:</h4>
    153. 

  153. 

  154. See program <A HREF="/zips/loadzips.cpp">loadzips.cpp</A> for an example of
    155. 

  155. how to use this method.
    156. 

  156. <hr>
    157. 

  157. 

  158. <h4>Method VOID DBF::AutoLockOff( VOID )</h4><br>
    159. 

  159. 

  160. This method turns automatic record locking off.  Auto record locking is on
    161. 

  161. by default if LOCKING_ON is set in the options.h file.
    162. 

  162. <br><br>
    163. 

  163. Turning auto locking off will result in slightly better execution speeds
    164. 

  164. but should not be used in multi-user environments when multiple users can
    165. 

  165. update files simultanteously.  If multiple users are accessing a file which
    166. 

  166. is read only then it is safe to turn off auto-locking for a particular file.
    167. 

  167. <br><br>
    168. 

  168. Turning autolocking off will disable any index file locking which is 
    169. 

  169. particularly dangerous in a multi-user environment if updates on the files
    170. 

  170. are permitted. 
    171. 

  171. 

  172. 

  173. <h4>Example Program:</h4>
    174. 

  174. 

  175. See program <A HREF="/zips/loadzips.cpp">loadzips.cpp</A> for an example of
    176. 

  176. how to use this method.
    177. 

  177. 

  178. <hr>
    179. 

  179. <h4>Method SHORT DBF::ExclusiveLock( SHORT WaitOption )</h4>
    180. 

  180. <h4>Method SHORT DBF::ExclusiveUnlock( VOID )</h4><br>
    181. 

  181. 

  182. ExclusiveLock and ExclusiveUnclock will lock the data file, memo file (if applicable) 
    183. 

  183. and any associated indexes in an exclusive mode. They also turn auto-lock 
    184. 

  184. on and off as appropriate.<br><br>
    185. 

  185. 

  186. WaitOption is either:<br><br>
    187. 

  187. <li>F_SETLK - returns immediately regardless if success or failure<br>
    188. 

  188. <li>F_SETLKW - waits until lock function executes<br><br>
    189. 

  189. 

  190. <h4>Example Program:</h4>
    191. 

  191. 

  192. See program <A HREF="/XbaseSamples/sample4.cpp">sample4.cpp</A> for an example of
    193. 

  193. how to use this method.
    194. 

  194. 

  195. <hr>
    196. 

  196. <h3>Method SHORT DBF::LockDatabase( SHORT WaitOption, SHORT LockType, LONG LRecNo )
    197. 

  197. </h3><br>
    198. 

  198. 

  199. This method locks or unlocks an Xbase (.DBF) file which was previously opened.<br>
    200. 

  200. <br>
    201. 

  201. WaitOption is either:<br><br>
    202. 

  202. <li>F_SETLK - returns immediately regardless if success or failure<br>
    203. 

  203. <li>F_SETLKW - waits until lock function executes<br><br>
    204. 

  204. 

  205. LockType is one of:<br><br>
    206. 

  206. <li>F_RDLCK - Perform a Read or Shared Lock<br>
    207. 

  207. <li>F_WRLCK - Perform a Write or Exclusive Lock<br>
    208. 

  208. <li>F_UNLCK - Unlock it<br><br>
    209. 

  209. 

  210. LRecNo is:<br><br>
    211. 

  211. 0 - Lock the header section of the file (use this to lock the file)<br>
    212. 

  212. 1 through n - Lock a particular record<br><br>
    213. 

  213. 

  214. <TABLE BORDER>
    215. 

  215. <CAPTION ALIGN="TOP"<h4>Method Return Codes</h4></CAPTION>
    216. 

  216. <TR><TH ALIGN="LEFT">Return Code<TD>Description
    217. 

  217. <TR><TH ALIGN="LEFT">INVALID_RECORD<TD>An invalid record given
    218. 

  218. <TR><TH ALIGN="LEFT">LOCK_FAILED<TD>The lock action failed, see errno
    219. 

  219. <TR><TH ALIGN="LEFT">NO_ERROR<TD>The lock was successful
    220. 

  220. </TABLE>
    221. 

  221. 

  222. 

  223. <h4>Example Program:</h4>
    224. 

  224. 

  225. See program <A HREF="/zips/loadzips.cpp">loadzips.cpp</A> for an example of
    226. 

  226. how to use this method.
    227. 

  227. 

  228. <hr>
    229. 

  229. 

  230. <h3>Method SHORT DBF::LockIndex( SHORT WaitOption, SHORT LockType )
    231. 

  231. </h3><br>
    232. 

  232. 

  233. This method locks or unlocks an Index (.NDX) file which was previously opened.<br>
    234. 

  234. <br>
    235. 

  235. WaitOption is either:<br><br>
    236. 

  236. <li>F_SETLK - returns immediately regardless if success or failure<br>
    237. 

  237. <li>F_SETLKW - waits until lock function executes<br><br>
    238. 

  238. 

  239. LockType is one of:<br><br>
    240. 

  240. <li>F_RDLCK - Perform a Read or Shared Lock<br>
    241. 

  241. <li>F_WRLCK - Perform a Write or Exclusive Lock<br>
    242. 

  242. <li>F_UNLCK - Unlock it<br><br>
    243. 

  243. 

  244. <TABLE BORDER>
    245. 

  245. <CAPTION ALIGN="TOP"<h4>Method Return Codes</h4></CAPTION>
    246. 

  246. <TR><TH ALIGN="LEFT">Return Code<TD>Description
    247. 

  247. <TR><TH ALIGN="LEFT">LOCK_FAILED<TD>The lock action failed, see errno
    248. 

  248. <TR><TH ALIGN="LEFT">NO_ERROR<TD>The lock was successful
    249. 

  249. </TABLE>
    250. 

  250. 

  251. <h4>Example Program:</h4>
    252. 

  252. See program <A HREF="/zips/loadzips.cpp">loadzips.cpp</A> for an example of
    253. 

  253. how to use this method.
    254. 

  254. <hr>
    255. 

  255. 

  256. <h3>Method SHORT DBF::LockMemoFile( SHORT WaitOption, SHORT LockType )
    257. 

  257. </h3><br>
    258. 

  258. 

  259. This method locks or unlocks a memo (.DBT) file which was previously opened.
    260. 

  260. It is not necessary for an application to call this method as locking is
    261. 

  261. handled automatically by other routines.<br><br>
    262. 

  262. 

  263. WaitOption is either:<br><br>
    264. 

  264. <li>F_SETLK - returns immediately regardless if success or failure<br>
    265. 

  265. <li>F_SETLKW - waits until lock function executes<br><br>
    266. 

  266. 

  267. LockType is one of:<br><br>
    268. 

  268. <li>F_RDLCK - Perform a Read or Shared Lock<br>
    269. 

  269. <li>F_WRLCK - Perform a Write or Exclusive Lock<br>
    270. 

  270. <li>F_UNLCK - Unlock it<br><br>
    271. 

  271. 

  272. <TABLE BORDER>
    273. 

  273. <CAPTION ALIGN="TOP"<h4>Method Return Codes</h4></CAPTION>
    274. 

  274. <TR><TH ALIGN="LEFT">Return Code<TD>Description
    275. 

  275. <TR><TH ALIGN="LEFT">LOCK_FAILED<TD>The lock action failed, see errno
    276. 

  276. <TR><TH ALIGN="LEFT">NO_ERROR<TD>The lock was successful
    277. 

  277. </TABLE>
    278. 

  278. <hr>
    279. 

  279. <p><img src="xbase.jpg"><br><hr>
    280. 

  280. </BODY>
    281. 

  281. </HTML>
    282. 

  282.