home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / DATABASE / BLTC17.ZIP / BLTNETWK.TXT < prev    next >
Encoding:
Text File  |  1993-08-31  |  10.9 KB  |  261 lines
  1. BULLET Network Routines, Supplemental Information.        26-July-1993
  2.  
  3.  
  4. BULLET has nine network-related routines that you can use.  Each will
  5. be described in this document as will when/how to use them and a bit
  6. of background information.
  7.  
  8. The BULLET network routines are:
  9.  
  10.   1.  LockXB
  11.   2.  UnlockXB
  12.   3.  LockKeyXB
  13.   4.  UnlockKeyXB
  14.   5.  LockDataXB
  15.   6.  UnlockDataXB
  16.   7.  DriveRemoteXB
  17.   8.  FileRemoteXB
  18.   9.  SetRetriesXB
  19.  
  20. Routines 7 through 9 are not discussed here.  The CZ documentation
  21. should be adequate for these.
  22.  
  23.  
  24. Glossary.
  25. ---------
  26.  
  27. BULLET fileset: Group of files related by their common AccessPack
  28. variable, AP().  A fileset contains 1 data file and from 1 to 32
  29. index files.
  30.  
  31. Locking: Giving exclusive file access to one application.
  32.  
  33. Unlocking: Releasing exclusive file access so other applications
  34. may perform a lock.
  35.  
  36. Flush: Act of updating disk data with data that currently is stored
  37. only in memory.
  38.  
  39.  
  40. Background.
  41. -----------
  42.  
  43. The purpose of locking/network access, in general, is to keep data in the
  44. fileset in a known state.  When only a single application access a data
  45. file the state will always be known since only that application can
  46. alter the state.  However, when multiple applications access a data
  47. file each application can alter the state without imforming the others
  48. of the new state.  To solve this problem, the locking of the data to a
  49. single application at any one time is done.  Thus giving an application
  50. exclusive access to the data, allowing it to alter its state, then to
  51. release the exclusive access (unlock) so that others can again access
  52. the data.
  53.  
  54. A BULLET file is made up of both header and data portions.  The header
  55. describes the makeup of the file and may be changed by accesses to
  56. that file (adding records, reindexing, etc.).  The data is essentially
  57. just user-data (data records, key fields, etc.).  In order to properly
  58. access a file in a multi-access environment, both the data and header
  59. portions must always be in a known state.  This requires that, upon
  60. initial access (the lock), the current application's internal header
  61. information (internal BULLET data areas) be reloaded from the physical
  62. image on disk.  It also requires that any buffered data from previous
  63. accesses be discarded. All internal BULLET data structures are properly
  64. refreshed when a LockXB is called.  However, the application must also
  65. insure that any data that IT has retained from a previous access be
  66. discarded since it may no longer be valid.
  67.  
  68. After a successful LockXB, the fileset is in a known state -- BULLET
  69. has reloaded its internal structures and is ready to operate.  At this
  70. time you can perform any file operation such as InsertXB, UpdateXB,
  71. ReindexXB, GetFirstXB, etc.  Deleting may also be performed but your
  72. application (logic) should first verify that the delete is valid --
  73. you don't want to delete a customer-record if the customer has
  74. outstanding invoices, etc.
  75.  
  76. Once done with the operation, you should release the lock.  While the
  77. lock is in place, no other application may access the fileset, so it's
  78. best to get in, do what you need, and get out.  Don't keep a fileset
  79. locked unless you need to have exclusive access.  To release the
  80. fileset locked by LockXB, use UnlockXB.  This will reverse the actions
  81. of LockXB.  First, it flushes any BULLET data buffers, including
  82. updating the file headers on disk with the current state of the file.
  83. This is important since, while the data portion of a file is written
  84. essentially in real-time, the header portion remains in memory until
  85. an UnlockXB or until the file is closed (always! unlock files before
  86. closing them).  After the flush, the disk image matches that known
  87. state of the fileset of the application in control, and so BULLET
  88. unlocks the fileset. The fileset is now available to other
  89. applications.  When another application requires the fileset, it goes
  90. through the exact same procedure.
  91.  
  92. Current versions of BULLET allow record locking in addition to file
  93. locking.  BULLET implements file locking by locking all bytes of a
  94. file, rather than by opening the file in an exclusive access mode.
  95. This permits BULLET to control access without the need to constantly
  96. open and close files with an exclusive access mode (though that is
  97. also available).  There are times, however, when exclusive access to
  98. the entire data file is not required, but rather only to a single record.
  99. By setting the AP(n).RecNo=RecordNumberToLock, the BULLET lock routines
  100. only lock that single record number in the data file, allowing other
  101. applications access to that data file.  Note that this mode -- record
  102. locking, does NOT reload the data file header*, it simply locks that
  103. one record preventing other applications from altering it.  For index
  104. files, the entire file is locked since the b-tree is one big, happy
  105. dataset, not independent data records as with the data file.  Note
  106. that since the header of the data file is not locked, you cannot
  107. perform any operations on the data file that would alter its state.
  108. If all you want to do is read and _hold_ a single record, you may want
  109. to use a record lock.  However, if you can get in and get out, perhaps
  110. setting a field in the record to hold with a flag, then the full
  111. LockXB() is the best solution (and recommended).
  112.  
  113. *Future versions will reload the header, but not lock it. The programmer
  114. can use ReadDHXB to reload the data file header manually.
  115.  
  116. The following is not a network-only concern, but is very important:
  117.  
  118. One other thing that the programmer must be aware of is keeping index
  119. files in-sync with its associated data file.  If keys within an index
  120. file(s) are based on a data file, and if that data file is altered
  121. without also updating the index file(s), then that index file is no
  122. longer valid.  To ensure the index file(s) remain in-sync with its
  123. respective data file, use only the high-level access routines when
  124. adding or updating data (InsertXB and UpdateXB) and use an AccessPack
  125. (AP()) with _ALL_ related index files controlled from that one AP().
  126. Note that since Xbase-specs do not physically delete data records,
  127. one can DeleteRecordXB (but not DeleteKeyXB!) as often as one likes
  128. without invalidating the index files.  However, if there are records
  129. tagged as 'deleted' in a data file, and if that file is PackRecordsXB'ed,
  130. then all associated index files must be ReindexXB'ed, else the index
  131. file(s) contains, again, invalid key pointers.  It is the programmer's
  132. responsibility to ensure that index files remain in-sync with their
  133. data file.
  134.  
  135.  
  136. Routines.
  137. ---------
  138.  
  139. 1.  LockXB
  140. ----------
  141.  
  142. LockXB is the highest-level lock function.  It coordinates the locking
  143. of an entire BULLET fileset with a single call and performs memory-
  144. buffer refresh of the respective file headers in the fileset.  LockXB
  145. is a combination of LockKeyXB and LockDataXB.  The process is:
  146.  
  147.           F#=1, indexing first AP() pack.
  148.  Step 1.  Attempt to lock key file F#.
  149.  Step 2.  If success, read F# header, increment F#.
  150.  
  151.           While success, and for each AP() index file, repeat
  152.           steps 1 & 2.
  153.  
  154.           If any failure, undo previous locks performed by steps 1&2
  155.           and set RC = F# of failed lock.  Go to step 5.
  156.  
  157.           If all index files successfully locked and headers loaded,
  158.           proceed to step 3:
  159.  
  160.  Step 3.  Attempt to lock data file.
  161.  Step 4.  If success, read header.
  162.  
  163.           If failure (including header load failure), undo lock
  164.           performed by step 3, if at all, and locks performed by
  165.           steps 1 & 2.  Set RC = F# (F# is equal to number of index
  166.           files locked in steps 1&2 _PLUS_ 1.  E.g., two index files
  167.           locked okay but data file failed to lock, RC=3.
  168.  
  169.  Step 5.  If failure, RC (return code) is returned to the caller in
  170.           the ax register, or if called from a high-level langauge,
  171.           as the return code (e.g., as stat in stat = BULLET(AP(1))).
  172.           This return code is not the error code.  REPEAT, is not the
  173.           error code.  To obtain the _error_ code, use
  174.  
  175.                 ecode=AP(stat).Stat
  176.  
  177.           If success, the RC (hence, stat) is 0.  There is no partial
  178.           success.  Either LockXB locks and loads everything, or it
  179.           fails.
  180.  
  181.           Also note that the return code of the _ALL_ Lock() routines
  182.           differs from the other high-level access routines in that
  183.           it return code=0 always implies success.  See InsertXB() for
  184.           more.  (If CZ is loaded, just move the cursor onto InsertXB()
  185.           above and press the hotkey!)
  186.  
  187.  
  188. 2.  UnlockXB
  189. ------------
  190.  
  191. UnlockXB is the highest-level unlock function.  It coordinates the
  192. unlocking of an entire BULLET fileset that was locked with LockXB
  193. with a single call and performs memory-buffer flushing of the
  194. repective file headers in the fileset.  UnlockXB is a combination of
  195. UnlockKeyXB and UnlockDataXB.  The process is:
  196.  
  197.           F#=1, indexing first AP() pack.
  198.  Step 1.  Flush key file header F# to disk.
  199.  Step 2.  If success, unlock key file F#, increment F#.
  200.  
  201.           While success, and for each AP() index file, repeat
  202.           steps 1 & 2.
  203.  
  204.           If any failure, set RC = F# of failed unlock.  Go to step 5.
  205.           (Relocking is not attempted.  Programmer must manually
  206.           unlock remaining locks using UnlockKeyXB.)
  207.  
  208.           If all index files successfully unlocked and headers flushed,
  209.           proceed to step 3:
  210.  
  211.  Step 3.  Flush data file header to disk.
  212.  Step 4.  If success, unlock data file.
  213.  
  214.           If failure (including header flush failure), set RC = F#
  215.           (F# is equal to number of index files unlocked in steps 1&2
  216.           _PLUS_ 1.  E.g., two index files unlocked okay but data file
  217.           failed to flush, RC=3.
  218.  
  219.  Step 5.  If failure, RC (return code) is returned to the caller in
  220.           the ax register, or if called from a high-level langauge,
  221.           as the return code (e.g., as stat in stat = BULLET(AP(1))).
  222.           This return code is not the error code.  REPEAT, is not the
  223.           error code.  To obtain the _error_ code, use
  224.  
  225.                 ecode=AP(stat).Stat
  226.  
  227.           If success, the RC (hence, stat) is 0.  There is partial
  228.           success with UnlockXB.  However, partial success implies
  229.           partial failure.  It is the programmer's responsibilty to
  230.           flush & unlock any failed unlocks.  It is unlikely that
  231.           a failure will occur with an UnlockXB operation, but be
  232.           aware of what must be done if it were to occur.
  233.  
  234.  
  235. 3.  LockKeyXB
  236. -------------
  237.  
  238. LockKeyXB is as LockXB but steps 1 & 2 only.  If success, proceed to
  239. step 5 rather than 3.
  240.  
  241.  
  242. 4.  UnlockKeyXB
  243. ---------------
  244.  
  245. UnlockKeyXB is as UnlockXB but steps 1 & 2 only.  If success, proceed
  246. to step 5 rather than 3.
  247.  
  248.  
  249. 5.  LockDataXB
  250. --------------
  251.  
  252. LockDataXB is as LockXB but steps 3 & 4 only.
  253.  
  254.  
  255. 6.  UnlockDataXB
  256. ----------------
  257.  
  258. UnlockDataXB is as UnlockXB but steps 3 & 4 only.
  259.  
  260. <EOF>
  261.