home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 12 / CD_ASCQ_12_0294.iso / maj / 421 / cz.hlp (.txt) < prev    next >
CZ Help  |  1993-08-03  |  218KB  |  3,869 lines

  1. CZ_HELP!
  2. INDEX
  3. TUTORIAL_INDEX
  4. LICENSE_AGREEMEN
  5. LICENSE_A
  6. PRODUCT_SUPPORT
  7. STARTING_CZ
  8. USING_CZ
  9. USING_CZ_A
  10. USING_CZ_B
  11. ABOUT_CZ
  12. IS_BULLET
  13. IS_A_DATABASE
  14. IS_DBF
  15. IS_A_BTREE
  16. IS_A_NETWORK
  17. IS_FILE_LOCKING
  18. IS_NLS
  19. DESIGN_A_DB
  20. CREATE_A_DB
  21. ADD_TO_THE_DB
  22. QUERY_THE_DB
  23. UPDATE_THE_DB
  24. DELETE_A_RECORD
  25. BC_COMPILE_WITH
  26. LIB_WITH
  27. MAKE_A_QLB
  28. LINK_WITH
  29. CALL_BULLET
  30. SPECS_OVERALL
  31. SPECS_DBF
  32. SPECS_DBF_A
  33. SPECS_DBF_B
  34. SPECS_DBF_C
  35. SPECS_INDEX
  36. SPECS_INDEX_A
  37. SPECS_INDEX_B
  38. SPECS_INDEX_C
  39. SPECS_MEMORY
  40. SPECS_MEMORY_A
  41. SPECS_OS_CALLS
  42. SPECS_LANGUAGES
  43. SPECS_OSES
  44. SPECS_NETWORKS
  45. SPECS_PERFORMANC
  46. SPECS_PERF_A
  47. SPECS_PERF_B
  48. SPECS_PERF_C
  49. SPECS_PERF_D
  50. INITXB
  51. EXITXB
  52. ATEXITXB
  53. MEMORYXB
  54. BREAKXB
  55. BACKUPFILEXB
  56. STATHANDLEXB
  57. GETEXTERRORXB
  58. DVMONCXB
  59. CREATEDXB
  60. OPENDXB
  61. CLOSEDXB
  62. STATDXB
  63. READDHXB
  64. FLUSHDHXB
  65. COPYDHXB
  66. ZAPDHXB
  67. CREATEKXB
  68. CREATEKXB_A
  69. CREATEKXB_B
  70. CREATEKXB_C
  71. CREATEKXB_D
  72. CREATEKXB_E
  73. CREATEKXB_F
  74. OPENKXB
  75. CLOSEKXB
  76. STATKXB
  77. READKHXB
  78. FLUSHKHXB
  79. COPYKHXB
  80. ZAPKHXB
  81. GETDESCRIPTORXB
  82. GETRECORDXB
  83. ADDRECORDXB
  84. UPDATERECORDXB
  85. DELETERECORDXB
  86. UNDELETERECORDXBfp
  87. PACKRECORDSXB
  88. FIRSTKEYXB
  89. EQUALKEYXB
  90. NEXTKEYXB
  91. PREVKEYXB
  92. LASTKEYXB
  93. STOREKEYXB
  94. DELETEKEYXB
  95. BUILDKEYXB
  96. CURRENTKEYXB
  97. GETFIRSTXB
  98. GETEQUALXB
  99. GETNEXTXB
  100. GETPREVXB
  101. GETLASTXB
  102. INSERTXB
  103. UPDATEXB
  104. REINDEXXB
  105. LOCKXB
  106. UNLOCKXB
  107. LOCKKEYXB
  108. UNLOCKKEYXB
  109. LOCKDATAXB
  110. UNLOCKDATAXB
  111. DRIVEREMOTEXB
  112. FILEREMOTEXB
  113. SETRETRIESXB
  114. DELETEFILEDOS
  115. RENAMEFILEDOS
  116. CREATEFILEDOS
  117. ACCESSFILEDOS
  118. OPENFILEDOS
  119. SEEKFILEDOS
  120. READFILEDOS
  121. EXPANDFILEDOS
  122. WRITEFILEDOS
  123. CLOSEFILEDOS
  124. MAKEDIRDOS
  125. ACCESSPACK
  126. BREAKPACK
  127. COPYPACK
  128. CREATEDATAPACK
  129. CREATEKEYPACK
  130. DESCRIPTORPACK
  131. DOSFILEPACK
  132. DVMONPACK
  133. EXITPACK
  134. FIELDDESCTYPE
  135. HANDLEPACK
  136. INITPACK
  137. MEMORYPACK
  138. OPENPACK
  139. REMOTEPACK
  140. SETRETRIESPACK
  141. STATDATAPACK
  142. STATKEYPACK
  143. STATHANDLEPACK
  144. XERRORPACK
  145. ERRORS_BULLET
  146. ERRORS_BULLET_B
  147. ERRORS_BULLET_C
  148. ERRORS_BULLET_D
  149. ERRORS_BASIC
  150. ERRORS_BASIC_B
  151. ERRORS_DOS
  152. ERRORS_DOS_B
  153. ERRORS_DOS_C
  154. INITXBSRC
  155. EXITXBSRC
  156. ATEXITXBSRC
  157. MEMORYXBSRC
  158. BREAKXBSRC
  159. BACKUPFILEXBSRC
  160. STATHANDLEXBSRC
  161. GETEXTERRORXBSRC
  162. DVMONCXBSRC
  163. CREATEDXBSRC
  164. CREATEDXBSRC_A
  165. OPENDXBSRC
  166. CLOSEDXBSRC
  167. STATDXBSRC
  168. READDHXBSRC
  169. FLUSHDHXBSRC
  170. COPYDHXBSRC
  171. ZAPDHXBSRC
  172. CREATEKXBSRC
  173. CREATEKXBSRC_A
  174. OPENKXBSRC
  175. CLOSEKXBSRC
  176. STATKXBSRC
  177. READKHXBSRC
  178. FLUSHKHXBSRC
  179. COPYKHXBSRC
  180. ZAPKHXBSRC
  181. GETDESCRIPTORXBSF
  182. GETRECORDXBSRC
  183. ADDRECORDXBSRC
  184. UPDATERECORDXBSR
  185. DELETERECORDXBSRU
  186. UNDELETERECORDSR&
  187. PACKRECORDSXBSRC
  188. FIRSTKEYXBSRC
  189. EQUALKEYXBSRC
  190. NEXTKEYXBSRC
  191. PREVKEYXBSRC
  192. LASTKEYXBSRC
  193. STOREKEYXBSRC
  194. DELETEKEYXBSRC
  195. BUILDKEYXBSRC
  196. CURRENTKEYXBSRC
  197. GETFIRSTXBSRC
  198. GETEQUALXBSRC
  199. GETNEXTXBSRC
  200. GETPREVXBSRC
  201. GETLASTXBSRC
  202. INSERTXBSRC
  203. UPDATEXBSRC
  204. REINDEXXBSRC
  205. LOCKXBSRC
  206. UNLOCKXBSRC
  207. LOCKKEYXBSRC
  208. UNLOCKKEYXBSRC
  209. LOCKDATAXBSRC
  210. UNLOCKDATAXBSRC
  211. DRIVEREMOTEXBSRC
  212. FILEREMOTEXBSRC
  213. SETRETRIESXBSRC
  214. DELETEFILEDOSSRC
  215. RENAMEFILEDOSSRCP,
  216. CREATEFILEDOSSRC^.
  217. ACCESSFILEDOSSRC(0
  218. OPENFILEDOSSRC
  219. SEEKFILEDOSSRC
  220. READFILEDOSSRC
  221. EXPANDFILEDOSSRC
  222. WRITEFILEDOSSRC
  223. CLOSEFILEDOSSRC
  224. MAKEDIRDOSSRC
  225. ~INDEX            CZ.HLP-BULLET for QB/BASIC PDS
  226.  System 
  227.  Mid-level Record/Key Access 
  228. InitXB        
  229. CreateDXB    CreateKXB    GetDescriptorXB     FirstKeyXB     
  230. ExitXB        
  231. OpenDXB      OpenKXB      GetRecordXB         EqualKeyXB     
  232. AtExitXB      
  233. CloseDXB     CloseKXB     AddRecordXB         NextKeyXB      
  234. MemoryXB      
  235. StatDXB      StatKXB      UpdateRecordXB      PrevKeyXB      
  236. BreakXB       
  237. ReadDHXB     ReadKHXB     DeleteRecordXB      LastKeyXB      
  238. BackupFileXB  
  239. FlushDHXB    FlushKHXB    UndeleteRecordXB    StoreKeyXB     
  240. StatHandleXB  
  241. CopyDHXB     CopyKHXB     PackRecordsXB       DeleteKeyXB    
  242. GetExtErrorXB 
  243. ZapDHXB      ZapKHXB                          BuildKeyXB     
  244. DVmonCXB      
  245.                                               CurrentKeyXB   
  246.  High-level Access 
  247.  Network 
  248. GetFirstXB    InsertXB     
  249. LockXB           UnlockXB        LockKeyXB      
  250. GetEqualXB    UpdateXB     
  251. UnlockKeyXB      LockDataXB      UnlockDataXB   
  252. GetNextXB     ReindexXB    
  253. DriveRemoteXB    FileRemoteXB    SetRetriesXB   
  254. GetPrevXB                  
  255. GetLastXB                  
  256.  Low-level DOS Access 
  257.                            
  258. DeleteFileDOS    OpenFileDOS     WriteFileDOS   
  259.                            
  260. RenameFileDOS    SeekFileDOS     CloseFileDOS   
  261.  Move cursor to index item 
  262. CreateFileDOS    ReadFileDOS     MakeDirDOS     
  263.  and press <Enter>.        
  264. AccessFileDOS    ExpandFileDOS                  
  265. See: TUTORIAL_INDEX
  266. ~TUTORIAL_INDEX   CZ.HLP-BULLET for QB/BASIC PDS
  267.  CZ.COM 
  268.  Using BULLET 
  269.  1.03 
  270. Starting_CZ   
  271. What:              How to:                                   
  272. Using_CZ      
  273.  is_BULLET          design_a_DB         BC_compile_with      
  274. About_CZ      
  275.  is_a_database      create_a_DB         LINK_with            
  276.               
  277.  is_DBF             add_to_the_DB       LIB_with             
  278.  is_a_Btree         query_the_DB        make_a_QLB           
  279.  Error Codes
  280.  is_a_network       update_the_DB      
  281.        
  282. Errors_BULLET 
  283.  is_file_locking    delete_a_record    
  284.  call_BULLET 
  285.        
  286. Errors_BASIC  
  287.  is_NLS                                
  288.        
  289. Errors_DOS    
  290.                     LICENSE_AGREEMENT   Product_Support      
  291.  Structure Pack Types 
  292.  Specifications 
  293. AccessPack       DVmonPack        RemotePack     
  294. Specs_Overall            
  295. BreakPack        ExitPack         SetRetriesPack 
  296. Specs_DBF                
  297. CopyPack         FieldDescTYPE    StatDataPack   
  298. Specs_Index              
  299. CreateDataPack   HandlePack       StatKeyPack    
  300. Specs_Memory             
  301. CreateKeyPack    InitPack         StatHandlePack 
  302. Specs_OS_Calls           
  303. DescriptorPack   MemoryPack       XErrorPack     
  304. Specs_Languages          
  305. DOSFilePack      OpenPack                        
  306. Specs_OSes               
  307.                                                  
  308. Specs_Networks           
  309.                                                  
  310. Specs_Performance        
  311. See: License_Agreement
  312. ~License_Agreement
  313. Before using this software you must agree to the following:
  314.  1. You are not allowed to operate more than one (1) copy of this software
  315.     package at one time per license. This means that if you have 10 programmers
  316.     that COULD possibly use the BULLET library at the same time, you must also
  317.     have ten (10) BULLET licenses.
  318.  2. You are not allowed to distribute non-executable code containing BULLET
  319.     code. This means that you are not allowed to redistribute BULLET code as
  320.     another .LIB, for example. Also, if BULLET code is to be contained in a
  321.     Dynamic Link Library (DLL) then it must be part of a stand-alone product.
  322.     This means that you cannot provide a .DLL containing BULLET code if that
  323.     .DLL is to be used as a programming library for other programmers. If you
  324.     wish to distribute non-executable code containing BULLET code you must
  325.     obtain written permission from the author.
  326.  3. This license grants you the right to use the BULLET library code on a
  327.     royalty-free basis.
  328. See: License_a                                                          -MORE-
  329. ~License_a
  330.  4. BULLET is owned by the author, Cornel Huth, and is protected by United
  331.     States copyright laws and international treaty provisions. You are not
  332.     allowed to make copies of this software except for archival purposes.
  333.  5. You may not rent or lease BULLET. You may not transfer this license without
  334.     the written permission of the author. If this software is an update or
  335.     upgrade, you may not sell or give away previous versions.
  336.  6. You may not reverse engineer, decompile, or disassemble this software.
  337.  7. There are no expressed or implied warranties with this software.
  338.  8. All liabilities in the use of this software rest with the user.
  339.  9. U.S. Government Restricted Rights. This software is provided with
  340.     restricted rights. Use, duplication, or disclosure by the Government is
  341.     subject to restrictions as set forth in subparagraph (c)(1)(ii) of the
  342.     Rights in Technical Data and Computer Software clause at 52.227-7013.
  343.     Manufacturer is Cornel Huth/6402 Ingram Rd/San Antonio, TX 78238.
  344.     This agreement is governed by the laws of the state of Texas.
  345. See: Product_Support
  346. ~Product_Support
  347. Support is available at my BBS, The 40th Floor, 7 days a week. Hours are
  348. 5pm to 9am, Central Time (USA). Weekend BBS hours are 1pm to 9am. Hours other
  349. than during above periods are voice. Central Time is UTC time -5/6 hours.
  350.         BBS tele#: 1-210-684-8065 (times listed above)
  351.                    N81, 300 to 14.4k bps
  352. Latest releases of BULLET are available for free download by registered users.
  353. Also available are other shareware products by me such as LP100, RUCKUS,
  354. QBTREE, QBEVGFX plus many more.
  355. The 40th Floor BBS is V32b, V32 compatible. Data rates 300 to 14.4k bps.
  356. My E-mail address:
  357.   Fidonet: 1:387/800.8
  358.  Internet: chuth@lonestar.utsa.edu
  359. See: Starting_CZ
  360. ~Starting_CZ
  361. At CZ's initial load it looks into the current directory for CZ.HLP, then in 
  362. the directory of CZ.COM, and last it looks for the pathname specified by the 
  363. DOS variable CZH (SET CZH=C:\DOC\CZ.HLP). Use /f: for alternate locations or 
  364. if CZ has any trouble locating its CZ.HLP file (C>cz /f:D:\BIN\CZ.HLP).      
  365. Load CZ.COM from the DOS command line. Options are:
  366.         /f:helpfile.ext       Use other than default CZ.HLP help file
  367.         /h# where n=1 to 4    Use alternate hot-key from default Alt-F1
  368.             #=1  Ctrl-h
  369.             #=2  F12
  370.             #=3  left+right Shift
  371.             #=4  Alt-left Shift
  372.         /u  uninstall CZ from memory (after initial load)
  373.         /s  temporarily put CZ to sleep by restoring all hooked vectors
  374.         /r  restore CZ from its sleep by rehooking vectors
  375.         /?  quick help
  376.  E.g., C>cz /f:D:\PRG_C\CBULLET.HLP   supply entire pathname when using /f:
  377.        C>cz /h1                       change hot key from Alt-F1 to Ctrl-H
  378. See: Using_CZ
  379. ~Using_CZ
  380. To activate CZ press the hot-key while the cursor is on the word you want to
  381. look up. Information on that word, if any, is displayed. If none is available,
  382. an index of help items in the dictionary is shown. Along the top-right of the
  383. index screens is the control bar. You can quickly move to the control bar by
  384. pressing <Home> or the See: line with <End>. Move the cursor to TUTORIAL_INDEX
  385. to select the second index screen or QUIT to return to whatever you were doing
  386. or over any index item. Then press <Enter> to move to that item's help entry.
  387. <F1> can be used as <Enter>. A mouse can also be used and is recommended.
  388. For example, to find out about CreateDXB, type it in your application and move
  389. the cursor on it. Press the hot-key. The CreateDXB screen is displayed. To see
  390. what pack type it uses, move to CreateDataPack (at Pack:) and press <Enter>.
  391. For a source example, move the cursor to Src: CreateDXBsrc. To go straight to
  392. the index from your application, press the hot-key with the cursor on a blank
  393. space. The <Esc> key returns you to your application.
  394. If there are more screens for the current topic the See: line has the same   
  395. topic name plus a letter, and -MORE- at the end. Move the cursor (or mouse)  
  396. to the topicname text (by using the <End> key) and press <Enter> (or click). 
  397. See: Using_CZ_a                                                         -MORE-
  398. ~Using_CZ_a
  399. CZ.COM can be loaded high but it is ESSENTIAL that you have at least 15K of  
  400. free UMB RAM available. It will load in as little as 4.5K but it will not    
  401. operate correctly. Use MEM/c to see how much Upper Memory RAM is available.  
  402. CZ opens the help file at installation. The help file is opened for Read-Only
  403. access with a Deny None sharing attribute. The file is closed when CZ is
  404. uninstalled (C>cz /u). CZ makes use of its own 256-byte stack.
  405. If you have several CZ help files, rename them to their particular application.
  406. For example:
  407. Rename the QuickBASIC BULLET CZ.HLP to QBULLET.HLP. Put QBULLET.HLP into your
  408. help files directory. Put SET CZH=C:\HELPFILES\QBULLET.HLP in your AUTOEXEC.BAT
  409. file. The next time CZ is installed it uses QBULLET.HLP from C:\HELPFILES.
  410. At anytime you can specify CZ.COM to use another help file. For example, if the
  411. current CZ help file is QBULLET.HLP but you want to use the CBULLET.HLP file,
  412. use C>cz /f:\helpfiles\cbullet.hlp. CBULLET.HLP then becomes the active file
  413. the next time you popup CZ.
  414. See: Using_CZ_b                                                         -MORE-
  415. ~Using_CZ_b
  416. Limitations:
  417. 1) The QB environment may interpret the Alt-F1 keypress after CZ has popped
  418. down. If this is a problem then change the hotkey, e.g., C>cz /h2 to use F12.
  419. 2) In the QB (and QBX) environment the keypad <Enter> key is not recognized by
  420. CZ. Use the main <Enter>. This occurs only in then QB 4.5 and QBX editors.
  421. 3) If, after returning from CZ, the QB environment's menu bar does not respond
  422. to Alt-keys (like an Alt-F), click the left mouse button a few times, or press
  423. F6 to go to the immediate window and execute a SHELL. It's unlikely that you'll
  424. encounter this.
  425. 4) CZ is a stable TSR but like all TSRs in a DOS system, unforseen events can
  426. take place that could conceivably cause the computer to crash. Therefore, it's
  427. recommended that you save your work often (you should do so whether a TSR is
  428. installed or not).
  429. 5) CZ currently doesn't reset the mouse. If you're having mouse trouble, you'll
  430. need to reset your mouse driver (type MOUSE at the C>). Many problems come from
  431. other programs not restoring the mouse cursor to its original state.
  432. See: About_CZ
  433. ~About_CZ
  434.               
  435.               
  436.                      CZ HELP                     
  437.               
  438.                                                  
  439.               
  440.       Context-sensitive Online Help Manager      
  441.               
  442.                                                  
  443.               
  444.                      for the                     
  445.               
  446.                                                  
  447.               
  448.                
  449.               
  450.               
  451.                
  452.                
  453.               
  454.                
  455.                
  456.               
  457.                
  458.                
  459.               
  460.                                                  
  461.               
  462.                 compiler libraries               
  463.               
  464.                                                  
  465.               
  466.        MS-DOS QuickBASIC/BASIC PDS version       
  467.               
  468.         (available for most DOS compilers)       
  469.               
  470.                                                  
  471.               
  472.            Copyright 1993  Cornel Huth           
  473.               
  474.                                                  
  475.               
  476. Ver 1.03         INT2F MuxID=C2         22-Apr-93
  477.               
  478. See: Specs_Overall
  479. ~is_BULLET - What?
  480. BULLET is a program module that handles the details of putting information to
  481. and getting information from your hard disk using a standard data file format
  482. called the Xbase DBF format with very fast and efficient index file routines.
  483. It can be used as-is by most DOS compilers.
  484. BULLET is written in 100% assembly language. Why? Two reasons. First, control.
  485. There's no compiler code or run-time library code in between BULLET and your
  486. data. Second, efficiency. BULLET knows exactly what it requires from the
  487. operating system and when. Result: fast, small, and robust applications.
  488. See: is_a_database
  489. ~is_a_database - What?
  490. A database is a collection of data arranged so that the it can be accessed as
  491. useful information. For example, let's say we have two files. Each consists of
  492. two fields. The first file has codenumber and score. The second file has a
  493. codenumber and name. Separately, the files are merely a collection of data.
  494. Together, however, they tie the name to the score:
  495.         score codenumber   codenumber name
  496.          99     100           100     John
  497.          87     155           105     Paul
  498.          66     125           110     George
  499.           :      :             :       :
  500. Codenumber 100 is John, who scored 99. The other members scores are not in the
  501. abbreviated data file listing.
  502. A database can be a single data file but more often it is a group of related
  503. data files and usually these data files are indexed by keys (in the index file,
  504. also called key file) so that very fast, direct access is possible.
  505. See: is_DBF
  506. ~is_DBF - What?
  507. DBF is the file extension of dBASE III-compatible data files (filename.DBF).
  508. The file format is used by dBASE IV, FoxPro and many other database programs.
  509. Many programs can also use the file format to import/export data using it.
  510. The DBF format is the most common data file format used on PCs.
  511. A DBF-compatible data file consists 3 distinct areas. First is the data header.
  512. This contains information such as the number of records in the file. Second is
  513. the field descriptors. These descriptors define the makeup of each field in the
  514. record. The third is the record area. Each record is a logical unit of data.
  515. For example, a record, all of which are made up of the same fields but with
  516. different data, could (conceptually) look like this:
  517.                field 1         field 2         field 3       field n
  518.            
  519.   record 1 
  520. Johnson         
  521. Larry          
  522. 465310555     ...
  523.            
  524.   record 2 
  525. Aberdeen        
  526. Zara           
  527. 465230555     ...
  528.            
  529.   record n
  530. See: is_a_Btree  Specs_DBF
  531. ~is_a_Btree - What?
  532. A b-tree is a sorting method ideally suited to data structures maintained on a
  533. hard disk. It is very fast on retrieval and is inherently self-balancing during
  534. inserts and deletes. Self-balancing ensures performance remains consistent.
  535. The reason the b-tree is ideally suited to hard disks is that, when looking for
  536. a particular key, most of the time involved in accessing the key is spent by
  537. the hard drive moving to various locations on the disk. The task of a good
  538. access method is to reduce the number of seeks that the disk must perform. The
  539. b-tree accomplishes this by maintaining several keys (perhaps 50) on each node,
  540. with the necessary pointers to previous and following nodes. A b-tree of order
  541. 20 (19 keys per node) can find a key in a file of 1,000,000 keys in a MAXIMUM
  542. of 5 disk accesses, where each disk access visits a node.
  543. 'BASIC program to find *max* seeks needed/avg time
  544. Keys& = 1000000: KeysPerNode = 19: AvgSR = 25
  545. Order = KeysPerNode + 1
  546. max = (LOG((Keys& + 1) / 2) / LOG(Order / 2))
  547. PRINT "Max nodes accessed for"; Keys; "keys & b-tree of order"; Order;
  548. PRINT "is"; max; "nodes"
  549. PRINT "Max disk time based on avg seek+read of"; AvgSR;
  550. PRINT "ms is"; AvgSR / 1000 * max; "seconds"
  551. See: is_a_network  Specs_Index
  552. ~is_a_network - What?
  553. A network is a group of computers able to communicate with one another. Often
  554. called a LAN (local area network), a network allows resources to be shared.
  555. Sharing resources can lead to problems if steps are not taken to ensure that
  556. two computers don't try to share the same resource at the same time. For
  557. example, say two computers try to change the same record in a file on a network
  558. drive. Let's say both users are accessing the number of widgets in inventory.
  559. The first user gets there a micro-second before the second and allocates the
  560. last widget in stock. The second user comes in right after and, since the first
  561. user has not yet updated the inventory, allocates the very same widget. One
  562. widget, two users. When the first user updates the inventory, widgets in
  563. inventory is changed to 0 (previous - 1). The second updates the inventory in
  564. the same manner and sets widgets to 1 less what it was when it started, or 0
  565. also. You see the problem.
  566. In order to successfully share a file on a network, the file must first be
  567. locked to a single user. Once that user has locked the file, he has sole access
  568. to the data within it and he will not experience the scenario above. When the
  569. user has completed the changes, he unlocks the file so that others may use it.
  570. See: is_file_locking
  571. ~is_file_locking - What?
  572. File locking is a means to obtain exclusive access to a file. This is needed in
  573. cases of multiple programs or users accessing a shared file at the same time.
  574. There are several methods to ensure only one process or user has access to a
  575. file. The first method is to open the file so that while the file is open only
  576. your program can access any part of it. This is simple to implement and the
  577. operating system handles the details of this. However, it requires your program
  578. to open/close files all the time since no other process may access the file
  579. while it is open.
  580. Another method is to use byte-level locks. Also managed by the OS, this method
  581. allows for restricting access to any particular region within the file. Which
  582. regions are to be locked is to be determined by your program, however, and it
  583. can be complex to perform multiple locks at the byte, field, or record level.
  584. Another use of the byte-level lock is to specify that all bytes within the file
  585. are to be locked. This greatly simplifies the process of obtaining a lock and
  586. has the advantage over a file access lock of not needing to open/close the file
  587. for each lock. It is very fast and easy to implement. BULLET offers all three
  588. lock types.
  589. See: is_NLS
  590. ~is_NLS - What?
  591. NLS stands for National Language Support. This feature is available in DOS 3.3
  592. and later. BULLET makes use of NLS by getting from DOS the current DOS country
  593. collate-sequence table. The collate table is used to properly sort mixed-case
  594. character strings and also foreign (or non-USA) language character strings
  595. according to that country's alphabet. This is an option but is recommended.
  596. In addition, BULLET provides for a programmer-supplied collate-sequence table.
  597. See: design_a_DB
  598. ~design_a_DB - How to
  599. To design a database, above all else, know what information you require from
  600. it. Having established what you need to know, collect the data that lets you
  601. formulate this into useful information.
  602. For example, you want to track a class of students and determine how well they
  603. achieve on tests. The criterion you use is the test score. You determine that
  604. your data is 1) students, 2) tests, and 3) test scores. Too simplify, you use
  605. a single 20-character field for student, a 1-character field for test number
  606. ("1" to the "n" tests), and a numeric field for test scores (0 to 100).
  607. Since the objective is to track students' scores, arrange the data so that
  608. output consists of each student's score in test order. Do this by specifying an
  609. index file containing an index based on the student's name and test number:
  610.   KeyExpression$ = "STUDENT + TEST"       'combine two character fields
  611. This is the reason that field 2, test number, is a character field. It can more
  612. easily be combined with other character fields than a numeric field. By using
  613. the routines of the database langauge, you can easily create the data and index
  614. files, add data, list student's scores, or make changes to the database. Note:
  615. these How_to examples are meant only to show the basis behind an operation.
  616. See: create_a_DB  CreateKXB
  617. ~create_a_DB - How to
  618. Having defined the database, create it. First, create the datafile based on the
  619. 3 fields you defined in your design. To do this, DIM an array for the field
  620. descriptors for the number of fields (see also CreateDataPack):
  621. DIM FD(1 TO 3) AS FieldDescTYPE
  622. FD(1).FieldName = "STUDENT" + STRING$(10,0)   'must be zero-filled
  623. FD(1).FieldType = "C"
  624. FD(1).FieldLength = CHR$(20)               
  625. FD(1).FieldDC = CHR$(0)                    
  626. The FD() is a structure element  
  627. FD(2).FieldName = "TEST" + STRING$(10,0)   
  628. in CDP (CreateDataPack) as in:   
  629. FD(2).FieldType = "C"                      
  630. CDP.Func=CREATEDXB               
  631. FD(2).FieldLength = CHR$(1)                
  632.   :        :                     
  633. FD(2).FieldDC = CHR$(0)                    
  634. CDP.FieldListPtrOff=VARPTR(FD(1))
  635. FD(3).FieldName = "SCORE" + STRING$(10,0)  
  636. CDP.FieldListPtrSeg=VARSEG(FD(1))
  637. FD(3).FieldType = "N"                      
  638.   :        :                     
  639. FD(3).FieldLength = CHR$(3)                
  640. FD(3).FieldDC = CHR$(0)
  641. Call CreateDXB to create the data file. To create the index file, first open
  642. the data file just created, then call CreateKXB to create the index file. Open
  643. the index file so we can use it (data file is already open).
  644. See: add_to_the_DB  CreateDXB
  645. ~add_to_the_DB - How to
  646. Once you have the database designed and the data and key files created and open
  647. you can start putting the student's test data into it. Note that the DBF-format
  648. requires that all data in a data file be in ASCII format. This means that we
  649. must convert the numeric test score into its ASCII form. BASIC has the STR$()
  650. function to do this. In addition, numbers generally should be right-justified
  651. in their field. BASIC has the RSET statement to do this:
  652. TYPE StudentRecordTYPE 'this structure is exactly how the record is on disk
  653. tag AS STRING * 1      'DBF delete tag used to identify deleted records
  654. sname AS STRING * 20   '--the tag is always present in any DBF record
  655. testn AS STRING * 1    '  don't forget to include it in all your TYPEs
  656. score AS STRING * 3
  657. END TYPE '25
  658. DIM SR AS StudentRecordTYPE
  659.      :
  660.    INPUT "Student name, test number, score:",n$,t$,s%
  661.    SR.sname = n$ : SR.testn = t$ : RSET SR.score = STR$(s%)
  662.    status = DoInsert(SR, keyhandle)
  663. LOOP UNTIL LEN(n$) = 0 OR (status <> 0)
  664. See: query_the_DB  InsertXB
  665. ~query_the_DB - How to
  666. Now that you have data in the database you want to see what's in there. Since
  667. the index file is in "STUDENT + TEST" order, the information we'll be getting
  668. out of the database is in Student name order, with each student's scores in
  669. test number order.
  670. If we want to look at all the students, we can use GetFirstXB to retrieve the
  671. first student's score for the first test. GetNextXB retrieves the next record
  672. (the first student's score for the second test), and so on. When all records
  673. have been retrieve GetNextXB returns an End Of File error code.
  674. If we want to look at a particular student's score only, we can use GetEqualXB
  675. to go directly to a student's first test score. GetNextXB get his next and so
  676. on until GetNextXB retrieves the next student's first test score. You can stop
  677. at this point (student names no longer match).
  678. We might also want to find all students who scored less than 65 on any test. To
  679. do this we can GetFirstXB, check SR.score for < 65 and if so print that record.
  680. Continue by using GetNextXB, printing each record that has a score < 65.
  681. See: update_the_DB  GetFirstXB
  682. ~update_the_DB - How to
  683. To update a particular record in the database we must first locate and identify
  684. it using one of the get routines such as GetEqualXB. The Get() routine return
  685. the record data, and also the physical record number of the record accessed,
  686. into the AccessPack RecNo. Having used one of the Get() routines to read the
  687. data record from disk to memory, you can make any changes to the data record in
  688. memory. E.g., if a student's score needs to be changed from a 69 to a 96, first
  689. find the record (and its RecNo), then update the score field:
  690.    INPUT "Student name, test number",n$,t$
  691.    SR.sname = n$ : SR.testn = t$
  692.    status = DoGetStudentTestScore(SR, keyhandle, Recno&)
  693.    DO UNTIL status <> 200   'student as entered not found, call search routine
  694.       status = DoFindStudentTestScore(SR, keyhandle, RecNo&)
  695.    LOOP
  696.    IF status = 0 THEN
  697.       PRINT "Student:" ; SR.sname ; " old score:" ; SR.score
  698.       INPUT "Enter new score:"; s% : RSET SR.score = STR$(val(s%))
  699.       status = DoUpdateTestScore(SR, keyhandle, Recno&)
  700.    ENDIF
  701. Any change to a key field will initiate a key file update automatically.
  702. See: delete_a_record  UpdateXB
  703. ~delete_a_record - How to
  704. To delete a particular record in the database we must first locate it using
  705. one of the get routines such as GetEqualXB. These Get() routines return the
  706. actual record number of the data record accessed by Get() into the AccessPack
  707. RecNo. Having used one of the Get() routines to find the data record, make a
  708. call to the delete function:
  709.    'delete all of Student's records, 1 record for each test he's taken
  710.    INPUT "Student name to delete",n$
  711.    SR.sname = n$
  712.    status = DoGetStudent(SR, keyhandle, RecNo&)
  713.    DO UNTIL status <> 200   'student as entered not found, call search routine
  714.       status = DoFindStudent(SR, keyhandle,RecNo&)
  715.    LOOP
  716.    DO
  717.       status = DoDeleteRecord(SR, RecNo&)  'does not affect key files
  718.       IF status = 0 THEN status = GetNextChkIfSameStudent(SR,keyhandle,RecNo&)
  719.    LOOP UNTIL status <> 0
  720. The DeleteRecordXB routine does not physically remove the record from the data
  721. file but instead tags it as being "deleted".
  722. See: BC_compile_with  DeleteRecordXB
  723. ~BC_compile_with - How to
  724. To create a stand-alone EXE file, compile your BASIC source as required. No
  725. special compiler switches are required. When your compiler is finished and has
  726. reported no errors during the compile, use the LINK program supplied with your
  727. compiler to resolve any external references in your BASIC program code that are
  728. dependant on the BULLET library code.
  729. For example, if you have a single-module BASIC source file called STUGRADE.BAS,
  730. compile it:
  731.  C>bc STUGRADE /o;
  732. If successful, use the LINK program to build the final EXE:
  733.  C>link STUGRADE,STUGRADE.EXE,nul,BULLET.LIB;
  734. If successful, link creates STUGRADE.EXE ready to be run at the DOS prompt.
  735. The BASIC runtime is also supported by BULLET. Just compile as you normally
  736. would (without the /o, of course).
  737. See: LIB_with
  738. ~LIB_with - How to
  739. BULLET.LIB is composed of many separate assembly language modules. All these
  740. modules have been combined into a single, easy-to-use .LIB library. While it
  741. is possible to combine, or add, other .OBJ files or even other .LIB files to
  742. BULLET.LIB, I do NOT, -NOT-, recommend that you do so.
  743. If you need to use two or more libraries with your programs, no problem, LINK
  744. can handle as many as you have. When LINK prompts you for a library file, just
  745. enter BULLET.LIB followed by any other library you need. For example:
  746.  C>LINK
  747.  Microsoft (R) Segmented-Executable Linker  Version 5.10
  748.  Copyright (C) Microsoft Corp 1984-1990.  All rights reserved.
  749.  Object Modules [.OBJ]: STUGRAD1+STUGRAD2+STUB
  750.  Run File [STUGRAD1.EXE]: STUGRADE.EXE
  751.  List File [NUL.MAP]: nul
  752.  Libraries [.LIB]: BULLET MOUSE;
  753. Consult your linker programs documentation for more.
  754. See: make_a_QLB
  755. ~make_a_QLB - How to
  756. If you use the QuickBASIC environment to program in, you need to build a .QLB
  757. so that you can call the BULLET routines. While QuickBASIC can load only a
  758. single QLB ( C>qb /L quicklib.qlb ), you can combine many LIB and OBJ modules
  759. to create the QLB. For example, to make a QLB of the BULLET.LIB, MOUSE.LIB,
  760. and STUB.OBJ modules:
  761.  C>link /QU BULLET.LIB+MOUSE.LIB+STUB, IDE.QLB, nul, BQLB45.LIB;
  762. Note the extension .LIB on the library modules. This is REQUIRED since LINK
  763. assumes .OBJ by default, as in the case of STUB, above. The quick library,
  764. BQLB45.LIB, is required for the Libraries: prompt. The exact name depends on
  765. the compiler version. Consult your compiler documentation for more.
  766. BASIC PDS note: BASIC PDS requires that all BASIC modules included into a QLB
  767. be compiled using the /Fs compiler switch. This instructs the compiler to
  768. generate code compatible with "far strings". Since BULLET is written entirely
  769. in assembly langauge, this is not an issue. However, if you start QBX.EXE with
  770. /L and get an INVALID FORMAT error, one of the modules in the .QLB file most
  771. likely was a BASIC module that was not compiled with the /Fs switch.
  772. See: LINK_with
  773. ~LINK_with - How to
  774. After successfully compiling your BASIC source code module(s), use the LINK
  775. program to build the EXE program file. For this example let's assume that you
  776. have 2 BASIC source code modules just compiled and their .OBJs available, the
  777. BULLET.LIB library, a stub object file called STUB.OBJ, and MOUSE.LIB.
  778. To build the final stand-alone EXE from this group of files, do the following:
  779.  C>link STUGRAD1+STUGRAD2+STUB,STUGRADE.EXE,nul,BULLET+MOUSE;
  780. The 3 object modules, STUGRAD1, STUGRAD2, and STUB, will have their entire code
  781. included in the EXE program, created as STUGRADE.EXE. The 2 library files,
  782. BULLET.LIB and MOUSE.LIB, will have only the code that is actually referenced
  783. by the 3 object modules included into the EXE program.
  784. If successful, link creates STUGRADE.EXE ready to be run at the DOS prompt.
  785. See: call_BULLET  AtExitXB
  786. ~call_BULLET - How to?
  787. BULLET is called through a single entry point. The only argument passed to it
  788. is a segmented far pointer to the control pack. The first two entries in this
  789. pack are the function to be performed and the function return status. BULLET
  790. is a FUNCTION call returning an INTEGER status value.
  791. Each function (or routine) uses a prescribed pack format. For example, some
  792. routines need only know the handle of the file, along with the function number
  793. itself. So, to flush a data file, for example, you would do the following:
  794.  DIM HP AS HandlePack           'could also DIM SHARED
  795.  HP.Func = FLUSHDHXB            'FLUSHDHXB is defined as a CONST in BULLET.BI
  796.  HP.Handle = File2FlushHandle   'the handle as returned from the Open() routine
  797.  stat = BULLET(HP)              'do the actual call to BULLET
  798. The value of stat is set to the completion code as returned by the FlushDHXB 
  799. routine. It is the same as the value returned in HP.Stat *IN ALL BUT A FEW*  
  800. cases: InsertXB, UpdateXB, ReindexXB, and LockXB. These routines return not  
  801. the actual error code, but rather a transaction index number of the access   
  802. that failed. See those routines for more information.                        
  803. See: is_BULLET  FlushDHXB
  804. ~Specs_Overall
  805. BULLET is dBASE III/III+/IV .DBF-compatible. This format is compatible with a
  806. large base of software programs including the latest database packages such as
  807. dBASE IV and FoxPro. Spreadsheet packages such as Excel and 1-2-3 can directly
  808. import BULLET DBF data files, too. And because of BULLET's versatility, it can
  809. also create very non-standard data files. This may be a useful feature if data
  810. secrecy is of concern.
  811. BULLET requires MS-DOS 3.30 or above. It uses 19K of code/static data space and
  812. requires at least 40K of workspace. 140K of workspace is ideal.
  813. Overall Specifications:
  814.               DBF           (per file)          INDEX
  815.       
  816.     Max records: 16,777,215                Max nodes: 65,535
  817.   Record length: 2-4000 (8192)              Max keys: 4,063,170
  818.      Max fields: 128 (255)                Key length: 1-64
  819.    Field length: 1-254 (255)          Max key fields: 16
  820. Total open index plus data files can be up to 255. Numbers in () indicate
  821. extended specifications.
  822. See: Specs_DBF
  823. ~Specs_DBF
  824. To remain compatible with other dBASE III .DBF platforms you should restrict
  825. your data files to the following specifications:
  826.  File ID byte: 3  (83hex if .DBF has memo field, not currently supported)
  827.  Max record size: 4000 bytes  Max fields/rec: 128   Max field size: 254 bytes
  828.  Allowable field name characters: A-Z and the _ (upper-case)
  829.  Allowable field types:
  830.   C-character, 1-254 bytes
  831.   D-date, 8 bytes, in the format YYYYMMDD (19920531)
  832.   L-logical, 1 byte, either space, "T" or "Y", "F" or "N"
  833.   M-memo, 10 bytes, used as pointer into .DBT file (currently not supported)
  834.   N-numeric, 1-19 bytes, ASCII format, uses explicit decimal if needed...
  835.     ...decimal places may be 0, or 2 to (field size - 3) but no more than 15
  836. Restrict all data in .DBF fields to ASCII. This means you should convert binary
  837. data to the equivalent ASCII representation, e.g., if you have the binary value
  838. 22154, it must first be converted to the string "22154" before you can store it
  839. to the .DBF data file. So, while your in-program code deals with binary data,
  840. your I/O code must convert it to/from ASCII. This is a dBASE-compatibility
  841. issue only. If you can forgo these requirements you can use binary fields, any-
  842. character field names, record sizes to 8192 bytes, and up to 255 fields.
  843. See: Specs_DBF_a                                                        -MORE-
  844. ~Specs_DBF_a
  845. A dBASE III .DBF is composed of 3 sections: the header, the field descriptors,
  846. and the data area.
  847. The header structure (first 32 bytes of file):
  848.     Name     Type   Offset  Meaning
  849.  FileID      byte        0  data file type id, 03 standard (43,63,83,88h)
  850.  LastYR      byte        1  last update year, binary
  851.  LastMo      byte        2  last update month, binary
  852.  LastDA      byte        3  last update day, binary
  853.  NoRecs      long        4  number of records in file
  854.  HdrLen      word        8  length of header, including field descriptors, +1
  855.  RecLen      word       10  length of data record including delete tag
  856.  internal    byte    12-31  reserved
  857. The last update values are updated to the current date whenever the .DBF file
  858. is flushed or closed. Likewise, the NoRecs value is updated whenever a record
  859. is added to the .DBF. The FileID is specified when you create the file, HdrLen
  860. and RecLen are computed and stored when the file is created, too.
  861. See: Specs_DBF_b                                                        -MORE-
  862. ~Specs_DBF_b
  863. The field descriptor format (follows header, one per field):
  864.     Name     Type   Offset  Meaning
  865.  FieldName   char        0  field name 10 ASCII characters, A-Z or _ (0-filled)
  866.         0T   byte       10  field name zero-termintor (must be 0)
  867.  FieldType   char       11  field type (C D L M N)
  868.  internal    long       12  reserved
  869.  FieldLen    byte       16  length of this field
  870.  FieldDC     byte       17  decimal count
  871.  internal    byte    18-31  reserved
  872.       
  873. The unused bytes in the FieldName must be set to zeroes (CHR$(0)).
  874. Each field is described by a 32-byte descriptor. The first field's descriptor
  875. starts right after the header proper, at offset +32. After the last field
  876. descriptor is data byte ASCII 13. (Note: the orginal dBASE III has a 0 byte
  877. following this ASCII 13.) Immediately following this is the actual record data.
  878. See: Specs_DBF_c                                                        -MORE-
  879. ~Specs_DBF_c
  880. The data record format:
  881. The first record is located at offset HdrLen (from the header). The first byte
  882. of each record is a delete tag. This tag is maintained by the BULLET routines.
  883. A space, ASCII 32, means the record is not deleted; an asterisk, ASCII 42,
  884. means the record has been deleted (marked as deleted, often this is used as a
  885. method to temporarily tag records, for whatever purpose).
  886. Following the tag is the data for each field, not delimited (i.e., the fields
  887. run together without anything separating them). The second record is at offset
  888. HdrLen+reclen. The start offset of any record in the file can be computed as
  889. (recordnumber - 1) * reclen + HdrLen. All data is in ASCII form.
  890. An EOF marker (ASCII 26) is placed at the end of the last record.
  891. See: Specs_Index
  892. ~Specs_Index
  893. BULLET uses a proprietary, modified b-tree index method to manage the index
  894. files. The supported key types are:
  895.     Type     Length  Meaning
  896.  Character     1-64  ASCII, NLS, or user-supplied sort table
  897.  Integer          2  signed or unsigned 16-bit value
  898.  Long Int         4  signed or unsigned 32-bit value
  899. In addition to the above types, BULLET allows for unique or duplicate keys in
  900. the index file. If duplicates are allowed, BULLET enumerates each key with an
  901. enumerator word (see FirstKeyXB).
  902. The key may be composed of up to 16 character fields or substrings within those
  903. fields. Numeric fields are considered character fields by BULLET unless the key
  904. is set to binary (see KeyFlags). Integer or LongInt binary keys can be composed
  905. of a single field only. The key expression is specified in text (e.g., "LNAME+
  906. SUBSTR(FNAME,1,1)+MI") and is fully evaluated when the index file is created.
  907. A BULLET index file is composed of 3 sections: the header, the collate-sequence
  908. table, and the node/key entry area.
  909. See: Specs_Index_a                                                      -MORE-
  910. ~Specs_Index_a
  911. The header structure:
  912.     Name     Type   Offset  Meaning
  913.  FileID      byte        0  index file type id, 20
  914.  RootNode    word        1  root node number
  915.  Keys        24bit       3  number of keys in index file
  916.  AvalNode    word        6  node number available for reuse
  917.  FreeNode    word        8  next free node number
  918.  KeyLen      byte       10  key length
  919.  NodeKeys    byte       11  number of keys that fit on a node
  920.  CodePage    word       12  code page ID
  921.  CtryCode    word       14  country code
  922.  internal    byte    16-21  reserved
  923.  KeyFlags    word       22  key flags
  924.  KeyExprn    byte   24-159  key expression
  925.  internal    byte      160  reserved
  926.  KeyXFlds    byte      161  number of fields used by key (1-16)
  927.  KeyXlate    byte  162-225  translated key expression
  928.  internal    byte  226-253  reserved
  929.  CTsize      word      254  collate-sequence table size
  930. See: Specs_Index_b                                                      -MORE-
  931. ~Specs_Index_b
  932. The collate-sequence table structure:
  933.  table      byte   256-511  sort weight table of ASCII character 0-255
  934. Node/key entry structure (first entry is in node #1, file offset 512):
  935.   2A  0A 00  KEY123  7B 00 00  12 00  KEY178  B2 00 00  0C 00 ...
  936.    1.   2.     3.       4.       5.     6.       7.       8.   9.
  937.       
  938.  1. Key count for that node (first byte of each node)
  939.  2. 16-bit node back pointer (for non-leaf nodes, 0 if leaf node)
  940.  3. First key value, "KEY123" in this case
  941.  4. 24-bit data record pointer (low word/hi byte) 7Bh = DBF record number 123
  942.  5. 16-bit node forward ptr/back ptr (for non-leaf nodes, 0 if leaf node)
  943.     --in this case, it indicates that the key following KEY123 is in node# 12h
  944.     --and also that the key before KEY178 is in that node as well
  945.  6. Second key (here "KEY178")
  946.  7. 24-bit data pointer (record number in DBF)
  947.  8. 16-bit forward node pointer (for non-leaf nodes, 0 if leaf node)
  948.  9. Repeat 6 to 8 for each key on node. (node size is 512 bytes)
  949. See: Specs_Index_c                                                      -MORE-
  950. ~Specs_Index_c
  951. As in many b-tree implementations, BULLET's index files maintain an average
  952. load percentage of approximately 66%. This means that in any given node, 66% of
  953. the available space is in use. The free space in the node is attributable to
  954. the constant reshaping of the file as keys are inserted or deleted, causing the
  955. nodes to be split and merged. A split will occur when an insert needs to add a
  956. key to an already full node; a merge will occur when a neighboring node is
  957. small enough to be merged into a just split node. This constant prune-and-graft
  958. of the b-tree results in a node load of about 66% (50% in degenerate cases such
  959. as with already sorted data). It's this aspect of the b-tree that makes it a
  960. consistent performer and a widely-used method of managing index files.
  961. The following formula can be used to determine the number of keys that an index
  962. file can hold:
  963.   MaxKeys = MaxNodes * MaxKeysPerNode * LoadFactor
  964.   MaxKeys = 65535 * 509/(keylen+5) * .66
  965. The load factor can be increased to ~95% by using the ReindexXB routine. This
  966. load factor results in superior retrieval speeds since there are more keys on
  967. each node. Insertion speed will be decreased, however, since splitting will
  968. occur more frequently, though perhaps not noticeably.
  969. See: Specs_Memory
  970. ~Specs_Memory
  971. BULLET allocates memory on an as-needed basis. When linked to an executable
  972. program, BULLET makes use of 17.5K of code space and about 1.5K of static
  973. DGROUP data space. To accomodate the wide variety of compilers, BULLET's API
  974. structure will have the linker included all of the library into your final EXE
  975. program.
  976. All runtime memory allocations are obtained from the operating system. This
  977. means that if your compiler generates code to allocate all the free memory at
  978. startup for its far heap, you need to instruct it to free up some memory for
  979. BULLET's use. In QuickBASIC you can use SETMEM(). You can also use the linker
  980. /CP:n option to limit the amount that the compiler-generated startup code
  981. allocates. The EXEHDR.EXE program can also be used to modify this amount. The
  982. linker /CP: option and the EXEHDR program both modify the EXE header. To
  983. determine if you need to release memory use the MemoryXB routine. It reports
  984. the operating system memory available for use by BULLET.
  985. The amount of memory that BULLET requires is based on which routines are used.
  986. See the next screen for a list of the routines that make malloc calls to the
  987. operating system and how much memory they require.
  988. (Most compilers don't grab all memory as QuickBASIC when it's using $DYNAMIC).
  989. See: Specs_Memory_a  MemoryXB                                           -MORE-
  990. ~Specs_Memory_a
  991. Routines making dynamic memory allocations and amount (within 
  992.  16 bytes):
  993.   Routine           Bytes        Basis
  994. InitXB                  272   permanent, released when program ends (JFTmode=1)
  995. BackupFileXB             32K  temp, released when routine exits
  996. CreateDXB        48+(NF*32)   temp, released when routine exits (NF=NoFields)
  997. CreateKXB               544   temp, released when routine exits
  998. OpenDXB     144+((1+NF)*32)   semi-permanent, released when file closed
  999. OpenKXB                1264   semi-permanent, released when file closed
  1000. PackRecordsXB      RL to 64K  temp, released when routine exits (RL=RecLength)
  1001. ReindexXB        32K to 128K  temp, released when routine exits
  1002. UpdateXB              2K+RL   temp, released when routine exits (RL=RecLength)
  1003. For example, when BackupFileXB is called it attempts to allocate 32K from the
  1004. OS. If 32K is not available, BackupFileXB returns with an error code of 8 (DOS
  1005. error #8, not enough memory). If you won't be using Backup or Reindex, BULLET
  1006. can make do with much less memory (use table above).
  1007. Needed stack space is 4K (max) for ReindexXB. Other routines can operate with
  1008. less than 1K of stack space. In other words, stack use is minimal.
  1009. See: Specs_OS_calls
  1010. ~Specs_OS_calls
  1011. BULLET makes use of the following operating system calls:
  1012. INT21/25 DOS_setvector                  INT21/44/0B DOS_setsharingretrycount
  1013. INT21/2A DOS_getdate                    INT21/48 DOS_malloc
  1014. INT21/30 DOS_version                    INT21/49 DOS_free
  1015. INT21/35 DOS_getvector                  INT21/51 DOS_getpsp
  1016. INT21/39 DOS_makedir                    INT21/56 DOS_renamefile
  1017. INT21/3D DOS_openfile                   INT21/59 DOS_getextendederror
  1018. INT21/3E DOS_closefile                  INT21/5A DOS_createtempfile
  1019. INT21/3F DOS_readfile                   INT21/5B DOS_createnewfile
  1020. INT21/40 DOS_writefile                  INT21/5C DOS_lockunlockfile
  1021. INT21/41 DOS_deletefile                 INT21/65/01 DOS_getextendedcountryinfo
  1022. INT21/42 DOS_movefileptr                INT21/65/06 DOS_getcollatesequencetable
  1023. INT21/44/09 DOS_isdriveremote           INT21/67 DOS_sethandlecount
  1024. INT21/44/0A DOS_isfileremote            INT2F/10/00 DOS_isshareinstalled
  1025. No other operating system calls are made. No BIOS calls are made.
  1026. See: Specs_Languages
  1027. ~Specs_Languages
  1028. BULLET is compatible with most DOS compilers. The only requirements are that
  1029. your compiler allow you to:
  1030.  1. Call a library routine via a FAR call using PASCAL calling convention
  1031.  2. Pass a far pointer (of the parameter pack) on the stack, by value
  1032.  3. Supply far pointers to the various pack parameters
  1033.  4. Be able to return an integer value from the FAR call
  1034.     (this is optional but recommended for the transaction-based routines)
  1035. These requirements can be met with most BASIC, C, and other-language DOS
  1036. compilers.
  1037. CZ online help is currently available in BASIC and C versions. Others are
  1038. pending. You should be able to do well with either of these versions using
  1039. other-language compilers since the only difference is the source code examples.
  1040. See: Specs_OSes
  1041. ~Specs_OSes
  1042. BULLET is currently available only for MS-DOS and compatible operating systems.
  1043. It requires DOS 3.3 or higher.
  1044. To provide efficient memory use, BULLET uses a single-buffer cache per index
  1045. file. The single-buffer cache also provides for very quick network access since
  1046. a minimum amount of memory needs to be flushed when releasing control of BULLET
  1047. files. For maximum speed, however, an external high-performance disk cache can
  1048. be used. Hyperdisk is a good choice (shareware, $50+). A properly configured
  1049. cache can increase BULLET's performance from 10 to 300%. The most improvement
  1050. is with the InsertXB routine. The least is with ReindexXB and PackRecordsXB,
  1051. which do most of their work in temporarily allocated memory. Hyperdisk is about
  1052. the best designed disk cache available for PCs. SmartDRV 4.x is also good.
  1053. If you do not use a disk cache then it's recommended that you set your BUFFERS=
  1054. statement in CONFIG.SYS to at least 20 or 30. Even without a disk cache, BULLET
  1055. is still very fast. Also, be sure to set your FILES= to the number of files
  1056. that you'll be opening at any one time. If you set FILES=20 you can have BULLET
  1057. open 14 files (CZ.COM uses 1 and DOS reserves 5 more). You can set FILES=255
  1058. allowing BULLET to open up to 249 files at one time.
  1059.                  DO NOT set FILES= to a value greater than 255.
  1060. See: Specs_Networks
  1061. ~Specs_Networks
  1062. BULLET currently operates on all DOS-compatible network platforms.
  1063. Be sure to install SHARE.EXE (or compatible) on the server and, if you are
  1064. mutlitasking, on your local machine. If you'll be opening many files you
  1065. should extended the default SHARE file-sharing information space and the number
  1066. of locks that can performed at one time. The DOS 5.0 default is /F:2048 and
  1067. /L:20. This allocates 2K for file-sharing info space and allows 20 consecutive
  1068. locks to be active. If the F: value is too low, error 5 (extended error 32) is
  1069. returned on an open attempt. If you extend the JFT in InitXB and plan to use
  1070. many files, say more than 50, be sure to extend /F: by 2K for every 50
  1071. additional files and set the /L: to the number of files you plan on having
  1072. open. If L: is too low, error 1 (ext err 36) is returned on a lock attempt.
  1073. As an example, if you'll be using 100 files, set FILES=106 in CONFIG.SYS, set
  1074. SHARE /F:4096 /L:106, and IP.JFTmode=1 for InitXB. These values are a minimum.
  1075. If you have more than one process active, you need to account for other apps.
  1076. Note that Windows always returns a "SHARE is installed" using the DOS detection
  1077. routines used by BULLET. To determine if SHARE is actually installed, attempt
  1078. to perform a lock using one of the LockXB routines. An error code indicates
  1079. that SHARE (or compatible) is not installed.
  1080. See: Specs_Performance
  1081. ~Specs_Performance
  1082.  Test: Reindex 1,000 to 1,000,000 records (BB_LAI10.BAS)
  1083.        DBF: extended DBF using binary sort field
  1084.        key: LONG+SIGNED+UNIQUE                        Machine: 486/33 SHO
  1085.  1Meg
  1086.                                                      *
  1087.      
  1088.      
  1089.                                     *
  1090.      
  1091.                    Records  Time  Reindex Rate
  1092.      
  1093.        *           -------  ----  ------------
  1094.  100k
  1095.   *                   1000   < 1  1000+/sec
  1096.      
  1097.                       5000     2    2500
  1098.      
  1099.  *                   10000     4    2500
  1100.      
  1101. *                    25000     7    3571   3500+ records indexed/second!
  1102.      
  1103.                      50000    14    3571   Times in table are in seconds
  1104.   10k
  1105. *                   100000    28    3571
  1106.      
  1107.                     200000    81    2469
  1108.      
  1109. *                   500000   355    1408
  1110.      
  1111.                    1000000  1124     890
  1112.    1k
  1113.      
  1114.  time (secs)  100       200       300       400       18:00     20:00 (min)
  1115. See: Specs_Perf_a                                                       -MORE-
  1116. ~Specs_Perf_a
  1117.  Test: Add 1,000 to 1,000,000 records (BB_LAI10.BAS)
  1118.        DBF: extended DBF using binary sort field
  1119.        key: not indexed                               Machine: 486/33 SHO
  1120.  1Meg
  1121.                                                       *
  1122.      
  1123.      
  1124.                          *
  1125.      
  1126.          *         Records  Time    Add Rate
  1127.      
  1128.                    -------  ----  ------------
  1129.  100k
  1130.     *                 1000   < 1  1000+/sec
  1131.      
  1132.                       5000     2    2500
  1133.      
  1134.   *                  10000     4    2500
  1135.      
  1136. *                    25000    12    2083   2000+ records added/second!
  1137.      
  1138.                      50000    24    2083   Times in table are in seconds
  1139.   10k
  1140. *                   100000    50    2000
  1141.      
  1142.                     200000   103    1942
  1143.      
  1144. *                   500000   262    1908
  1145.      
  1146.                    1000000   529    1890
  1147.    1k
  1148.      
  1149.  time (secs)  100       200       300       400        8:00     10:00 (min)
  1150. See: Specs_Perf_b                                                       -MORE-
  1151. ~Specs_Perf_b
  1152.  Test: Access 1,000 to 1,000,000 keys(*), keys+records(+) (BB_LGK10.BAS)
  1153.        DBF: extended DBF using binary sort field
  1154.        key: LONG+SIGNED+UNIQUE                        Machine: 486/33 SHO
  1155.  1Meg
  1156.                                          *            +
  1157.      
  1158.      
  1159.               *                          +
  1160.      
  1161.     *        +  Keys   Time  Access Rate   Keys+Recs Time  Access Rate
  1162.      
  1163.               -------  ----  -----------   --------- ----  ------------
  1164.  100k
  1165.  *   +           1000   < 1  1000+/sec         1000   < 1  1000+/sec
  1166.      
  1167.                 10000     1    10000          10000     6    1667
  1168.      
  1169.                100000    22     4545         100000    68    1471
  1170.      
  1171.                200000    49     4082         200000   144    1389
  1172.      
  1173.                500000   147     3401         500000   427    1171
  1174.   10k
  1175. *+            1000000   424     2358        1000000   948    1055
  1176.      
  1177.      
  1178.              Times for forward/reverse (Next/Prev) were similar (
  1179.      
  1180. +            Times in table are in seconds
  1181.    1k
  1182.      
  1183.  time (secs)  100       200       300       400       15:00     17:00 (min)
  1184. See: Specs_Perf_c                                                       -MORE-
  1185. ~Specs_Perf_c
  1186.  Test: Insert 1,000 random records to existing data/key files (BB_LAA10.BAS)
  1187.        DBF: extended DBF using binary sort field
  1188.        key: LONG+SIGNED+UNIQUE                        Machine: 486/33 SHO
  1189.  Base records/keys   Inserted   Time / Rate
  1190.  -----------------   --------   ----   ----
  1191.               1000       1000     15     67 records+keys inserted/second
  1192.              10000       1000     18     56 Times in table are in seconds
  1193.             100000       1000     19     53
  1194.             200000       1000     20     50
  1195.  This tests the InsertXB speed. A data file containing the base records and
  1196.  an index file containing the same number of keys has inserted into it 1000
  1197.  random keys and records. The records are added to the end of the data file
  1198.  and the keys are inserted into their appropriate place in the index file.
  1199.  Typically InsertXBs would be done online. The rate of 50 inserts/second at
  1200.  200,000 records would indicate a time of 0.02 seconds per insert on even a
  1201.  very large database (0.015 secs/insert @ 1000 records).
  1202. See: Specs_Perf_d                                                       -MORE-
  1203. ~Specs_Perf_d
  1204.  Test: Update 1,000 records by changing the key field (BB_LAU10.BAS)
  1205.        DBF: extended DBF using binary sort field
  1206.        key: LONG+SIGNED+UNIQUE                        Machine: 486/33 SHO
  1207.  Base records/keys    Updated   Time / Rate
  1208.  -----------------    -------   ----   ----
  1209.               1000       1000     50     20 records+keys updated/second
  1210.              10000       1000     59     17 Times in table are in seconds
  1211.             100000       1000    108      9
  1212.             200000       1000    126      8
  1213.  This tests the UpdateXB speed. A data file containing the base records and
  1214.  an index file containing the same number of keys has the first 1000 keys and
  1215.  records changed. This forces the old data record to be replaced, the old index
  1216.  key to be deleted, and a new key for the record to be inserted in the index
  1217.  file.
  1218.  Typically UpdateXBs would be done online. The rate of 8 updates/second at
  1219.  200,000 records would indicate a time of 0.125 seconds per update on even a
  1220.  very large database (0.05 secs/update @ 1000 records).
  1221. See: Specs_Overall
  1222. ~InitXB
  1223. Pack: InitPack          Src: InitXBsrc          Func:   0/System
  1224. Before using any routine you must initialize the BULLET file system.
  1225. If you want more than the standard number of file handles, set InitPack.JFTmode
  1226. to 1. This expands the current process's Job File Table to allow 255 open files
  1227. maximum.
  1228. On return the DOS version (INT21/30h) is in InitPack.DOSver. Major version in
  1229. the high byte. Minor in the low. The BULLET version (*100) is returned as is
  1230. the address of the ExitXB routine. You can use this address to register ExitXB
  1231. with your own _atexit function if your runtime library does not provide _atexit
  1232. already.
  1233. Note: _atexit is a routine available in most DOS, OS/2, and ANSI runtime
  1234. library code and is called just prior to the program ending. See AtExitXB for
  1235. information on what to do if your library does not have _atexit.
  1236. See: ExitXB
  1237. ~ExitXB
  1238. Pack: ExitPack          Src: ExitXBsrc          Func:   1/System
  1239. Before ending your program you should call ExitXB to close any open BULLET
  1240. files. This also will release any memory still allocated to those files.
  1241. This restores the default keyboard break handlers if they were changed.
  1242. In normal operation you would see to closing all files yourself. However, if
  1243. your program fails to reach the programmed end, it's very possible that files
  1244. may still be left open. It is essential that you properly close all BULLET
  1245. files before ending. There are two methods to achieve this:
  1246. 1. In BASIC use ON ERROR GOTO label, where label is in the main module. The
  1247. code at label would then call ExitXB.
  1248. 2. Use AtExitXB to automatically register ExitXB to be executed in the normal
  1249. shut-down code of the compiler. This method is preferred.
  1250. In the QB environment you can easily stop and restart the executing program
  1251. without having reached the end of the program where you call ExitXB. Previously
  1252. opened BULLET files remain open and memory used remains allocated. Eventually
  1253. you will run out of files or out of memory. Use AtExitXB to prevent this.
  1254. See: AtExitXB
  1255. ~AtExitXB
  1256. Pack: ExitPack          Src: AtExitXBsrc        Func:   2/System
  1257. Used to automatically close all BULLET files, release allocated memory, and
  1258. restore the default Break handlers when your program ends. Your compiler
  1259. generates specific code to be executed in the course of ending your program.
  1260. AtExitXB registers the ExitXB routine to be performed in this compiler-
  1261. generated code.
  1262. This routine is standard in most DOS, OS/2, and ANSI runtime libraries. If   
  1263. yours does not have _atexit, then you must link with the supplied            
  1264. NOATEXIT.OBJ file:                                                           
  1265.                                                                              
  1266. C>link YOURPRG + NOATEXIT, ...                                               
  1267. You can tell if your compiler doesn't supply _atexit at link time. LINK reports
  1268. '_atexit' : unresolved external. Add NOATEXIT.OBJ as described above.
  1269. Be sure that your _atexit routine is for the medium, large, or huge memory
  1270. models since BULLET uses multiple code segments and far calls.
  1271. See: MemoryXB  ExitXB  BreakXB
  1272. ~MemoryXB
  1273. Pack: MemoryPack        Src: MemoryXBsrc        Func:   3/System
  1274. This is the only BULLET routine that can be used before InitXB. It reports the
  1275. largest free block of memory available from the OS. This memory does not
  1276. include fragmented memory or UMB memory that BULLET can and will use.
  1277. Some compilers provide their own memory management and thus will use most or 
  1278. all of the contiguous memory when its program loads. BULLET, however,        
  1279. allocates memory on an as-needed basis, directly from the OS, and releases it
  1280. back to the OS as soon as it is no longer needed. If the memory amount       
  1281. returned by MemoryXB is low, your compiler's startup code has pre-allocated  
  1282. all OS memory. If the memory available from the OS is less than your         
  1283. application needs, you need to instruct your program to release some of the  
  1284. memory back to the OS so BULLET can use it. For QuickBASIC and BASIC PDS, see
  1285. the BASIC function SETMEM().                                                 
  1286. With DOS able to use UMB memory, memory for BULLET requests may be provided
  1287. from this region. You can use StatPack.HereSeg from StatXB to locate from which
  1288. segment address the allocations are being made. Anything above C800h is UMB.
  1289. See: BreakXB  StatXB  OpenDXB  OpenKXB
  1290. ~BreakXB
  1291. Pack: BreakPack         Src: BreakXBsrc         Func:   4/System
  1292. Disables system response to Control-C and Control-Break keys preventing users
  1293. from inadvertently exiting the program without first doing a BULLET shutdown.
  1294. It's REQUIRED that you reinstate the default break handlers with this routine
  1295. before ending your program. ExitXB automatically reinstates the default break
  1296. handlers.                                                                    
  1297. This routine will not disable Control-Alt-Delete (a warm-boot). If the user is
  1298. at this point, he may prefer to exit via a warm-boot rather than reset the
  1299. machine.
  1300. Also, this routine does not prevent QuickBASIC and BASIC PDS from terminating
  1301. a program at an INPUT statement. This is because these versions of BASIC are
  1302. using their own method of INPUT aside from DOS. If AtExitXB has been issued,
  1303. all BULLET files will be properly closed even if *User Break* occurs.
  1304. This routine will not surpress the ^C displayed by DOS. If you don't want the
  1305. ^C to be displayed move the cursor to a location off-screen, say, row 26.
  1306. See: BackupFileXB  ExitXB
  1307. ~BackupFileXB
  1308. Pack: CopyPack          Src: BackupFileXBsrc    Func:   5/System
  1309. Copy an open BULLET key or data file. BULLET repacks and reindexes files in-
  1310. place, requiring less disk space to perform the function. BackupFileXB allows
  1311. you to safely copy a file before doing this.
  1312. This function is recommended prior to packing a data file with PackRecordsXB 
  1313. since the data is very valuable. There is probably little need to do so when 
  1314. reindexing an index file since index files can be constructed very easily    
  1315. from the data file.                                                          
  1316. See: StatHandleXB  PackRecordsXB  ReindexXB
  1317. ~StatHandleXB
  1318. Pack: StatHandlePack    Src: StatHandleXBsrc    Func:   6/System
  1319. Get information on a DOS file handle number to determine if it is a BULLET file
  1320. and if so, if that file is a BULLET key or data file.
  1321. If the returned ID value is 0, the handle is to a BULLET index file. ID=1 then
  1322. the handle is a BULLET .DBF file. ID= -1 then the handle is not a BULLET file.
  1323. See: CreateDXB  StatDXB  StatKXB
  1324. ~GetExtErrorXB
  1325. Pack: XErrorPack        Src: GetExtErrorXBsrc   Func:   7/System
  1326. Get the extended error information for the last operation. This information
  1327. includes the extended error code, the error class, the recommended action, and
  1328. the location of the error. See Errors_DOS for the extended error meaning an
  1329. Errors_DOS_c for the class, action, and locus code meanings.
  1330. Note that on fatal DOS errors, such as an open floppy drive door, the extended
  1331. error code returned is 83 - fail on INT24. This indicates that the INT24
  1332. handler was invoked by DOS and that the INT24 handler told DOS to ignore the
  1333. error. (BULLET invokes its own INT24 handler each time it accesses the DOS file
  1334. system and restores it promptly after the access.) In such cases, this extended
  1335. error code is less informative than the standard return code and, the other
  1336. 'extended' information should be disregarded. (In fatal DOS errors the standard
  1337. return code IS the extended error code.)
  1338. This routine returns the extended error information for the LAST DOS system  
  1339. error. This information remains the same until the next DOS system error.    
  1340. See: CreateDXB  Errors_DOS
  1341. ~DVmonCXB
  1342. Pack: DVmonPack         Src: DVmonCXBsrc        Func:   9/DEBUG
  1343. Control BULLET debug monitor.
  1344. This routine is available only in the debug engine.                          
  1345. The monitor displays in realtime the state of a data file handle, or an index
  1346. and data file handle pair if an index handle is specified. DVmonCXB is best
  1347. used on dual-display systems in which the video output is sent to the secondary
  1348. video monitor. In any case, a 4000-byte screen image is updated in real-time.
  1349. To use the monitor, set mode=1, handle=file to monitor, and VideoSeg=segment
  1350. address of 4000-byte area. The typical VideoSeg would be to video memory. If
  1351. you have a color system as the main monitor and a mono as the secondary, set
  1352. VideoSeg=&HB000. Detail system stats are continually updated to the secondary
  1353. monitor. If you have a single monitor with at least 2 video pages, set VideoSeg
  1354. to your base address plus the page size\16, typically &HB800+(4096\16). If you
  1355. have only a single-page video system, you can allocate a 4000-byte memory area
  1356. and update the video manually by moving it to your video display (80x25).
  1357. See: CreateDXB  StatDXB  StatKXB
  1358. ~CreateDXB
  1359. Pack: CreateDataPack    Src: CreateDXBsrc       Func:  10/Mid-level
  1360. Create a new BULLET .DBF data file. Before using this routine allocate a field
  1361. description array of TYPE FieldDescTYPE for at least as many fields as are in
  1362. the record.
  1363. Conventional dBASE .DBF files have a FileID=3. Other possible FileIDs that you
  1364. may come across are (in hex):
  1365.  43h \__ are special-use Xbase IV DBF files, BULLET can process these file IDs
  1366.  63h /                                    since they are similar to ID type 3
  1367.  83h --- this DBF file has an Xbase III/III+ memo field/file
  1368.  88h --- this DBF file has an Xbase IV memo field/file
  1369. In creating your .DBF files, specify FileID=3 to ensure compatibility across 
  1370. Xbase versions.                                                              
  1371. BULLET makes no special use of the FileID byte.
  1372. See: OpenDXB  FieldDescTYPE  CreateKXB
  1373. ~OpenDXB
  1374. Pack: OpenPack          Src: OpenDXBsrc         Func:  11/Mid-level
  1375. Open an existing .DBF data file for use. You need to specify two things, the
  1376. filename and the DOS file access mode. If the open succeeds, the DOS file
  1377. handle is returned. Use this handle for all further access to this file.
  1378. Each .DBF data file you open allocates 144+((1 + number of fields) * 32) bytes
  1379. for internal use. This memory is not deallocated until you close the file with
  1380. CloseDXB or execute ExitXB.
  1381. You must open the data file before you can open (or create) any of its index
  1382. files.
  1383. See: CloseDXB  OpenKXB
  1384. ~CloseDXB
  1385. Pack: HandlePack        Src: CloseDXBsrc        Func:  12/Mid-level
  1386. Close an existing .DBF data file for use. Closing the file updates the file
  1387. header and deallocates the memory used by this file.
  1388. You MUST close all BULLET files before ending your program or file corruption
  1389. may occur. To ensure that all files are closed in the event of an unscheduled
  1390. program termination, use AtExitXB.                                           
  1391. See: StatDXB  ExitXB  CloseKXB
  1392. ~StatDXB
  1393. Pack: StatDataPack      Src: StatDXBsrc         Func:  13/Mid-level
  1394. Get basic information on the BULLET .DBF data file handle specified.
  1395. Information returned includes the number of records in the file, the record
  1396. length, number of fields per record, and the date the file was last updated.
  1397. Typically, your program will keep track of whether a particular handle belongs
  1398. to a data file or a key file. In cases where this is not possible, call the
  1399. StatHandleXB routine to determine what file type a handle is.
  1400. Note that a just-created data file will have the LastUpdate date set to 0/0/0.
  1401. See: ReadDHXB  StatKXB  StatHandleXB
  1402. ~ReadDHXB
  1403. Pack: HandlePack        Src: ReadDHXBsrc        Func:  14/Mid-level
  1404. Reload the disk copy of the data header for the opened .DBF data file handle
  1405. to the internal copy.
  1406. In single-user, single-tasking systems this routine is not needed. However, in
  1407. a multi-user or multi-tasking system it's possible, and desirable, for two or
  1408. more programs to use the same data file. Consider this scenario: A data file
  1409. has 100 records. Two programs access this data file, both opening it. Program 1
  1410. locks the file, adds a new record, then flushes and unlocks the file. Program 1
  1411. knows that there are now 101 records in the file. However, Program 2 is not
  1412. aware of the changes that Program 1 made--it thinks that there are still 100
  1413. records in the file. This out-of-sync situation is easily remedied by having
  1414. Program 2 reload the data header from the file on disk.
  1415. How does Program 2 know that it needs to reload the header? It doesn't. Instead
  1416. BULLET uses a simple yet effective approach when dealing with such problems.
  1417. Whenever your program locks a file, BULLET automatically reloads the header.
  1418. Whenever you unlock a file, BULLET automatically flushes the header.
  1419. See: FlushDHXB  ReadKHXB  LockXB
  1420. ~FlushDHXB
  1421. Pack: HandlePack        Src: FlushDHXBsrc       Func:  15/Mid-level
  1422. Write the internal copy of the data header for the opened .DBF data file handle
  1423. to disk. The actual write occurs only if the header has been changed.
  1424. This is to ensure that the data header on disk matches exactly the data header
  1425. that is being maintained by BULLET. Also, this routine updates the operating
  1426. system's directory entry for this file.
  1427. Assume the following: A data file with 100 records. Your program opens the data
  1428. file and adds 1 record. Physically, there are 101 records on disk. However, the
  1429. header image of the data file on disk still reads 100 records. This isn't a
  1430. problem, BULLET uses its internal copy of the data header and the internal copy
  1431. does read 101 records. BUT, if there were a system failure now, the disk image
  1432. would not get updated. After the system restart, BULLET opens the file, reads
  1433. the header and thinks that there are 100 records. You lost a record. Now, if
  1434. after that add above, your program issued a FlushDHXB, the header on disk is
  1435. refreshed with the internal copy, keeping the two in-sync. Also, the routine
  1436. updates the DOS directory entry, keeping things neat there as well. Still, it
  1437. doesn't come without cost: flushing will take additional time, therefore, you
  1438. may elect to flush periodically, or whenever the system is idle.
  1439. See: CopyDHXB  ReadDHXB  FlushKHXB  LockXB
  1440. ~CopyDHXB
  1441. Pack: CopyPack          Src: CopyDHXBsrc        Func:  16/Mid-level
  1442. Copy the .DBF file structure of an open data file to another DOS file.
  1443. This routine makes it easy for you to duplicate the structure of an existing
  1444. .DBF file without having to specify all the information needed by CreateDXB.
  1445. The resultant .DBF will be exactly like the source, including number of fields
  1446. and field descriptions. It will contain 0 records.
  1447.      
  1448. See: ZapDHXB  CopyKHXB
  1449. ~ZapDHXB
  1450. Pack: HandlePack        Src: ZapDHXBsrc         Func:  17/Mid-level
  1451. Delete all records for a .DBF data file.
  1452. This routine is similar to CopyDHXB except for one major difference: ALL DATA
  1453. RECORDS IN THE *SOURCE* FILE ARE PHYSICALLY DELETED, so be *careful*.
  1454. If you have a .DBF file with 100 records and use ZapDHXB on it, all 100 records
  1455. will be physically deleted and the file truncated to 0 records. There is no
  1456. return from this routine. All data is gone.
  1457.                            
  1458.                            
  1459. * C A U T I O N *
  1460.                            
  1461.      
  1462. See: CreateKXB  CopyDHXB  ZapKHXB
  1463. ~CreateKXB
  1464. Pack: CreateKeyPack     Src: CreateKXBsrc       Func:  20/Mid-level
  1465. Create a new BULLET key file. Before you can create a key file, you must first
  1466. have opened (and have created if necessary) the BULLET .DBF data file that it
  1467. is to index. (BULLET couples index and data files tightly.)
  1468. To create the key file, you need to provide the key expression, key flags, .DBF
  1469. file link handle, and optionally, the code page ID, country code, and collate
  1470. table.
  1471.                                 Key Expression
  1472. The key expression is an ASCII character string composed of the elements that
  1473. are to make up this index file's key. The key can be composed of any or all of
  1474. the fields in the .DBF data record or sub-strings within any of those fields.
  1475. Two functions are supported in evaluating a key expression. These are SUBSTR()
  1476. and UPPER(). SUBSTR() is similar to BASIC's MID$() in that it extracts part of
  1477. a string starting at a particular position for x number of characters. UPPER()
  1478. is similar to UCASE$() in that it converts all lower-case letters to their
  1479. upper-case equivalent. Since BULLET supports NLS, UPPER() conversion is not
  1480. required for proper sorting of mixed-case text strings.
  1481. See: CreateKXB_a  CreateDXB                                             -MORE-
  1482. ~CreateKXB_a
  1483. All names used in the key expression must be a valid field name in the DBF data
  1484. file. Some sample key expressions given that the .DBF has the following fields:
  1485.  Fields...             Valid key expressions
  1486.      
  1487.  FNAME C 25 0       kx = "LNAME"
  1488.  LNAME C 25 0       kx = "LNAME+FNAME"
  1489.  SSN   C  9 0       kx = "SUBSTR(LNAME,1,4)+SUBSTR(FNAME,1,1)+SUBSTR(SSN,6,4)
  1490.  DEPT  N  5 0       kx = "UPPER(LNAME+FNAME)"  (for non-NLS index files)
  1491.   :     :           kx = "DEPT+SSN" (N- + C-type is valid for non-binary keys)
  1492.                                     Key Flags
  1493. The key expression is used in conjunction with the key flags to determine the
  1494. type of key generated.
  1495. First, if your index file is to disallow duplicate keys, add 1 to KeyFlag.
  1496. If you have a key composed of a character field(s) or portions thereof, you
  1497. specify a KeyFlag = 2. This instructs BULLET that the sort order is left-to-
  1498. right (proper mixed-case sorting is available, see code page ID).
  1499. See: CreateKXB_b                                                        -MORE-
  1500. ~CreateKXB_b
  1501. If you have a key composed of a numeric field(s) or portions thereof, you can
  1502. also specify a KeyFlag = 2. This instructs BULLET to treat the numeric field
  1503. as a regular character field for sorting. To ensure proper sorting, you must
  1504. decimal-align the +numeric strings in the .DBF data field, i.e., right-justify
  1505. the numeric strings (dBASE .DBF numeric strings are stored as ASCII strings).
  1506. These non-binary numeric fields are just like character fields to BULLET.
  1507. In addition, if you have a key composed of a SINGLE numeric field (fld type N)
  1508. and the field is an integer (NO DECIMAL POINT), you can specify a KeyFlag of 16
  1509. or 32. KeyFlag=16 is for a field known to be in word/integer range; KeyFlag=32
  1510. if the field is known to be in LongInt range. These KeyFlag values instruct
  1511. BULLET to sort the key as a 16/32-bit BINARY value. It also stores the key as a
  1512. 16- or 32-bit value (only 2 or 4 bytes) in the index, eventhough the data field
  1513. is in ASCII (keyflag=16 or 32).
  1514. Although not dBASE compatible, you may use BINARY FIELDS in your data records.
  1515. dBASE always has ASCII data in the data fields, even if the field is numeric.
  1516. For example, an N type field of 8.2 is stored as an ASCII text string in the
  1517. data record, say, a string like " 1100.55". If you want dBASE compatibility
  1518. your field data must also be ASCII. However, if you can forgo this requirement,
  1519. you can use binary values in the fields.
  1520. See: CreateKXB_c                                                        -MORE-
  1521. ~CreateKXB_c
  1522. To do this you must specify a field type of "B" (actually, anything but a "N")
  1523. and, IF IT IS TO BE USED AS A KEY FIELD, also set the 16- or 32-bit KeyFlag.
  1524. Unique and signed may also be flagged. The field length for a "B" field type is
  1525. 2 or 4. Make sure the key flags match (2 if cINTEGER, 4 if cLONG).
  1526. If you specify a binary key flag (for either N or B field types), you must also
  1527. specify whether the field is to be treated as a signed or unsigned value. If
  1528. values less than 0 are possible, add to KeyFlag the hex number &H8000.
  1529.  KeyFlag = cUNIQUE + cCHAR              'unique character key (NLS sort)
  1530.  KeyFlag = cINTEGER + cUNIQUE           'unique unsigned integer (binary sort)
  1531.  KeyFlag = cUNIQUE + cSIGNED + cLONG    'unique signed long
  1532.  KeyFlag = cCHAR                        'character key with duplicates allowed
  1533.  KeyFlag = cCHAR + cINTEGER             'THIS IS AN INVALID KEY FLAGS!
  1534.  KeyFlag = cLONG                        'unsigned long (dups allowed)
  1535. The following values are defined in BULLET.BI (and BULLET.H):
  1536.   cUNIQUE=1, cCHAR=2, cINTEGER=&H10, cLONG=&H20, cNLS=&H4000, cSIGNED=&H8000
  1537. The NLS flag is assigned by BULLET. StatKXB is used to query KeyFlags.
  1538. See: CreateKXB_d                                                        -MORE-
  1539. ~CreateKXB_d
  1540. The key expression you specify may be up to 136 characters, and evaluate out to
  1541. 64 bytes (62 bytes if unique key is not specified). I.e, kx$ = "SUBSTR(..." can
  1542. be up to 136 characters, and that the actual key built from this expression can
  1543. be no longer that 64 bytes, or 62 if you did not specify UNIQUE. In general,
  1544. shorter keys (the key itself, not the expression) offer better performance.
  1545.                          DBF File Link Handle (XBlink)
  1546. Since BULLET evaluates the key expression at CreateKXB, it must have access to
  1547. the DBF file to verify that the key expression is valid. You must therefore
  1548. supply CreateKXB with the OS file handle of the opened DBF data file.
  1549. National Language Support (NLS)
  1550. With DOS 3.3 and later, NLS is available. BULLET uses NLS to build the collate
  1551. sequence table that it uses to ensure proper sorting of mixed-case keys as well
  1552. as the sorting of foreign language alphabets. In order for BULLET to use the
  1553. proper collate table, it must know what code page ID and coutry code to use.
  1554. This table is made part of the index file so that all subsequent access to the
  1555. index file maintains the original sort order, even if the MIS shop is moved to
  1556. another location/computer system using another country code/code page.
  1557. See: CreateKXB_e                                                        -MORE-
  1558. ~CreateKXB_e
  1559.                                 Code Page ID
  1560. To use the default code page ID of the computer in use, specify a code page ID
  1561. of -1. This instructs BULLET to use the collate-sequence table as provided by
  1562. MS-DOS running on the machine. You may also specify the code page ID for BULLET
  1563. to use, but only if support for the code page ID is available on your machine.
  1564. Look in your DOS manual under CUSTOMIZING FOR INTERNATIONAL USE for specific
  1565. code page IDs and country codes. See also the COUNTRY and NLSFUNC commands.
  1566. You may also specify a code page ID = 0 in which case no collate table is used.
  1567.                                 Country Code
  1568. To use the default country code of the computer in use, specify a country code
  1569. of -1. This instructs BULLET to use the collate-sequence table as provided by
  1570. MS-DOS running on the machine. You may also specify the country code for BULLET
  1571. to use, but only if support for the country code is available on your machine.
  1572. Look in your DOS manual under CUSTOMIZING FOR INTERNATIONAL USE for specific
  1573. code page IDs and country codes. See also the COUNTRY and NLSFUNC commands.
  1574. You may also specify a country code = 0 in which case no collate table is used.
  1575. Typically, you set CodePageID = -1, CoutryCode = -1 and CollatePtr = 0.
  1576. See: CreateKXB_f                                                        -MORE-
  1577. ~CreateKXB_f
  1578.                          User-specified Collate Table
  1579. If you are to use a MS-DOS supplied collate table (BOTH codepage ID and country
  1580. codes are non-zero) then you do not need to specify a collate table--DOS will.
  1581. The option to allow a user-specified collate table is to work around some DOS
  1582. versions supplying incorrect collate tables. If you find that the DOS-supplied
  1583. collate table is not valid (it's stored in the second sector of the file) for
  1584. your country, you can supply the table to be used by pointing the CollatePtr
  1585. variables to your in-memory version of a valid collate table. If you want to
  1586. use the DOS-supplied collate table, you MUST set the CollatePtr variables = 0.
  1587. Note: The collate table is a 256-byte table that contains the sort value of
  1588. each character (0-255). For example, the first byte would be 0, second would
  1589. be 1, and so on. Values for characters up to the lower-case letters (ASCII 97)
  1590. are usually as you would expect: "A" has a value of 65. However, the lower-case
  1591. letters have the same value as their upper-case counterparts: "a" also has a
  1592. value of 65. BULLET uses this collate table to ensure proper sorting.
  1593. If you specify EITHER code page ID OR country code = 0 then no collate table
  1594. is used or built. Instead, sorting is done by standard ASCII sort. This is
  1595. somewhat faster but less versatile. Use UPPER() for mixed-case sort if needed.
  1596. See: OpenKXB  CreateKXB
  1597. ~OpenKXB
  1598. Pack: OpenPack          Src: OpenKXBsrc         Func:  21/Mid-level
  1599. Open an existing key file for use.
  1600. Each key file that you open allocates 1264 bytes for internal use. This memory
  1601. is not deallocated until you close the file with CloseKXB or execute ExitXB.
  1602. You must open the data file before you can open its related index file
  1603. because you must supply the handle of the data file that this index files
  1604. indexes.
  1605. See: CloseKXB  OpenDXB
  1606. ~CloseKXB
  1607. Pack: HandlePack        Src: CloseKXBsrc        Func:  22/Mid-level
  1608. Close an open key file. Closing the file updates the file header and
  1609. deallocates the memory used by this file.
  1610. You MUST close all BULLET files before ending your program or file corruption
  1611. may occur. To ensure that all files are closed on the event of an unscheduled
  1612. program termination, use AtExitXB.                                           
  1613. See: StatKXB  ExitXB  CloseDXB
  1614. ~StatKXB
  1615. Pack: StatKeyPack       Src: StatKXBsrc         Func:  23/Mid-level
  1616. Get basic information on a BULLET key file handle specified. Information
  1617. returned includes the number of keys in the file, the key length, the data file
  1618. handle for this key, the last accessed record number of that data file, NLS
  1619. information, and the key flags.
  1620. Typically, your program will keep track of whether a particular handle belongs
  1621. to a key file or a data file. In cases where this is not possible, call the
  1622. StatHandleXB routine to determine what file type a handle is.
  1623. See: ReadKHXB  StatDXB  StatHandleXB
  1624. ~ReadKHXB
  1625. Pack: HandlePack        Src: ReadKHXBsrc        Func:  24/Mid-level
  1626. Reload the disk copy of the key header for the opened key file handle to the
  1627. internal copy.
  1628. In single-user, single-tasking systems this routine is not needed. However, in
  1629. a multi-user or multi-tasking system it's possible, and desirable, for two or
  1630. more programs to use the same data file. Consider this scenario: A key file has
  1631. 100 keys. Two programs access this key file, both opening it. Program 1 locks
  1632. the file, adds a new key, then flushes and unlocks the file. Program 1 knows
  1633. that there are now 101 keys in the file. However, Program 2 is not aware of the
  1634. changes that Program 1 made--it thinks that there are still 100 keys in the
  1635. file. This out-of-sync situation is easily remedied by having Program 2 reload
  1636. the key header from the file on disk.
  1637. How does Program 2 know that it needs to reload the header? It doesn't. Instead
  1638. BULLET uses a simple yet effective approach when dealing with such problems.
  1639. Whenever your program locks a file, BULLET automatically reloads the header.
  1640. Whenever you unlock a file, BULLET automatically flushes the header.
  1641. See: FlushKHXB  ReadDHXB  FlushDHXB  LockXB
  1642. ~FlushKHXB
  1643. Pack: HandlePack        Src: FlushKHXBsrc       Func:  25/Mid-level
  1644. Write the internal copy of the key header for the opened key file handle to
  1645. disk. The actual write occurs only if the header has been changed.
  1646. This is to ensure that the key header on disk matches exactly the key header
  1647. that is being maintained by BULLET. Also, this routine updates the operating
  1648. system's directory entry for this file.
  1649.      
  1650. Assume the following: A data file with 100 keys. Your program opens the key
  1651. file and adds 1 key. Physically, there are 101 keys on disk. However, the
  1652. header image of the data file on disk still reads 100 keys. This isn't a
  1653. problem, BULLET uses its internal copy of the key header and the internal copy
  1654. does read 101 keys. BUT, if there were a system failure now, the disk image
  1655. would not get updated. After the system restart, BULLET opens the file, reads
  1656. the header and thinks that there are 100 keys. You lost a key. Now, if after
  1657. that add above, your program issued a FlushKHXB, the header on disk is
  1658. refreshed with the internal copy, keeping the two in-sync. Also, the routine
  1659. updates the DOS directory entry, keeping things neat there as well. Still, it
  1660. doesn't come without cost: flushing will take additional time, therefore, you
  1661. may elect to flush periodically, or whenever the system is idle.
  1662. See: CopyKHXB  ReadKHXB  FlushDHXB  LockXB
  1663. ~CopyKHXB
  1664. Pack: CopyPack          Src: CopyKHXBsrc        Func:  26/Mid-level
  1665. Copy the key file structure of an open key file to another DOS file.
  1666. This routine makes it easy for you to duplicate the structure of an existing
  1667. key file without having to specify all the information needed by CreateKXB.
  1668. The resultant key file will be exactly like the source, including key flags and
  1669. key expression. It will contain 0 keys.
  1670.      
  1671. See: ZapKHXB  CopyKHXB
  1672. ~ZapKHXB
  1673. Pack: HandlePack        Src: ZapKHXBsrc         Func:  27/Mid-level
  1674. Delete all keys for a key file.
  1675. This routine is similar to CopyKHXB except for one major difference: ALL KEYS
  1676. IN THE *SOURCE* FILE ARE PHYSICALLY DELETED, so be *careful*.
  1677. If you have a key file with 100 keys and use ZapKHXB on it, all 100 keys will
  1678. be physically deleted and the file truncated to 0 keys. There is no return from
  1679. this routine. All data is gone.
  1680.                            
  1681.                            
  1682. * C A U T I O N *
  1683.                            
  1684.      
  1685. See: GetDescriptorXB  CopyKHXB  ZapDHXB
  1686. ~GetDescriptorXB
  1687. Pack: DescriptorPack    Src: GetDescriptorXBsrc Func:  30/Mid-level
  1688. Get the field descriptor information for a field.
  1689. You can specifiy either the fieldname or the field number (position of the
  1690. field within the record where the first field is #1) to get info on.
  1691. The field descriptor contains the following information:
  1692.   FIELDNAME  10 upper-case characters, A-Z and _ allowed, unused space is
  1693.              0-filled and is 0-terminated (11 bytes, ASCII, byte 11 always=0)
  1694.   FIELDTYPE  single ASCII character where C=character, N=numeric, D=date,
  1695.              L=logical, and M=memo field (1 byte, ASCII)
  1696.   FIELDLEN   length of field: C=1-254, N=1-19, D=8 (yyyymmdd), L=1 (T/F/space),
  1697.              M=10, this is total field length (1 byte, binary)
  1698.   FIELDDC    places right of decimal point if N field type, minimum if not 0 is
  1699.              2, can be up to 6 or 8, non-N fields always 0 (1 byte, binary)
  1700. See: GetRecordXB
  1701. ~GetRecordXB
  1702. Pack: AccessPack        Src: GetRecordXBsrc     Func:  31/Mid-level
  1703. Get the physical record from the data file into a data buffer by record number.
  1704. The data buffer is typically a TYPEd variable defined as the .DBF record itself
  1705. is defined. For example, if the DBF record has 2 fields, LNAME and FNAME, then
  1706. variable would be TYPEd as:
  1707.   TYPE RecBuffer
  1708.   tag AS STRING * 1             'the Xbase DBF delete flag (must be included)
  1709.   LastName AS STRING * 25       'same field length as the .DBF LNAME field
  1710.   FirstName AS STRING * 25      'same field length as the .DBF FNAME field
  1711.   END TYPE
  1712. This method of accessing the data file does not use any indexing. Therefore, it
  1713. typically is not used except for special purposes. The preferred method to
  1714. access the data is by one of the keyed Get() routines.
  1715. See: AddRecordXB  GetEqualXB
  1716. ~AddRecordXB
  1717. Pack: AccessPack        Src: AddRecordXBsrc     Func:  32/Mid-level
  1718. Append the record in the data buffer to the end of the DBF file.
  1719. This method of adding a record does not involve any indexing. It is typically
  1720. used to build a data file en masse and do the indexing after the entire .DBF 
  1721. file(s) has been built.                                                      
  1722. If you have several thousand data records to be added at once, this method of
  1723. building the DBF first and then using the ReindexXB routine is often faster
  1724. than using the InsertXB routine for each record to add.
  1725. The AddRecordXB is very fast. 400 recs/sec on an AT machine is typical. Over
  1726. 2000 recs/sec can be added on a fast 486 machine--that's 120,000 records added
  1727. per minute.
  1728. The record number used is determined by BULLET and it is returned in AP.RecNo.
  1729. See: UpdateRecordXB  InsertXB  ReindexXB
  1730. ~UpdateRecordXB
  1731. Pack: AccessPack        Src: UpdateRecordXBsrc  Func:  33/Mid-level
  1732. Write the updated data record to the the physical record number.
  1733. This method of writing the updated record must not be used if any field(s) in
  1734. the record is used as a key field(s) and has been changed.                   
  1735. This method of updating a record is very fast if you know that that update is
  1736. not going to alter any field used as a key in any index file that uses it. You
  1737. must, of course, first get the data record into the record buffer. Then you can
  1738. change it and write the update out to disk with this routine.
  1739. If you need to change a field(s) that is used as a key field or part of one,
  1740. use the UpdateXB routine. UpdateXB not only dynamically updates all related
  1741. index files if you change a key field, it also will undo any and all changes if
  1742. an error occurs in the transaction.
  1743. See: DeleteRecordXB  GetRecordXB  UpdateXB
  1744. ~DeleteRecordXB
  1745. Pack: AccessPack        Src: DeleteRecordXBsrc  Func:  34/Mid-level
  1746. Tag the record at the physical record number as being deleted.
  1747. This does not tag any in-memory copies of the record so be sure to mark any
  1748. such copies as being deleted yourself.                                     
  1749. The first byte of every .DBF record is reserved for the delete tag. This tag
  1750. is a space (ASCII 32) if the record is normal, or a * (ASCII 42) if it's marked
  1751. as being deleted. This delete tag is a reserved field in the DBF record and as
  1752. such is not defined as a formal field with a descriptor, etc. Make sure that
  1753. you define your in-memory buffers to reserve the first byte for the delete tag.
  1754. The Xbase DBF standard doesn't physically remove records marked as deleted from
  1755. the data file. It doesn't mark them as available/reusable either. To physically
  1756. remove records marked as deleted use PackRecordsXB.
  1757. Records can be temporarily marked as deleted then recalled to normal status.
  1758. The Key/Get routines (GetFirstXB, etc.) return the record number needed for
  1759. this routine after each access in AP.RecNo.
  1760. See: UndeleteRecordXB  PackRecordsXB
  1761. ~UndeleteRecordXB
  1762. Pack: AccessPack        Src: UndeleteRecordsrc  Func:  35/Mid-level
  1763. Tag the record at the physical record number as being normal (not deleted).
  1764. This does not tag any in-memory copies of the record so be sure to mark any
  1765. such copies as being normal yourself.                                      
  1766. The first byte of every .DBF record is reserved for the delete tag. This tag
  1767. is a space (ASCII 32) if the record is normal, or a * (ASCII 42) if it's marked
  1768. as being deleted. This delete tag is a reserved field in the DBF record and as
  1769. such is not defined as a formal field with a descriptor, etc. Make sure that
  1770. you define your in-memory buffers to reserve the first byte for the delete tag.
  1771. The Xbase DBF standard does not physically remove records marked as deleted
  1772. from the data file so you can "recall" then back to normal status as easily as
  1773. you marked them deleted.
  1774. See: PackRecordsXB  DeleteRecordXB
  1775. ~PackRecordsXB
  1776. Pack: AccessPack        Src: PackRecordsXBsrc   Func:  36/Mid-level
  1777. Rebuild the open DBF file by physically removing all records marked as deleted.
  1778. Packing occurs in place using the existing file. It's recommended that you   
  1779. use BackupFileXB to copy the current DBF file before using this routine in   
  1780. case of a failure during the pack process.                                   
  1781. The newly packed file is truncated to reflect the current, actual size.
  1782. If there are index files for this .DBF file, they MUST all be reindexed after
  1783. the pack process by using ReindexXB.
  1784. This routine dynamically allocates at least as many bytes as the length of   
  1785. the record. More if available.                                               
  1786. See: FirstKeyXB  DeleteRecordXB  BackupFileXB  ReindexXB
  1787. ~FirstKeyXB
  1788. Pack: AccessPack        Src: FirstKeyXBsrc      Func:  40/Mid-level
  1789. Retrieve the first key in index order from the index file.
  1790. This routine does not access the .DBF file and so does not retrieve the data 
  1791. record. What it does do is locate the first key of the index, returning it,  
  1792. and also returning the record number within the .DBF that the key indexes.   
  1793. To retrieve the data record you can use the GetRecordXB routine. The preferred
  1794. method, however, is to use the GetFirstXB.
  1795. The key returned includes an enumerator if a non-unique index file is involved.
  1796. The enumerator is a little-endian 16-bit value that serves to differentiate  
  1797. up to 65535 "identical", non-unique keys. It is attached to all keys of non- 
  1798. unique index files and occupies the last two bytes of the key.               
  1799. This routine is typically used to position the index file to the first key so
  1800. as to allow forward in-order access to the keys by using NextKeyXB.
  1801. See: EqualKeyXB  GetFirstXB  GetRecordXB
  1802. ~EqualKeyXB
  1803. Pack: AccessPack        Src: EqualKeyXBsrc      Func:  41/Mid-level
  1804. Search for the exact key in the index file.
  1805. This routine does not access the .DBF file and so does not retrieve the data 
  1806. record. What it does do is search for the key in the index, and if found,    
  1807. returns the record number within the .DBF that the key indexes. The key must 
  1808. be an exact match, including enumerator word if a non-unqiue index file.     
  1809. To retrieve the data record you can use the GetRecordXB routine. The preferred
  1810. method, however, is to use the GetEqualXB.
  1811. This routine will only find EXACT matches to the specified key (including the
  1812. enumerator if applicable). However, even if the exact key is not found in the
  1813. index file, the index file is positioned so that the next NextKeyXB retrieves
  1814. the key that would have followed the unmatched specified key. For example,
  1815. if the key to match was "KINGS" (a partial key in this case), EqualKeyXB would
  1816. return a key not found error. If you were to now do a NextKeyXB, the next key
  1817. would be returned, let's say it is "KINGSTON".
  1818. See: NextKeyXB  GetEqualXB  GetRecordXB
  1819. ~NextKeyXB
  1820. Pack: AccessPack        Src: NextKeyXBsrc       Func:  42/Mid-level
  1821. Retrieve the next key in index order from the index file.
  1822. This routine does not access the .DBF file and so does not retrieve the data 
  1823. record. What it does do is retreive the next key of the index, returning it, 
  1824. and also returning the record number within the .DBF that the key indexes.   
  1825. To retrieve the data record you can use the GetRecordXB routine. The preferred
  1826. method, however, is to use the GetNextXB.
  1827. The key returned includes an enumerator if a non-unique index file is involved.
  1828. This routine is typically called after the index file has first been positioned
  1829. to a known key using either FirstKeyXB or EqualKeyXB, or after a previous
  1830. NextKeyXB or even PrevKeyXB. What it basically does is get the key following
  1831. the current key, and then make that key the new current key.
  1832. See: PrevKeyXB  GetNextXB  GetRecordXB
  1833. ~PrevKeyXB
  1834. Pack: AccessPack        Src: PrevKeyXBsrc       Func:  43/Mid-level
  1835. Retrieve the previous key in index order from the index file.
  1836. This routine does not access the .DBF file and so does not retrieve the data 
  1837. record. What it does do is retreive the previous key of the index, returning 
  1838. it and also returning the record number within the .DBF that the key indexes.
  1839. To retrieve the data record you can use the GetRecordXB routine. The preferred
  1840. method, however, is to use the GetPrevXB.
  1841. The key returned includes an enumerator if a non-unique index file is involved.
  1842. This routine is typically called after the index file has first been positioned
  1843. to a known key using either LastKeyXB or EqualKeyXB, or after a previous
  1844. PrevKeyXB or even NextKeyXB. What it basically does is to get the key previous
  1845. the current key, and then make that key the new current key.
  1846. See: LastKeyXB  GetPrevXB  GetRecordXB
  1847. ~LastKeyXB
  1848. Pack: AccessPack        Src: LastKeyXBsrc       Func:  44/Mid-level
  1849. Retrieve the last key in index order from the index file.
  1850. This routine does not access the .DBF file and so does not retrieve the data 
  1851. record. What it does do is locate the last key of the index, returning it,   
  1852. and also returning the record number within the .DBF that the key indexes.   
  1853. To retrieve the data record you can use the GetRecordXB routine. The preferred
  1854. method, however, is to use the GetLastXB.
  1855. This routine is typically used to position the index file to the last key so as
  1856. to allow reverse in-order access to the keys by using PrevKeyXB.
  1857. See: StoreKeyXB  GetLastXB  GetRecordXB
  1858. ~StoreKeyXB
  1859. Pack: AccessPack        Src: StoreKeyXBsrc      Func:  45/Mid-level
  1860. Insert the key into the index file in proper key order.
  1861. This routine does not add the data record to the .DBF file. It only inserts  
  1862. the key and record number into the index file. Use InsertXB, instead.        
  1863. To do a complete data record and key insert, you could use AddRecordXB to add
  1864. the data record to the .DBF, BuildKeyXB to construct the key, then StoreKeyXB
  1865. to insert the key and record number information into the index file. If that
  1866. key already exists and the file allows duplicate keys, you need to attach the
  1867. proper enumerator word and retry StoreKeyXB.
  1868. This is much too much to do. Instead, just use InsertXB. All these details
  1869. including adding the data record and multi-key inserts are performed
  1870. automatically with just the single call.
  1871. See: DeleteKeyXB  InsertXB
  1872. ~DeleteKeyXB
  1873. Pack: AccessPack        Src: DeleteKeyXBsrc     Func:  46/Mid-level
  1874. Physically remove the specified key from the index file.
  1875. This routine requires an EXACT key match for all bytes of the key, including 
  1876. the enumerator word if a non-unique index file is involved.                  
  1877. This routine would seldom be used, typically, since deleted dBASE data records
  1878. are only physically deleted during a PackRecordsXB and the index file is
  1879. rebuilt afterward using ReindexXB.
  1880. See: BuildKeyXB  CurrentKeyXB
  1881. ~BuildKeyXB
  1882. Pack: AccessPack        Src: BuildKeyXBsrc      Func:  47/Mid-level
  1883. Build the key for the specifed data record based on the key expression for the
  1884. index file. If the index file is non-unique, a 0-value enumerator is attached.
  1885. The enumerator is a little-endian 16-bit value that serves to differentiate  
  1886. up to 65535 "identical", non-unique keys. It is attached to all keys of non- 
  1887. unique index files and occupies the last two bytes of the key.               
  1888. This routine, like most of the mid-level routines, typically would not be used
  1889. since the high-level access routines take care of this detail automatically.
  1890. See: CurrentKeyXB  StoreKeyXB
  1891. ~CurrentKeyXB
  1892. Pack: AccessPack        Src: CurrentKeyXBsrc    Func:  48/Mid-level
  1893. Retrieve the current key value for the specified key file handle and also the
  1894. data record number that it indexes.
  1895. This routine is useful in that it retrieves on demand the actual key value of
  1896. the last accessed key in the index file (and the data record number). Most
  1897. often you don't need this information so it would be a waste of time and space
  1898. for your program to explicitly track each current key for each index file that
  1899. you have open.
  1900. See: GetFirstXB  ReindexXB  DeleteKeyXB
  1901. ~GetFirstXB
  1902. Pack: AccessPack        Src: GetFirstXBsrc      Func:  60/High-level
  1903. Retrieve the first indexed key and data record.
  1904. The key returned includes an enumerator if a non-unique index file is involved.
  1905. This routine is typically used to process a database in index order starting at
  1906. the first ordered key (and its data record). After processing this first entry,
  1907. subsequent in-order access of the database is achieved by using GetNextXB until
  1908. the end of the database is reached.
  1909. This routine, like all the high-level Get routines, fills in the AP.RecNo of
  1910. the record accessed. In GetFirstXB's case, it fills AP.RecNo with the record
  1911. number pointed to by the first key. Since this is so, the AP pack is primed for
  1912. an UpdateXB after each high-level Get. Other methods to get the record number
  1913. are to use CurrKeyXB or any of the Key routines (KeyFirstXB, etc.).
  1914. See: GetEqualXB  FirstKeyXB  UpdateXB
  1915. ~GetEqualXB
  1916. Pack: AccessPack        Src: GetEqualXBsrc      Func:  61/High-level
  1917. Search for the exact key in the index file and return its data record.
  1918. This routine will only find EXACT matches to the specified key (including the
  1919. enumerator if applicable). However, even if the exact key is not found in the
  1920. index file, the index file is positioned so that the next GetNextXB retrieves
  1921. the key that would have followed the unmatched specified key. For example,
  1922. if the key to match was "KINGS" (a partial key in this case), GetEqualXB would
  1923. return a key not found error. If you were to now do a GetNextXB, the next key
  1924. and data record would be returned, let's say the key is "KINGSTON" and its data
  1925. record is the data record for that key. Another GetNextXB would retrieve the
  1926. key and record after that. (GetPrevXB can be used in this fashion too.)
  1927. This routine, like all the high-level Get routines, fills in the AP.RecNo of
  1928. the record accessed. In GetEqualXB's case, it fills AP.RecNo with the record
  1929. number pointed to by the matched key. Since this is so, the AP pack is primed
  1930. for an UpdateXB after each high-level Get. Other methods to get the record
  1931. number are to use CurrKeyXB or any of the Key routines (KeyEqualXB, etc.).
  1932. See: GetNextXB  EqualKeyXB
  1933. ~GetNextXB
  1934. Pack: AccessPack        Src: GetNextXBsrc       Func:  62/High-level
  1935. Retrieve the next indexed key and its data record.
  1936. The key returned includes an enumerator if a non-unique index file is involved.
  1937. This routine is typically calld after the index file has first been positioned
  1938. to a known key using either GetFirstXB or GetEqualXB, or after a previous
  1939. GetNextXB or even GetPrevXB. What it basically does is get the key and data
  1940. record following the current key, and then make that key the new current key.
  1941. This routine, like all the high-level Get routines, fills in the AP.RecNo of
  1942. the record accessed. In GetNextXB's case, it fills AP.RecNo with the record
  1943. number pointed to by the next key. Since this is so, the AP pack is primed for
  1944. an UpdateXB after each high-level Get. Other methods to get the record number
  1945. are to use CurrKeyXB or any of the Key routines (KeyNextXB, etc.).
  1946. See: GetPrevXB  NextKeyXB
  1947. ~GetPrevXB
  1948. Pack: AccessPack        Src: GetPrevXBsrc       Func:  63/High-level
  1949. Retrieve the previous indexed key and record.
  1950. The key returned includes an enumerator if a non-unique index file is involved.
  1951. This routine is typically called after the index file has first been positioned
  1952. to a known key using either GetLastXB or GetEqualXB, or after a previous
  1953. GetPrevXB or even GetNextXB. What it basically does is to get the key and data
  1954. record previous the current key, and then make that key the new current key.
  1955. This routine, like all the high-level Get routines, fills in the AP.RecNo of
  1956. the record accessed. In GetPrevXB's case, it fills AP.RecNo with the record
  1957. number pointed to by the previous key. Since this is so, the AP pack is primed
  1958. for an UpdateXB after each high-level Get. Other methods to get the record
  1959. number are to use CurrKeyXB or any of the Key routines (KeyPrevXB, etc.).
  1960. See: GetLastXB  PrevKeyXB
  1961. ~GetLastXB
  1962. Pack: AccessPack        Src: GetLastXBsrc       Func:  64/High-level
  1963. Retrieve the last indexed key and record.
  1964. This routine is typically used to process a database in reverse index order
  1965. starting at the last ordered key (and its data record). After processing this
  1966. last entry, subsequent reverse-order access of the database is achieved by
  1967. using GetPrevXB until the top of the database is reached.
  1968. This routine, like all the high-level Get routines, fills in the AP.RecNo of
  1969. the record accessed. In GetLastXB's case, it fills AP.RecNo with the record
  1970. number pointed to by the last key. Since this is so, the AP pack is primed for
  1971. an UpdateXB after each high-level Get. Other methods to get the record number
  1972. are to use CurrKeyXB or any of the Key routines (KeyLastXB, etc.).
  1973. See: InsertXB  LastKeyXB
  1974. ~InsertXB
  1975. Pack: AccessPack        Src: InsertXBsrc        Func:  65/High-level
  1976. Add the data record to data file and insert the related key(s) into the linked
  1977. index file(s).
  1978. This routine is used to add new entries into a database, one at a time. The
  1979. data record is first added to the data file, then for each related index file,
  1980. a key is inserted into the appropriate index file. Up to 32 index files can be
  1981. automatically maintained for each data file.
  1982. This and several other routines are transaction-based. If a failure occurs
  1983. prior to the routine's completion, all changes made to the database by the
  1984. routine will be backed-out and the database (data and related index file(s))
  1985. effectively restored to its original state.
  1986.                                   
  1987. If the routine failed to complete, the function return value is the number of
  1988. the pack that caused the failure. The pack's Stat is checked to determine the
  1989. error code. If the function return value is 0, YOU MUST STILL check the first
  1990. pack's Stat. If it's non-zero, then the failure occured with the data record.
  1991. See: UpdateXB  StoreKeyXB
  1992. ~UpdateXB
  1993. Pack: AccessPack        Src: UpdateXBsrc        Func:  66/High-level
  1994. Modify an existing data record (identified by record number) and automatically
  1995. perform any index file updates needed to keep the index file(s) in sync.
  1996. If any key fields changed between the original record and the new one, this
  1997. routine updates the appropriate index file(s) by replacing the original key(s)
  1998. with new the key(s) based on the updated data record. Up to 32 index files can
  1999. be automatically maintained for each data file. Get routines (GetFirstXB, etc.)
  2000. set the AP.RecNo of the record that UpdateXB uses.
  2001. This and several other routines are transaction-based. If a failure occurs
  2002. prior to the routine's completion, all changes made to the database by the
  2003. routine will be backed-out and the database (data and related index file(s))
  2004. effectively restored to its original state.
  2005. If the routine failed to complete, the function return value is the number of
  2006. the pack that caused the failure. The pack's Stat is checked to determine the
  2007. error code. If the function return value is 0, YOU MUST STILL check the first
  2008. pack's Stat. If it's non-zero, then the failure occured with the data record.
  2009. See: ReindexXB  UpdateRecordXB
  2010. ~ReindexXB
  2011. Pack: AccessPack        Src: ReindexXBsrc       Func:  67/High-level
  2012. Reindex all related index files for a data file.
  2013. The index file(s) must already exist and be open. Any existing key data is
  2014. overwritten by the new key data. In other words, if you have a 10MByte index
  2015. file, ReindexXB uses the same file space building the news keys over the old.
  2016. This results in a less fragmented disk and also minimizes disk space needed.
  2017. You can also create a new, empty index file and reindex to that. This would be
  2018. useful, for instance, if you needed to create a temporary index file--something
  2019. that you'd use for a report, say, then delete after the report.
  2020. This routine creates a TEMPORARY work file in either the current directory or,
  2021. if the DOS environment variable TMP is defined, in the TMP= directory. The size
  2022. of this file is approx. bytes = (RECORDS * (KEYLEN+6)). ReindexXB can operate
  2023. in as little as 32K of available memory and can use up to 128K. The resultant
  2024. index file(s) are optimized for minimum size AND maximum retrieval speed.
  2025. If the routine failed to complete, the function return value is the number of
  2026. the pack that caused the failure. The pack's Stat is checked to determine the
  2027. error code. A return value of zero indicates no error occured.               
  2028. See: LockXB  PackRecordsXB
  2029. ~LockXB
  2030. Pack: AccessPack        Src: LockXBsrc          Func:  80/Network
  2031. Lock all bytes in the index file handle(s) for exclusive use by the current
  2032. process and reload the index file header(s) from disk. Also lock all bytes in
  2033. the related data file and reload the data file header from disk.
  2034. The files must have been opened with the appropriate share attribute and not 
  2035. in compatibility mode. SHARE.EXE MUST be installed or DOS error 1 is issued. 
  2036. This routine is transaction-based and will lock all index files specified in 
  2037. AccessPack and the data file. If any lock fails, all previous locks by this  
  2038. routine are released. The return value indicates which access pack failed, if
  2039. any. This value is used as the index into the AccessPack group for you to    
  2040. identify the error code. See LockXBsrc for determining this exactly.         
  2041. Use the DriveRemoteXB and/or FileRemoteXB to determine if locking is necessary.
  2042. If the files are on a remote drive then it is best to use locking. Locking may
  2043. also be necessary on multitasking local machines accessing shared files.
  2044. This routine is a combination of LockKeyXB and LockDataXB.
  2045. See: UnlockXB  LockKeyXB  LockDataXB  DriveRemoteXB  FileRemoteXB
  2046. ~UnlockXB
  2047. Pack: AccessPack        Src: UnlockXBsrc        Func:  81/Network
  2048. Unlock all bytes in the specified file handle(s) (previously locked) and flush
  2049. the file header(s) to disk (flush done before lock(s) released). Also unlock
  2050. all bytes in the related data file and flush the data file header to disk.
  2051. The files must have been opened with the appropriate share attribute and not 
  2052. in compatibility mode. SHARE.EXE MUST be installed or DOS error 1 is issued. 
  2053. This routine is transaction-based and will unlock all index files specified in
  2054. AccessPack and the data file. If an unlock fails the routine exits with a
  2055. return value indicating which access pack failed. This value is used as the
  2056. index into the AccessPack group for you to identify the error code. Note that
  2057. this routine does not attempt to re-lock those files unlocked successfully if
  2058. an error occurs in the transaction. If an error does occur (unlikely) you will
  2059. need to provide for unlocking the remaining files manually with the UnlockKeyXB
  2060. and UnlockDataXB routines. You should not rely on the operating system to
  2061. automatically unlock files when they're closed.
  2062. This routine is a combination of UnlockKeyXB and UnlockDataXB.
  2063. See: LockKeyXB  UnlockKeyXB  UnlockDataXB
  2064. ~LockKeyXB
  2065. Pack: AccessPack        Src: LockKeyXBsrc       Func:  82/Network
  2066. Lock all bytes in the index file handle(s) for exclusive use by the current
  2067. process and reload the index file header(s) from disk.
  2068. The files must have been opened with the appropriate share attribute and not 
  2069. in compatibility mode. SHARE.EXE MUST be installed or DOS error 1 is issued. 
  2070. This routine is transaction-based and will lock all index files specified in
  2071. AccessPack. If any lock fails, all previous locks by this routine are released.
  2072. The return value indicates which access pack failed, if any. This value is used
  2073. as the index into the AccessPack group for you to identify the error code.
  2074. The advantage of using region locks (LockKeyXB locks the entire file region) to
  2075. control file access is that the file does not need to be opened/closed using
  2076. the Deny Read/Write sharing attribute. Opening the file for Deny None, and
  2077. controlling subsequent access with region locks, allows for faster processing
  2078. since files do not need to be constantly opened and closed, as they would if
  2079. access were controlled by opening with Deny Read/Write.
  2080. See: UnlockKeyXB  LockXB
  2081. ~UnlockKeyXB
  2082. Pack: AccessPack        Src: UnlockKeyXBsrc     Func:  83/Network
  2083. Unlock all bytes in the specified file handle(s) (previously locked) and flush
  2084. the file header(s) to disk (flush done before lock(s) released).
  2085. The files must have been opened with the appropriate share attribute and not 
  2086. in compatibility mode. SHARE.EXE MUST be installed or DOS error 1 is issued. 
  2087. This routine is transaction-based and will unlock all index files specified in
  2088. AccessPack. If an unlock fails the routine exits with a return value indicating
  2089. which access pack failed. This value is used as the index into the AccessPack
  2090. group for you to identify the error code.
  2091. All file locks should be released when exclusive access in no longer needed. 
  2092. It is not recommended that you end your program without having released active
  2093. file locks. This is especially a valid concern for DOS versions prior to 5.0.
  2094. DOS 5 releases locks on files that are closed.
  2095. See: LockDataXB  UnlockXB
  2096. ~LockDataXB
  2097. Pack: AccessPack        Src: LockDataXBsrc      Func:  84/Network
  2098. Lock all bytes in the file handle's data file for exclusive use by the current
  2099. process and reload the data file header from disk. You must set AP.RecNo=0 to
  2100. do this. To lock a single record, set AP.RecNo=record# to lock.
  2101. The files must have been opened with the appropriate share attribute and not 
  2102. in compatibility mode. SHARE.EXE MUST be installed or DOS error 1 is issued. 
  2103. This routine locks the specified data file. If the handle specified is that of
  2104. an index file, that index file's related data file handle is used. For single-
  2105. record locks, AP.Handle must have a data file handle specified. Header loading
  2106. is not performed if locking a single record.
  2107. The advantage of using region locks (LockDataXB locks the entire file region)
  2108. to control file access is that the file does not need to be opened/closed using
  2109. the Deny Read/Write sharing attribute. Opening the file for Deny None, and
  2110. controlling subsequent access with region locks, allows for faster processing
  2111. since files do not need to be constantly opened and closed, as they would if
  2112. access were controlled by opening with Deny Read/Write.
  2113. See: UnlockDataXB
  2114. ~UnlockDataXB
  2115. Pack: AccessPack        Src: UnlockDataXBsrc    Func:  85/Network
  2116. Unlock all bytes in the specified file handle (previously locked) and flush the
  2117. data file header to disk (flush done before lock released). To do this you must
  2118. set AP.RecNo=0. To unlock a single record, set AP.RecNo=record# to unlock.
  2119. The files must have been opened with the appropriate share attribute and not 
  2120. in compatibility mode. SHARE.EXE MUST be installed or DOS error 1 is issued. 
  2121. This routine unlocks the specified data file. If the handle specified is that
  2122. of an index file that index file's related datafile handle is used. For single-
  2123. record unlocks, AP.Handle must have a data file handle specified. Flushing is
  2124. not performed if unlocking a single record.
  2125. All file locks should be released when exclusive access in no longer needed. 
  2126. It is not recommended that you end your program without having released active
  2127. file locks. This is especially a valid concern for DOS versions prior to 5.0.
  2128. DOS 5 releases locks on files that are closed.
  2129. See: DriveRemoteXB
  2130. ~DriveRemoteXB
  2131. Pack: RemotePack        Src: DriveRemoteXBsrc   Func:  86/Network
  2132. Determine if specified drive is remote (default drive=0, A:=1, B=2, C=3...).
  2133. This routine uses INT21/44/sub function 09.
  2134. In addition to returning the IsRemote state, this routine sends back the result
  2135. of the DX register and also the install state of SHARE.EXE.
  2136. The meaning of the bitflags in Flags are (where IsRemote=0):
  2137. Bit   Meaning drive...
  2138.  1   1=uses 32-bit sectoring
  2139.  6   1=accepts Generic IOCTL (for INT21/44/0D,0E,0Fh)
  2140.  7   1=accepts Query IOCTL Device (INT21/44/11h)
  2141.  9   1=is local but shared by other computers in the network
  2142. 11   1=accepts Does-Device-Use-Removable-Media (INT21/44/08)
  2143. 13   1=requires media descriptor in FAT
  2144. 14   1=accepts Receive/Send Control Data from Block Device (INT21/44/04,05)
  2145. 15   1=is Substitution drive (set by the DOS SUBST command)
  2146.      (all other bits=0)
  2147. See: FileRemoteXB  LockXB
  2148. ~FileRemoteXB
  2149. Pack: RemotePack        Src: FileRemoteXBsrc    Func:  87/Network
  2150. Determine if specified handle of file or device is remote.
  2151. This routine uses INT21/44/sub function 0Ah.
  2152. In addition to returning the IsRemote state, this routine sends back the result
  2153. of the DX register and also the install state of SHARE.EXE.
  2154. Flags bit 7=1 then handle is device, =0 then handle is file.
  2155. Bit   Meaning DEVICE...                 Bit   Meaning DEVICE...(cont)
  2156.  0   1=is console input device          13   1=is named pipe
  2157.  1   1=is console output device         15   1=is remote, 0=is local
  2158.  2   1=is null device                        (all other bits=0)
  2159.  3   1=is clock device                  Bit   Meaning FILE...
  2160.  4   1=is special device               0-5   xxxxxx=drive number (0=A...)
  2161.  5   1=is in binary mode, 0=in ASCII     6   1=has not been written to
  2162.  6   0=returns EOF if device is read    12   1=is NoInherit
  2163. 11   1=is network spooler               14   1=date/time not set at close
  2164. 12   1=is NoInherit                     15   1=is remote, 0=is local
  2165.                                              (all other bits=0)
  2166. See: SetRetriesXB  DriveRemoteXB  LockXB
  2167. ~SetRetriesXB
  2168. Pack: SetRetriesPack    Src: SetRetriesXBsrc    Func:  88/Network
  2169. Set the number of times DOS retries disk operations after a failure due to
  2170. file-sharing operations (locked file regions from LockXB routines).
  2171. This routine uses INT21/44/sub function 0Bh.
  2172. By default DOS retries an operation 3 times (without pausing between attempts)
  2173. before returning an error to the application.
  2174. If you change the default values it's recommended that the default state be  
  2175. restored before your application ends (Retries=3, Pause=1).                  
  2176. These values are pretty much determined by trial-and-error. You may find that
  2177. adding a delay between retries returns fewer access-denied errors.
  2178. See: DeleteFileDOS  LockXB
  2179. ~DeleteFileDOS
  2180. Pack: DOSFilePack       Src: DeleteFileDOSsrc   Func: 100/DOS
  2181. Delete the specified file.
  2182. This routine uses DOS INT21/41 (interrupt 21h function 41h).
  2183. See: RenameFileDOS
  2184. ~RenameFileDOS
  2185. Pack: DOSFilePack       Src: RenameFileDOSsrc   Func: 101/DOS
  2186. Rename a file. May also be used to move the file to a new directory within the
  2187. partition.
  2188. This routine uses DOS INT21/56.
  2189. If the specified directory differs from the file's directory, the file's     
  2190. directory entry is moved to the new directory.                               
  2191. For example, if the FilenamePtr filename is C:\LP100\PROJ93A.INF and the
  2192. NewFilenamePtr filename is C:\ARCH\PROJ93A.INA, the file is essentially
  2193. renamed and also moved to the \ARCH directory.
  2194. See: CreateFileDOS
  2195. ~CreateFileDOS
  2196. Pack: DOSFilePack       Src: CreateFileDOSsrc   Func: 102/DOS
  2197. Create a new file.
  2198. This routine uses INT21/3C.
  2199. The specified filename/pathname must NOT already exist.
  2200. The file created is not left open. You must OpenFileDOS to use it.
  2201. The attribute used during the create can be:
  2202.   ATTRIBUTE       VALUE    MEANING
  2203.    Normal              0    normal access permitted to file
  2204.    Read-Only           1    read-only access permitted to file
  2205.    Hidden              2    file does not appear in directory listing
  2206.    System              4    file is a system file
  2207.    Volume              8    FILENAME used as volume label if no current label
  2208.    Archive            20h   file is marked for archiving
  2209. See: AccessFileDOS  OpenFileDOS
  2210. ~AccessFileDOS
  2211. Pack: DOSFilePack       Src: AccessFileDOSsrc   Func: 103/DOS
  2212. Determine if the specified file can be accessed with the specified
  2213. access/sharing mode.
  2214. This routine uses INT21/3D and INT21/3E.
  2215. Basically, a Does-File-Exist routine. It uses the specified access/sharing
  2216. attributes when trying to open the file. For example, if you specify
  2217. DFP.Attr = &H42 (R/W access + Deny None sharing) and use AccessFileDOS on a
  2218. Read-Only DOS file, the return value would be DOS error 5, Access Denied.
  2219. See: OpenFileDOS
  2220. ~OpenFileDOS
  2221. Pack: DOSFilePack       Src: OpenFileDOSsrc     Func: 104/DOS
  2222. Open the specified file with the specified access/sharing mode.
  2223. This routine uses INT21/3D.
  2224.   ACCESS          VALUE    MEANING
  2225.    Read-only           0    open for read-only access
  2226.    Write-only          1    open for write-only access
  2227.    Read/Write          2    open for read/write access
  2228.   SHARE
  2229.    Compatibility       0     any process may share file (not recommended)
  2230.    Deny Read/Write    10h    no other process may share file
  2231.    Deny Write         20h    no other process may share file for write
  2232.    Deny Read          30h    no other process may share file for read
  2233.    Deny None          40h    any process may share file except in Compatibilty
  2234.   INHERIT                                                                 mode
  2235.    NoInheritFlag      80h    if set child processes do not inherit file handles
  2236.                              (child process cannot inherit handle > 20)
  2237. The file access mode is a combination of ACCESS + SHARE + INHERIT.
  2238. See: SeekFileDOS  OpenPack
  2239. ~SeekFileDOS
  2240. Pack: DOSFilePack       Src: SeekFileDOSsrc     Func: 105/DOS
  2241. Position the DOS file pointer of the specified file to the specified position.
  2242. This routine uses INT21/42.
  2243. The position is a 32-bit value and is relative to either the start of the file,
  2244. the current file pointer position, or the end of the file.
  2245.  Method  Meaning
  2246.     0    start move from the start of file (offset is a 32-bit unsigned value)
  2247.     1    start move at the current position (offset a signed value)
  2248.     2    start move at the end of file (offset a signed value)
  2249. For example, to move to the 511th byte of a file (byte 0 being the first), set
  2250. the offset value to 511 and use Method 0. On return, the absolute offset value
  2251. of the new position is returned. This is useful with Method 2 since you can
  2252. specify an offset of 0 and have the file length returned.
  2253. Never position the file pointer to before the start of file.                 
  2254. See: ReadFileDOS
  2255. ~ReadFileDOS
  2256. Pack: DOSFilePack       Src: ReadFileDOSsrc     Func: 106/DOS
  2257. Read from the file or device the specified number of bytes into a buffer.
  2258. This routine uses INT21/3F.
  2259. On block devices (such as disks) input starts at the current file position and
  2260. the file pointer is repositioned to the last byte read +1.
  2261. It is possible to read less than the bytes specified without an error being  
  2262. generated. Compare the bytes to read with the returned bytes read value. If  
  2263. less then end of file was reached during the read, if 0 then file was at EOF.
  2264. By using DOS's predefined handles you can read from the keyboard (STDIN) by
  2265. using the STDIN handle, 0. The input will terminate after all specified bytes
  2266. have been read or after a CR (ASCII 0Dh). If more bytes are entered than were
  2267. requested, the next read will retrieve those excess bytes. Therefore, it's
  2268. suggested that you specify 129 bytes to input (DOS will process 127+CR/LF bytes
  2269. maximum when reading the STDIN device). Post-process the entered data by
  2270. scanning for the CR/LF.
  2271. See: ExpandFileDOS
  2272. ~ExpandFileDOS
  2273. Pack: DOSFilePack       Src: ExpandFileDOSsrc   Func: 107/DOS
  2274. Expands the specified file by the specified number of bytes.
  2275. This routine uses INT21/42 and INT21/40.
  2276. This routine is useful in pre-allocating disk space. By reserving disk space in
  2277. advance you can guarantee that enough disk space will be available for a future
  2278. operation (especially if more than 1 process is running). You'll also be able
  2279. ensure that the disk space that a file does use is as contiguous as possible.
  2280. Database systems are dynamic and their files typically allocate new space on
  2281. an as-needed basis. This dynamic allocation can cause parts of a file to be
  2282. located throughout the disk system, possibly affecting performance drastically.
  2283. By pre-allocating the disk space you can be assured of consistent throughput
  2284. performance since the file is contiguous.
  2285. See: WriteFileDOS
  2286. ~WriteFileDOS
  2287. Pack: DOSFilePack       Src: WriteFileDOSsrc    Func: 108/DOS
  2288. Write to the file or device the specified number of bytes from a buffer.
  2289. This routine uses INT21/40.
  2290. If the number of bytes written is less than the specified bytes, this routine
  2291. returns a -2 error code (or 65554 unsigned).                                 
  2292. On block devices (such as disk) output starts at the current file position, and
  2293. the file pointer is repositioned to the last byte written +1.
  2294. If the specified bytes to write is 0, the file is truncated at the current   
  2295. file pointer position.                                                       
  2296. By using DOS's predefined handles you can write to the screen (STDOUT) by
  2297. using the STDOUT handle, 1.
  2298. See: CloseFileDOS
  2299. ~CloseFileDOS
  2300. Pack: DOSFilePack       Src: CloseFileDOSsrc    Func: 109/DOS
  2301. Close the file flushing any internal buffers, releasing any locked regions, and
  2302. update the directory entry to the correct size, date, and time.
  2303. This routine uses INT21/3E.
  2304. If you have opened a file using the DOS open routine you should close it when
  2305. you no longer need it.
  2306. This routine can be used to close the predefined DOS handles (0-4) and make  
  2307. those handles available for reuse. Typically handles 0 and 1 should not be   
  2308. closed by an application since they are the STDIN and STDOUT that DOS uses   
  2309. for the current application (keyboard and screen).                           
  2310. Since BULLET provides for up to 250 user file handles for your applications it
  2311. isn't necessary for you to eek 3 more file handles by closing handles 2-4.
  2312. See: MakeDirDOS
  2313. ~MakeDirDOS
  2314. Pack: DOSFilePack       Src: MakeDirDOSsrc      Func: 110/DOS
  2315. Create a new subdirectory.
  2316. This routine uses INT21/39.
  2317. See: DeleteFileDOS
  2318. ~AccessPack
  2319.  Src: InsertXBsrc      Func: InsertXB and many more
  2320. TYPE AccessPack        'AP (AP is recommended pack name for DIM, AP.Func=)
  2321. Func AS INTEGER        'varies
  2322. Stat AS INTEGER        'ret:completion status
  2323. Handle AS INTEGER      'OS handle
  2324. RecNo AS LONG          ' in:rec number to get/delete/update (if applicable)
  2325.                        ' in:set to single rec# to lock or set to 0 to lock all
  2326.                        'ret:record number of data record accessed
  2327. RecPtrOff AS INTEGER   'far pointer to record storage buffer
  2328. RecPtrSeg AS INTEGER
  2329. KeyPtrOff AS INTEGER   'far pointer to search key buffer
  2330. KeyPtrSeg AS INTEGER
  2331. NextPtrOff AS INTEGER  'far pointer to next key access pack
  2332. NextPtrSeg AS INTEGER  'or 0:0 if end of link or if N/A
  2333. END TYPE  '22
  2334. The NextPtr variables are only used by InsertXB, UpdateXB, ReindexXB, and the
  2335. LockXB routines. NextPtr is used as a link to the next related access pack,
  2336. if any. Not all entries are used by all routines. Generally, any routine that
  2337. gets/puts user data to the database uses this pack.
  2338. See: BreakPack
  2339. ~BreakPack
  2340.  Src: BreakXBsrc       Func: BreakXB
  2341. TYPE BreakPack             'BP
  2342. Func AS INTEGER            '4
  2343. Stat AS INTEGER            'ret:completion status
  2344. Mode AS INTEGER            '=0 disable Ctrl-C/Ctrl-Break, 1=restore
  2345. END TYPE '6 bytes
  2346. A simple pack.
  2347. See: CopyPack
  2348. ~CopyPack
  2349.  Src: BackupFileXBsrc  Func: BackupFileXB, CopyDHXB, CopyKHXB
  2350. TYPE CopyPack              'CP
  2351. Func AS INTEGER            '5=BackupFileXB,16=CopyDHXB,26=CopyKHXB
  2352. Stat AS INTEGER            'ret:completion status
  2353. Handle AS INTEGER          'handle of BULLET file
  2354. FilenamePtrOff AS INTEGER  'far pointer to filenameZ
  2355. FilenamePtrSeg AS INTEGER  '(filename must end with a CHR$(0)))
  2356. END TYPE '10
  2357. See: CreateDataPack
  2358. ~CreateDataPack
  2359.  Src: CreateDXBsrc     Func: CreateDXB
  2360. TYPE CreateDataPackTYPE    'CDP
  2361. Func AS INTEGER            '10
  2362. Stat AS INTEGER            'ret:completion status
  2363. FilenamePtrOff AS INTEGER  'far pointer to filenameZ to create
  2364. FilenamePtrSeg AS INTEGER  '(filename must end with a CHR$(0))
  2365. NoFields AS INTEGER        'number of fields per record
  2366. FieldListPtrOff AS INTEGER 'far pointer to field list
  2367. FieldListPtrSeg AS INTEGER '(field list is of type FieldDescTYPE )
  2368. FileID AS INTEGER          'file signature byte, usually=3
  2369. END TYPE '16
  2370. The filename pointed at by the FilenamePtr variables should be a fixed-length
  2371. string (e.g., FILEN AS STRING * 80) so that VARSEG/VARPTR can be used to get
  2372. its memory address. The filename must end with a CHR$(0) immediately following
  2373. the last character of the filename: FILEN = YourFilename$ + CHR$(0).
  2374. The FieldListPtr variables point to an array of type FieldDescTYPE. This array
  2375. is dimensioned for as many fields as there are in the record and contains the
  2376. field descriptors, one for each field.
  2377. See: CreateKeyPack  FieldDescTYPE
  2378. ~CreateKeyPack
  2379.  Src: CreateKXBsrc     Func: CreateKXB
  2380. TYPE CreateKeyPack         'CKP
  2381. Func AS INTEGER            '20
  2382. Stat AS INTEGER            'ret:completion status
  2383. FilenamePtrOff AS INTEGER  'far pointer to filenameZ
  2384. FilenamePtrSeg AS INTEGER  '(filename must end with a CHR$(0))
  2385. KeyExpPtrOff AS INTEGER    'far pointer to key expressionZ
  2386. KeyExpPtrSeg AS INTEGER    '(key expression must end with a CHR$(0))
  2387. XBlink AS INTEGER          'BULLET XB data file handle this key file indexes
  2388. KeyFlags AS INTEGER        'bit 0=unique,1=char,4=int,5=long,(E=NLS),F=signed
  2389. CodePageID AS INTEGER      'code page ID for NLS, -1 to use system default
  2390. CountryCode AS INTEGER     'country code number for NLS, -1 to use default
  2391. CollatePtrOff AS INTEGER   'far pointer to programmer-supplied collate table
  2392. CollatePtrSeg AS INTEGER   'or 0:0 if using system-determined NLS table
  2393. END TYPE '24
  2394. Bit 14 in KeyFlags (0Eh) is set by BULLET during CreateKXB if a collate table
  2395. is present.
  2396. See: DescriptorPack  is_NLS
  2397. ~DescriptorPack
  2398.  Src: GetDescriptorXBsrc  Func: GetDescriptorXB
  2399. TYPE DescriptorPack        'DP
  2400. Func AS INTEGER            '30
  2401. Stat AS INTEGER            'ret:completion status
  2402. Handle AS INTEGER          'BULLET data file handle to get information on
  2403. FieldNumber AS INTEGER     'field number to get info on, or if 0 then...
  2404. FD AS FieldDescTYPE        '...search for DP.FD.FieldName
  2405. END TYPE '40
  2406. GetDescriptorXB allows you to get the field descriptor info for a particular
  2407. field number (as in the first field, or the 10th field, etc.) or, if you don't
  2408. know the physical field number, the routine can also get the info for a field
  2409. by field name.
  2410. To get the info for field number, say 5, set DP.FieldNumber = 5. The DP.FD
  2411. structure element is filled in with field 5's information.
  2412. To get the info for a field by fieldname, say LASTNAME, set DP.FieldNumber=0 &
  2413. DP.FD.FieldName = "LASTNAME" + STRING$(11,0)--the fieldname must be zero-filled
  2414. and zero-terminated--adding 11 ASCII zeroes ensures this requirement.
  2415. See: DOSFilePack  FieldDescTYPE
  2416. ~DOSFilePack
  2417.  Src: AccessFileDOSsrc  Func: AccessFileDOS
  2418.                               (all routines ending with DOS)
  2419. TYPE DOSFilePack           'DFP
  2420. Func AS INTEGER            'varies, see DeleteFileDOS for first of DOS routines
  2421. Stat AS INTEGER            'ret:completion status
  2422. FilenamePtrOff AS INTEGER  'far pointer to filenameZ
  2423. FilenamePtrSeg AS INTEGER  '(filename must end with a CHR$(0))
  2424. Handle AS INTEGER          'in: handle to access  ret: handle opened
  2425. ASmode AS INTEGER          'open access/sharing mode
  2426. Bytes AS INTEGER           'in: bytes to read  ret: bytes read
  2427. SeekOffset AS LONG         'seek to file position
  2428. Method AS INTEGER          'seek method
  2429. BufferPtrOff AS INTEGER    'far pointer to read/write buffer
  2430. BufferPtrSeg AS INTEGER
  2431. Attr AS INTEGER            'file create directory entry attribute
  2432. NewNamePtrOff AS INTEGER   'far pointer to new filenameZ for rename
  2433. NewNamePtrSeg AS INTEGER   '(filename must end with a CHR$(0))
  2434. END TYPE '30
  2435. All of the xDOS routines use this pack. Often only a few of the structure
  2436. elements are used by any one of the routines. Set only those needed.
  2437. See: DVmonPack
  2438. ~DVmonPack
  2439.  Src: DVmonCXBsrc      Func: DVmonCXB
  2440. TYPE DVmonPackTYPE         'THIS ROUTINE IS AVAILABLE ONLY IN THE DEBUG ENGINE
  2441. Func AS INTEGER            '9
  2442. Stat AS INTEGER            'ret:completion status
  2443. Mode AS INTEGER            '=0 disable montitoring, =1 enable
  2444. Handle AS INTEGER          'file handle to monitor
  2445. VideoSeg AS INTEGER        'segment to write screen image (e.g., &HB800)
  2446. END TYPE '10 bytes
  2447. This routine is supplied only in the BULLET debug engine. It displays real-time
  2448. monitoring information of a .DBF file or index and .DBF file pair including
  2449. searches, seeks, hits, current record number, current key, key node contents,
  2450. key node pointers, stack state, key and record counts, and other info.
  2451. By using the HereSeg value returned from StatKXB you can locate the searches,
  2452. seeks, and hits data at (DEF SEG=HereSeg: Seeks&=GetLongAt&(517): DEF SEG)
  2453.  +513 Searches AS LONG ;keys searched for since open
  2454.  +517 Seeks AS LONG    ;nodes seeked since open
  2455.  +521 Hits AS LONG     ;seeks satisfied without disk access
  2456. See: ExitPack
  2457. ~ExitPack
  2458.  Src: InitXBsrc        Func: ExitXB, AtExitXB
  2459. TYPE ExitPack              'EP
  2460. Func AS INTEGER            '1=ExitXB, 2=AtExitXB
  2461. Stat AS INTEGER            'ret:completion status
  2462. END TYPE '4 bytes
  2463. See: FieldDescTYPE
  2464. ~FieldDescTYPE
  2465.  Src: CreateDXBsrc     Func: CreateDXB
  2466. TYPE FieldDescTYPE         'this TYPE is used by CreateDataPack ONLY
  2467. FieldName AS STRING * 11   'zero-filled field name (use only ASCII 65-90,95)
  2468. FieldType AS STRING * 1    'C-har,N-umeric,D-ate,L-ogical,M-emo
  2469. FieldDA AS LONG            '=0,reserved
  2470. FieldLength AS STRING * 1  'C=1-254,N=1-19(varies),D=8,L=1,M=10
  2471. FieldDC AS STRING * 1      'decimal places for FieldType=N (0,2-15)
  2472. A1 AS INTEGER              '=0,reserved
  2473. A2 AS INTEGER              '=0,reserved
  2474. filler AS STRING * 10      '=0,reserved
  2475. END TYPE '32
  2476. If you can can forgo dBASE compatility you can use the B field type. This type
  2477. is for fields that contain binary data (all dBASE fields contain ASCII text or
  2478. numeric strings). If you specify a FieldType = "B" for, say an integer field,
  2479. use a FieldLen = 2. If the field is a long integer, use FieldLen = 4. You can
  2480. also use this non-standard field type for indexing. See CreateKXB for more.
  2481. See: HandlePack  CreateDataPack  CreateKXB
  2482. ~HandlePack
  2483.  Src: CloseDXBsrc      Func: CloseDXB, ReadDHXB, FlushDHXB, ZapDHXB
  2484.                              CloseKXB, ReadKHXB, FlushKHXB, ZapKHXB
  2485.                            'HP
  2486. TYPE HandlePack            '12=CloseDXB,14=ReadDHXB,15=FlushDHXB,17=ZapDHXB
  2487. Func AS INTEGER            '22=CloseKXB,24=ReadKHXB,25=FlushKHXB,27=ZapKHXB
  2488. Stat AS INTEGER            'ret:completion status
  2489. Handle AS INTEGER          'handle of BULLET file
  2490. END TYPE '6
  2491. See: InitPack
  2492. ~InitPack
  2493.  Src: InitXBsrc        Func: InitXB
  2494. TYPE InitPack              'IP
  2495. Func AS INTEGER            '0
  2496. Stat AS INTEGER            'ret:completion status
  2497. JFTmode AS INTEGER         'expand JFT if non-zero
  2498. DOSver AS INTEGER          'ret:DOS version
  2499. Version AS INTEGER         'ret:BULLET version * 100
  2500. ExitOff AS INTEGER         'ret:far pointer to ExitXB routine, offset
  2501. ExitSeg AS INTEGER         'ret:segment of ExitXB
  2502. END TYPE '12 bytes
  2503.      
  2504. See: MemoryPack
  2505. ~MemoryPack
  2506.  Src: MemoryXBsrc      Func: MemoryXB
  2507. TYPE MemoryPack            'MP
  2508. Func AS INTEGER            '3
  2509. Stat AS INTEGER            'ret:completion status
  2510. Memory AS LONG             'ret:largest free OS memory block
  2511. END TYPE '8 bytes
  2512. See: OpenPack
  2513. ~OpenPack
  2514.  Src: OpenDXBsrc       Func: OpenDXB, OpenKXB
  2515. TYPE OpenPack              'OP
  2516. Func AS INTEGER            '11=OpenDXB,21=OpenKXB
  2517. Stat AS INTEGER            'ret:completion status
  2518. Handle AS INTEGER          'ret:OS handle of file opened
  2519. FilenamePtrOff AS INTEGER  'far pointer to filenameZ to open
  2520. FilenamePtrSeg AS INTEGER  '(filename must end with a CHR$(0))
  2521. ASmode AS INTEGER          'DOS access-sharing mode (see OpenFileDOS)
  2522. xbHandle AS INTEGER        'if opening key file this is its related data file
  2523. END TYPE '14               '(if opening data file xbHandle is not used)
  2524.                            'Note: you must supply xbHandle on index file opens
  2525. See: RemotePack  OpenFileDOS
  2526. ~RemotePack
  2527.  Src: DriveRemoteXBsrc  Func: DriveRemoteXB, FileRemoteXB
  2528. TYPE RemotePack            'RP
  2529. Func AS INTEGER            '86=DriveRemoteXB,87=FileRemoteXB
  2530. Stat AS INTEGER            'ret:completion status
  2531. Handle AS INTEGER          'handle/drive depending on routine
  2532. IsRemote AS INTEGER        'ret:0=local,1=remote
  2533. Flags AS INTEGER           'ret:dx register as returned by DOS
  2534. IsShare AS INTEGER         'ret:0=SHARE.EXE not loaded
  2535. END TYPE '12
  2536. See: SetRetriesPack
  2537. ~SetRetriesPack
  2538.  Src: SetRetriesXBsrc  Func: SetRetriesXB
  2539. TYPE SetRetriesPack        'SRP
  2540. Func AS INTEGER            '88
  2541. Stat AS INTEGER            'ret:completion status
  2542. Mode AS INTEGER            '0=set DOS default else use Pauses/Retries below
  2543. Pause AS INTEGER           '0-65535 loop counter between retries
  2544. Retries As INTEGER         '0-65535 retries to access locked file
  2545. END TYPE '10
  2546. The default values for Retries is 3 and Pause is 1.
  2547. The Pause value is used as a simple loop counter used to waste time. This loop
  2548. IS dependent on CPU power so values are not portable across different machines.
  2549. Do not use unrealistic values. For example, don't set Retries to 30,000 unless
  2550. you really want to wait for DOS to try 30,000 times before returning an error!
  2551. See: StatDataPack
  2552. ~StatDataPack
  2553.  Src: StatDXBsrc       Func: StatDXB
  2554. TYPE StatDataPackTYPE      'SDP
  2555. Func AS INTEGER            '13
  2556. Stat AS INTEGER            'ret:completion status
  2557. Handle AS INTEGER          'BULLET data file to get status on
  2558. FileType AS STRING * 1     'ret:1=BULLET XB data file
  2559. Dirty AS STRING * 1        'ret:0=not changed
  2560. Recs AS LONG               'ret:records in file
  2561. RecLen AS INTEGER          'ret:record length
  2562. Fields AS INTEGER          'ret:fields per record ()
  2563. f1 AS STRING * 1           'reserved (1=update DVmon)
  2564. LUyear AS STRING * 1       'ret:binary, year file last updated
  2565. LUmonth AS STRING * 1      'ret:month   --LUs are 0 if DBF newly created
  2566. LUday AS STRING * 1        'ret:day
  2567. HereSeg AS INTEGER         'ret:this file's control segment
  2568. filler AS STRING * 10      'reserved
  2569. END TYPE '32
  2570. See: StatKeyPack
  2571. ~StatKeyPack
  2572.  Src: StatKXBsrc       Func: StatKXB
  2573. TYPE StatKeyPack           'SKP
  2574. Func AS INTEGER            '23
  2575. Stat AS INTEGER            'ret:completion status
  2576. Handle AS INTEGER          'BULLET key file to get status on
  2577. FileType AS STRING * 1     'ret:0=BULLET XB key file
  2578. Dirty AS STRING * 1        'ret:0=not changed
  2579. Keys AS LONG               'ret:keys in file
  2580. KeyLen AS INTEGER          'ret:key length
  2581. XBlink AS INTEGER          'ret:related BULLET XB data file handle
  2582. XBrecno AS LONG            'ret:record number attached to current key
  2583. HereSeg AS INTEGER         'ret:this file's control segment
  2584. CodePageID AS INTEGER      'ret:code page ID number of key file sort
  2585. CountryCode AS INTEGER     'ret:country code number of key file sort
  2586. CollateTableSize AS INTEGER 'ret: size of collate table, 0 or 256
  2587. KeyFlags AS INTEGER        'ret:bit 0=unique,1=char,4=int,5=long,E=NLS,F=signed
  2588. filler AS STRING * 2
  2589. END TYPE '32
  2590. See: StatHandlePack
  2591. ~StatHandlePack
  2592.  Src: StatHandleXBsrc  Func: StatHandleXB
  2593. TYPE StatHandlePack        'SHP
  2594. Func AS INTEGER            '6
  2595. Stat AS INTEGER            'ret:completion status
  2596. Handle AS INTEGER          'file handle to get information on
  2597. ID AS INTEGER              'ret:0=XB index,1=XB data file,-1=not BULLET handle
  2598. END TYPE '8 bytes
  2599. See: XErrorPack
  2600. ~XErrorPack
  2601.  Src: GetExtErrorXBsrc Func: GetExtErrorXB
  2602. TYPE XErrorPack            'XEP
  2603. Func AS INTEGER            '7
  2604. Stat AS INTEGER            'ret:extended error
  2605. Class AS INTEGER           'ret:error class
  2606. Action AS INTEGER          'ret:suggested action
  2607. Location AS INTEGER        'ret:error location
  2608. END TYPE '10 bytes
  2609. See: AccessPack  Errors_DOS
  2610. ~Errors_BULLET    (200-209)
  2611. 200 key not found - The search key for Equal was not matched exactly.
  2612.     Next/Prev routines can be used to continue search from point of mismatch.
  2613. 201 key already exists - Attempted to add a key that already exists in the
  2614.     index file created to allow only unique keys.
  2615. 202 end of file - A Next routine is past the last key of the index file.
  2616. 203 top of file - A Prev routine is before the first key of the index file.
  2617. 204 key file empty - A key access was attempted with no keys in the index file.
  2618. 205 key type unknown - Generally indicates a corrupt index header (keyflags
  2619.     unknown at key insert).
  2620.     reserved,206-207
  2621. 208 no more nodes - The index file has reached full capacity (32MB). ReindexXB
  2622.     can often shrink an index file by 30 to 50%.
  2623. 209 key file corrupt - The index file is corrupt (write attempt to node 0).
  2624. See: Errors_BULLET_b
  2625. ~Errors_BULLET_b  (210-232)
  2626. 210 key file corrupt - The index file is corrupt (internal overflow).
  2627.     reserved,211-219
  2628. 220 incorrect DOS version - BULLET requires DOS 3.3 or later.
  2629. 221 invalid key length - The key is > 62 bytes (or 64 if unique specified).
  2630. 222 file not open - The specified handle is not an open BULLET file.
  2631.        
  2632.     reserved,223
  2633. 224 invalid record number - The specified record number is < 0, past the last
  2634.     record number in the .DBF, or is > 16,777,215.
  2635.     reserved,225-227
  2636. 228 invalid filetype - The specified handle is not the correct type for the
  2637.     operation (i.e., specifying a data file handle for a key file operation).
  2638.     reserved,229-232
  2639. See: Errors_BULLET_c
  2640. ~Errors_BULLET_c  (233-243)
  2641. 233 init not active - InitXB must be called before all others except MemoryXB.
  2642. 234 init already active - InitXB has already been called. Use ExitXB first to
  2643.     call InitXB more than once per process. (Make sure the xxP.Func <> 0.)
  2644. 235 too many indexes - BULLET can handle up to 32 index files per transaction
  2645.     record with the InsertXB and UpdateXB routines. Contact the author if you
  2646.     need to allow for more than 32 index files/transaction record.
  2647.     reserved,236-239
  2648. 240 invalid key expression - The CreateKXB key expression could not be
  2649.     evaluated.
  2650.     reserved,241
  2651. 242 field not found - The fieldname was not found in the descriptor area.
  2652. 243 invalid field count - Too many fields were specified or the specified field
  2653.     number is past the last field.
  2654. See: Errors_BULLET_d
  2655. ~Errors_BULLET_d  (244-255)
  2656.     reserved,244-249
  2657. 250 invalid country info - The specifed country code or code page ID is not
  2658.     valid or not installed (according to DOS).
  2659. 251 invalid collate table size - The specified country code/code page ID uses
  2660.     a collate-sequence table > 256 bytes (2-byte characters as with Kanji).
  2661. 252 invalid keyflags - The specified keyflags are invalid.
  2662.     reserved,253-254
  2663. 255 evaluation mode shutdown - BULLET evaluation period has completed.
  2664.     You can reinstall to continue evaluation, though you may want to consider
  2665.     your motives for reinstalling since the original evaluation period has
  2666.     expired. This error occurs only after the evaluation period has expired.
  2667.     It is not recommended that you continue to use BULLET after the evaluation
  2668.     period. It is possible for no 255 error to be generated for quite some
  2669.     time since it occurs only under certain load conditions and then only when
  2670.     certain routine sequences are performed. The specified evaluation period of
  2671.     21 days should be adhered to.
  2672. See: Errors_BASIC
  2673. ~Errors_BASIC
  2674.  1 NEXT without FOR                    24 device timeout
  2675.  2 syntax error                        25 device fault
  2676.  3 RETURN without GOSUB                26 FOR without NEXT
  2677.  4 out of DATA                         27 out of paper
  2678.  5 illegal function call               29 WHILE without WEND
  2679.  6 overflow                            30 WEND without WHILE
  2680.  7 out of memory                          reserved,31-32
  2681.  8 label not defined                   33 duplicate label
  2682.  9 subscript out of range                 reserved,34
  2683. 10 duplicate definition                35 subprogram not defined
  2684. 11 division by zero                       reserved,36
  2685. 12 illegal in direct mode              37 argument-count mismatch
  2686. 13 type mismatch                       38 array not defined
  2687. 14 out of string space                    reserved,39
  2688.    reserved,15                         40 variable required
  2689. 16 string formula too complex             reserved,41-49
  2690. 17 cannot continue                     50 FIELD overflow
  2691. 18 function not defined                51 internal error
  2692. 19 no RESUME                           52 bad file name or number
  2693. 20 RESUME without error                53 file not found
  2694.    reserved,21-23                      54 bad file mode
  2695. See: Errors_BASIC_b
  2696. ~Errors_BASIC_b
  2697. 55 file already open                      reserved,77-79
  2698. 56 FIELD statement active              80 feature removed
  2699. 57 device I/O error                    81 invalid name
  2700. 58 file already exists                 82 table not found
  2701. 59 bad record length                   83 index not found
  2702.    reserved,60                         84 invalid column
  2703. 61 disk full                           85 no current record
  2704. 62 input past end of file              86 duplicate value for unique index
  2705. 63 bad record number                   87 invalid operation on null index
  2706. 64 bad file name                       88 database needs repair
  2707.    reserved,65-66                      89 insufficient ISAM buffers
  2708. 67 too many files
  2709. 68 device unavailable
  2710. 69 communication-buffer overflow
  2711. 70 permission denied
  2712. 71 disk not ready
  2713. 72 disk-media error
  2714. 73 feature unavailable
  2715. 74 rename across disks
  2716. 75 path/File access error
  2717. 76 path not found
  2718. See: Errors_DOS
  2719. ~Errors_DOS
  2720. -2 disk full or unexpected end of file
  2721. -1 bad filename
  2722.  0 no error
  2723.  1 function not supported              19 disk write protected
  2724.  2 file not found                      20 unknown unit
  2725.  3 path not found                      21 drive not ready
  2726.  4 too many open files                 22 unknown command
  2727.  5 access denied (see Specs_Networks)  23 data error (CRC)
  2728.  6 handle invalid                      24 bad request structure length
  2729.  7 MCBs destroyed                      25 seek error
  2730.  8 not enough memory                   26 unknown medium type
  2731.  9 memory block address invalid        27 sector not found
  2732. 10 environment invalid                 28 printer out of paper
  2733. 11 format invalid                      29 write fault
  2734. 12 access code invalid                 30 read fault
  2735. 13 data invalid                        31 general failure
  2736.    reserved-0Eh                        32 sharing violation
  2737. 15 disk drive invalid                  33 lock violation
  2738. 16 cannot remove current directory     34 disk change invalid/wrong disk
  2739. 17 not same device                     35 FCB unavailable
  2740. 18 no more files                       36 sharing buffer overflow
  2741. See: Errors_DOS_b
  2742. ~Errors_DOS_b
  2743. 37 code page mismatched                58 incorrect response from network
  2744. 38 handle EOF                          59 unexpected network error
  2745. 39 handle disk full                    60 incompatible remote adapter
  2746.    reserved-28h                        61 print queue full
  2747.    reserved-29h                        62 no spool space
  2748.    reserved-2Ah                        63 not enough space to print file
  2749.    reserved-2Bh                        64 network name deleted
  2750.    reserved-2Ch                        65 network access denied
  2751.    reserved-2Dh                        66 network device type incorrect
  2752.    reserved-2Eh                        67 network name not found
  2753.    reserved-2Fh                        68 network name limit exceeded
  2754.    reserved-30h                        69 NETBIOS session limit exceeded
  2755.    reserved-31h                        70 sharing temporarily paused
  2756. 50 network request not supported       71 network request not accepted
  2757. 51 remote computer not listening       72 print/disk redirection paused
  2758. 52 duplicate name on network              reserved-49h
  2759. 53 network pathname not found             reserved-4Ah
  2760. 54 network busy                           reserved-4Bh
  2761. 55 network device no longer exists        reserved-4Ch
  2762. 56 NETBIOS command limit exceeded         reserved-4Dh
  2763. 57 network adapter hardware error         reserved-4Eh
  2764. See: Errors_DOS_c
  2765. ~Errors_DOS_c
  2766.    reserved-4Fh                  
  2767.  DOS Class Codes 
  2768. 80 file exists
  2769. 81 duplicate FCB                 1 out of resources       7 application error
  2770. 82 cannot make                   2 temporary situation    8 not found
  2771. 83 fail on INT24                 3 authorization          9 bad format
  2772. 84 out of structures             4 internal error        10 locked
  2773. 85 already assigned              5 hardware failure      11 media failure
  2774. 86 invalid password              6 system failure        12 already exists
  2775. 87 invalid parameter                                     13 unknown
  2776. 88 network write fault
  2777.    reserved-59h                    DOS Action Codes         DOS Locus Codes
  2778. 90 sys comp not loaded
  2779.                                  1 retry immediately      1 unknown
  2780.                                  2 delay and retry        2 block device
  2781.                                  3 reenter input          3 network
  2782.                                  4 abort ASAP             4 serial device
  2783.                                  5 abort immediately      5 memory
  2784.                                  6 ignore error
  2785.                                  7 user intervention
  2786. See: Errors_BULLET
  2787. ~InitXBsrc
  2788. Func: InitXB           Pack: InitPack           Func:   0/System
  2789. DIM IP AS InitPack
  2790. DIM EP AS ExitPack
  2791. IP.Func = InitXB        'InitXB defined in BULLET.BI
  2792. IP.JFTmode = 1          'expand JFT to 255 handles
  2793. stat = BULLET(IP)
  2794. IF stat = 0 THEN
  2795.    DOSmajor = IP.DOSver\256
  2796.    DOSminor = IP.DOSver MOD 256
  2797.    BULLETver = IP.Version
  2798.    SegExitXB = IP.ExitSeg
  2799.    OffExitXB = IP.ExitOff
  2800.    EP.Func = AtExitXB   'register ExitXB with _atexit shutdown routine
  2801.    stat = BULLET(EP)
  2802. ENDIF
  2803. IF stat THEN 'error
  2804. See: ExitXBsrc
  2805. ~ExitXBsrc
  2806. Func: ExitXB           Pack: ExitPack           Func:   1/System
  2807. DIM EP AS ExitPack
  2808. EP.Func = ExitXB        'ExitXB defined in BULLET.BI
  2809. stat = BULLET(EP)
  2810. The return value from ExitXB is currently always 0.
  2811. See: AtExitXBsrc
  2812. ~AtExitXBsrc
  2813. Func: AtExitXB         Pack: ExitPack           Func:   2/System
  2814. DIM IP AS InitPack
  2815. DIM EP AS ExitPack
  2816. IP.Func = InitXB
  2817. IP.JFTmode = 1
  2818. stat = BULLET(IP)
  2819. IF stat = 0 THEN
  2820.    DOSmajor = IP.DOSver\256
  2821.    DOSminor = IP.DOSver MOD 256
  2822.    SegExitXB = IP.ExitSeg
  2823.    OffExitXB = IP.ExitOff
  2824.                         'register ExitXB with _atexit shutdown routine
  2825.    EP.Func = AtExitXB   'AtExitXB defined in BULLET.BI
  2826.    stat = BULLET(EP)    'the return value is that returned from the compiler
  2827.                         '_atexit routine, 0=okay, anything else is an error
  2828. ENDIF                   'indicating, for example, the _atexit register is full
  2829. IF stat THEN 'error
  2830. See: MemoryXBsrc
  2831. ~MemoryXBsrc
  2832. Func: MemoryXB         Pack: MemoryPack         Func:   3/System
  2833. DIM MP AS MemoryPack
  2834. WorkSpace& = 50000      'a value at least 40K or so
  2835. MemoryNeeded& = WorkSpace& + (144&+ ((1+NF)*32)) * TotalOpenDataFiles _
  2836.                            + (1264& * TotalOpenKeyFiles)
  2837. MP.Func = MemoryXB
  2838. stat = BULLET(MP)
  2839. IF MP.Memory < MemoryNeeded& THEN
  2840.     QBheap& = SETMEM(-MemoryNeeded& + 4096)  'release what we need+QB fudge
  2841.     MP.Func = MemoryXB
  2842.     stat = BULLET(MP)
  2843.     IF MP.Memory < MemoryNeeded& THEN 'not enough memory
  2844. END IF
  2845. MP.Memory does not reflect memory available through DOS in the UMB area. It's
  2846. possible that all memory requests can be satisfied by UMB RAM. Consult a DOS 5+
  2847. programmer reference for more information on this (see DOS INT21/58 for more).
  2848. In the QuickBASIC/BASIC PDS environment do not call SETMEM(-x) more than once.
  2849. See: BreakXBsrc
  2850. ~BreakXBsrc
  2851. Func: BreakXB          Pack: BreakPack          Func:   4/System
  2852. DIM BP AS BreakPack
  2853. BP.Func = BreakXB       'BreakXB defined in BULLET.BI
  2854. BP.Mode = 0             'disable Ctrl-C/Ctrl-BREAK (do nothing on those keys)
  2855. stat = BULLET(BP)       'stat=0 always
  2856. If BreakXB is called multiple times with the same BP.mode each time, only the
  2857. first is acted on. You can set BP.mode = 1 to restore the default handlers
  2858. (those installed originally) and then again set BP.Mode = 0 to disable them.
  2859. ExitXB calls this routine automatically as part of the BULLET shutdown to
  2860. restore the original default break handlers.
  2861. See: BackupFileXBsrc
  2862. ~BackupFileXBsrc
  2863. Func: BackupFileXB     Pack: CopyPack           Func:   5/System
  2864. DIM AP AS AccessPack
  2865. DIM CP AS CopyPack
  2866. DIM TempStr AS STRING * 80      'used as fixed-length string for VARPTR()
  2867.                                 'so same source QB AND BASIC7 /Fs compatible
  2868. TempStr = NewFilename$          'assign the var-len string to fixed-len str
  2869. CP.Func = BackupFileXB  'defined in BULLET.BI
  2870. CP.Handle = DataHandle  'handle of data file to backup
  2871. CP.FilenamePtrOff = VARPTR(TempStr) 'ALWAYS use VARPTR() on fixed-len string
  2872. CP.FilenamePtrSeg = VARSEG(TempStr) 'ALWAYS use VARSEG() on fixed-len string
  2873. stat = BULLET(CP)       'copy the data file to the file NewFilename$
  2874. IF stat = 0 THEN
  2875.    AP.Func = PackRecordsXB
  2876.    AP.Handle = DataHandle
  2877.    stat = BULLET(AP)
  2878. ENDIF
  2879. IF stat THEN 'error
  2880. See: StatHandleXBsrc
  2881. ~StatHandleXBsrc
  2882. Func: StatHandleXB     Pack: StatHandlePack     Func:   6/System
  2883. DIM SHP AS StatHandlePack
  2884. DIM SKP AS StatKeyPack
  2885. DIM SDP AS StatDataPack
  2886. SHP.Func = StatHandleXB 'defined in BULLET.BI
  2887. SHP.Handle = TheHandleNumber
  2888. stat = BULLET(SHP)
  2889. IF SHP.ID = 0 THEN      'handle belongs to an index file (index file/key file)
  2890.    SKP.Func = StatKXB   'get key stats  -- see StatKXB/StatDXB for more
  2891.    SKP.Handle = PassedHandleNumber      ' on the SKP structure
  2892.    stat = BULLET(SKP)
  2893. ELSEIF SHP.ID = 1 THEN  '.DBF data file
  2894.    'get DBF stats
  2895.    'error not a BULLET file type
  2896. ENDIF
  2897. See: GetExtErrorXBsrc
  2898. ~GetExtErrorXBsrc
  2899. Func: GetExtErrorXB    Pack: XErrorPack         Func:   7/System
  2900. 'an error just occured in the range 1 to 199 as returned in one of the
  2901. 'pack.Stat variables (current max DOS error is 90 (5Ah))
  2902. 'remember, transaction-based routines return a bad pack index in the return
  2903. 'stat value, which you use to check the appropriate pack.Stat variable
  2904. DIM XEP AS XErrorPack
  2905. XEP.Func = GetExtErrorXB 'defined in BULLET.BI
  2906. stat = BULLET(XEP)
  2907. IF stat <> 0 THEN
  2908.    PRINT "Extended Codes --"
  2909.    PRINT "            error: "; XEP.Stat
  2910.    PRINT "      error class: "; XEP.Class
  2911.    PRINT "recommened action: "; XEP.Action
  2912.    PRINT "         location: "; XEP.Location
  2913.    PRINT "No error"
  2914. ENDIF
  2915. See: DVmonCXBsrc  StatKXB
  2916. ~DVmonCXBsrc
  2917. Func: DVmonCXB         Pack: DVmonPack          Func:   9/DEBUG
  2918. 'at this point a data file and a key file have been opened
  2919. 'kf is that key file's DOS handle
  2920. DIM DV AS DVmonPack
  2921. DV.Func = DVmonCXB      'defined in BULLET.BI
  2922. DV.Mode = 1             'enable monitoring
  2923. DV.Handle = kf          'monitor key file handle, kf (and its XBlink data file)
  2924. DV.VideoSeg = &HB800+(4096\16)  'output to color screen, page 1 (pages 0 to ?)
  2925. stat = BULLET(DV)       'stat=0 always even if not DEBUG ENGINE
  2926. For two-monitor systems (with a color monitor as the main system) output should
  2927. be directed to &HB000, the mono monitor's video memory.
  2928. DVmonCXB stands for Dual Video Monitor Control XB.
  2929. See: CreateDXBsrc
  2930. ~CreateDXBsrc
  2931. Func: CreateDXB        Pack: CreateDataPack     Func:  10/Mid-level
  2932. DIM CDP AS CreateDataPack
  2933. DIM TempStr AS STRING * 80      'used as fixed-length string for VARPTR()
  2934. REDIM FD(1 TO 2) AS FieldDescTYPE 'field descriptions for each of the fields...
  2935.                                   '...in the record (record has 2 fields)
  2936. TempStr = filename$ + CHR$(0)   'assign filename to a fixed-len string...
  2937.                                 '...so we can use VARSEG/VARPTR
  2938. 'build FD first for each of the fields in the record
  2939. FD(1).FieldName = "STUDENT" + STRING$(10,0)   'must be zero-filled
  2940. FD(1).FieldType = "C"           'a character field type
  2941. FD(1).FieldLength = CHR$(20)    'up to 20 characters (a byte field--use CHR$())
  2942. FD(1).FieldDC = CHR$(0)         'non-numeric has no decimal places
  2943. FD(2).FieldName = "SCORE" + STRING$(10,0)
  2944. FD(2).FieldType = "N"
  2945. FD(2).FieldLength = CHR$(3)     'dBASE numeric format, allow for "100"
  2946. FD(2).FieldDC = CHR(0)          'no decimal places used for this field
  2947. '(cont)
  2948.                      'for BINARY FieldType="B" see FieldDescTYPE
  2949. See: CreateDXBsrc_a                                                     -MORE-
  2950. ~CreateDXBsrc_a
  2951. 'build the CDP
  2952. CDP.Func = CreateDXB            'defined in BULLET.BI
  2953. CDP.FilenamePtrOff = VARPTR(TempStr) 'point to filenameZ (Z=0-terminated str)
  2954. CDP.FilenamePtrSeg = VARSEG(TempStr)
  2955. CDP.NoFields = 2                'this example has 2 fields
  2956. CDP.FieldListPtrOff = VARPTR(FD(1)) 'point to the first field decription...
  2957. CDP.FieldListPtrSeg = VARPTR(FD(1)) '...defined in the previous screen
  2958. CDP.FileID = 3                  'standard dBASE file ID
  2959. stat = BULLET(CDP)              'create the DBF data file
  2960. IF stat THEN 'error
  2961. Normally this code would be written as a generalized FUNCTION. The CDP could be
  2962. a global allocation (DIM SHARED CDP AS CreateDataPack) and the FD() would also
  2963. be (REDIM [SHARED] FD(1 TO 1) AS FieldDescTYPE) and REDIM'd to needed size when
  2964. used. A possible header:
  2965.  DECLARE FUNCTION CreateDBF% (filename$, NoFields%, FD() AS FieldDescTYPE)
  2966. To create a DBF you'd need just the filename, number of fields, REDIM the FD()
  2967. array (if needed), fill in FD() array, then call the function. Look at the
  2968. source code examples on the distribution disk for more.
  2969. See: OpenDXBsrc  CreateDXBsrc
  2970. ~OpenDXBsrc
  2971. Func: OpenDXB          Pack: OpenPack           Func:  11/Mid-level
  2972. DIM OP AS OpenPack
  2973. DIM TempStr AS STRING * 80      'used as fixed-length string for VARPTR()
  2974. TempStr = filename$ + CHR$(0)   'assign filename to a fixed-len string...
  2975. OP.Func = OpenDXB                   'defined in BULLET.BI
  2976. OP.FilenamePtrOff = VARPTR(TempStr) 'point to filenameZ (Z=0-terminated str)
  2977. OP.FilenamePtrSeg = VARSEG(TempStr)
  2978. OP.ASmode = ReadWrite + DenyNone    'defined in BULLET.BI
  2979. stat = BULLET(OP)
  2980. IF stat THEN 'error
  2981. The ASmode (access/sharing mode) determines how the operating system controls
  2982. access to the file. See OpenFileDOS for the meanings of the various ASmodes.
  2983. See: CloseDXBsrc  OpenFileDOS
  2984. ~CloseDXBsrc
  2985. Func: CloseDXB         Pack: HandlePack         Func:  12/Mid-level
  2986. DIM HP AS HandlePack
  2987. HP.Func = CloseDXB              'defined in BULLET.BI
  2988. HP.Handle = datahandle          'handle of the file to close
  2989. stat = BULLET(HP)
  2990. IF stat THEN 'error
  2991. See: StatDXBsrc
  2992. ~StatDXBsrc
  2993. Func: StatDXB          Pack: StatDataPack       Func:  13/Mid-level
  2994. DIM SDP AS StatDataPack
  2995. SDP.Func = StatDXB          'defined in BULLET.BI
  2996. SDP.Handle = datahandle     'data handle to get stats on
  2997. stat = BULLET(SDP)          'must be a data handle, use StatHandleXB if you...
  2998. IF stat = 0 THEN            '...don't know the type of file a handle's for
  2999.    'SDP.FileType is set to 1
  3000.    'SDP.Dirty is set to 1 if the file has changed (0=not changed)
  3001.    'SDP.Recs = number of records in the DBF file
  3002.    'SDP.RecLen = record length
  3003.    'SDP.Fields = number of fields in the record
  3004.    'SDP.f1 is reserved
  3005.    'SDP.LUyear = year file last updated, binary (year = ASC(SDP.LUyear))
  3006.    'SDP.LUmonth = month, binary
  3007.    'SDP.LUday = day, binary
  3008.    'SDP.HereSeg is set to this handle's control segment (location in memory)
  3009.    'error
  3010. ENDIF
  3011. See: ReadDHXBsrc
  3012. ~ReadDHXBsrc
  3013. Func: ReadDHXB         Pack: HandlePack         Func:  14/Mid-level
  3014. DIM HP AS HandlePack
  3015. HP.Func = ReadDHXB              'defined in BULLET.BI
  3016. HP.Handle = datahandle          'handle of file whose header you want to reload
  3017. stat = BULLET(HP)
  3018. IF stat THEN 'error
  3019. This routine is automatically called by the network lock routines.
  3020. See: FlushDHXBsrc  LockDataXB
  3021. ~FlushDHXBsrc
  3022. Func: FlushDHXB        Pack: HandlePack         Func:  15/Mid-level
  3023. DIM HP AS HandlePack
  3024. HP.Func = FlushDHXB             'defined in BULLET.BI
  3025. HP.Handle = datahandle          'handle of file you want to flush
  3026. stat = BULLET(HP)
  3027. IF stat THEN 'error
  3028. Note that the physical write to disk is performed only if the file has changed
  3029. since the open or last flush.
  3030. This routine is automatically called by the network unlock routines.
  3031. See: CopyDHXBsrc  UnlockDataXB
  3032. ~CopyDHXBsrc
  3033. Func: CopyDHXBsrc      Pack: CopyPack           Func:  16/Mid-level
  3034. DIM CP AS CopyPack
  3035. DIM TempStr AS STRING * 80      'used as fixed-length string for VARPTR()
  3036. TempStr = filename$ + CHR$(0)   'assign filename to a fixed-len string...
  3037. CP.Func = CopyDHXB              'defined in BULLET.BI
  3038. CP.Handle = datahandle          'handle of file to copy from (the source)
  3039. CP.FilenamePtrOff = VARPTR(TempStr) 'far pointer to filenameZ for copy
  3040. CP.FilenamePtrSeg = VARPTR(TempStr) '(the destination)
  3041. stat = BULLET(CP)
  3042. IF stat THEN 'error
  3043. See: ZapDHXBsrc
  3044. ~ZapDHXBsrc
  3045. Func: ZapDHXB          Pack: HandlePack         Func:  17/Mid-level
  3046. DIM HP AS HandlePack
  3047. HP.Func = ZapDHXB               'defined in BULLET.BI
  3048. HP.Handle = datahandle          'handle of file you want !ZAP!
  3049. stat = BULLET(HP)
  3050. IF stat THEN 'error
  3051. Note that this removes ALL data records from the data file.
  3052. See: CreateKXBsrc
  3053. ~CreateKXBsrc
  3054. Func: CreateKXB        Pack: CreateKeyPack      Func:  20/Mid-level
  3055. 'This code assumes that the datafile was created as in CreateDXBsrc, and that
  3056. 'the datafile was opened as in OpenDXBsrc.
  3057. kx$ = "SUBSTR(STUDENT,1,5)"     'key expression, a non-unique, character key
  3058. DIM CKP AS CreateKeyPack
  3059. DIM TempStr AS STRING * 80      'used as fixed-length string for VARPTR()
  3060. DIM TempStr2 AS STRING * 136    'used as fixed-length string for VARPTR()
  3061. TempStr = filename$ + CHR$(0)   'assign filename to a fixed-len string
  3062. TempStr2 = kx$ + CHR$(0)        'same for key expression string
  3063. '(cont)
  3064. See: CreateKXBsrc_a                                                     -MORE-
  3065. ~CreateKXBsrc_a
  3066. CKP.Func = CreateKXB                 'defined in BULLET.BI
  3067. CKP.FilenamePtrOff = VARPTR(TempStr) 'far pointer to filenameZ
  3068. CKP.FilenamePtrSeg = VARSEG(TempStr)
  3069. CKP.KeyExpPtrOff = VARPTR(TempStr2)  'far pointer to key expressionZ
  3070. CKP.KeyExpPtrSeg = VARSEG(TempStr2)
  3071. CKP.XBlink = datahandle              'the datafile handle returned from OpenDXB
  3072. CKP.KeyFlags = cCHAR                 '-KEYFLAGS- are defined in BULLET.BI
  3073. CKP.CodePageID = -1                  'use DOS default code page ID
  3074. CKP.CountryCode = -1                 'use DOS default country code
  3075. CKP.CollatePtrOff = 0                'no user-supplied collate table...
  3076. CKP.CollatePtrSeg = 0                '...
  3077. stat = BULLET(CKP)
  3078. IF stat THEN 'error
  3079. Normally this code would be written as a generalized FUNCTION. The CKP could be
  3080. a global allocation (DIM SHARED CKP AS CreateKeyPack). A possible header:
  3081.  DECLARE FUNCTION CreateNewIndex% (filename$, datahandle, kx$, KeyFlags%)
  3082. To create an index file you'd need just filename, datahandle, key expression,
  3083. and key flags (country code info if not using default), then call the function.
  3084. See: OpenKXBsrc  CreateKXBsrc
  3085. ~OpenKXBsrc
  3086. Func: OpenKXB          Pack: OpenPack           Func:  21/Mid-level
  3087. DIM OP AS OpenPack
  3088. DIM TempStr AS STRING * 80      'used as fixed-length string for VARPTR()
  3089. TempStr = filename$ + CHR$(0)   'assign filename to a fixed-len string...
  3090. OP.Func = OpenKXB                   'defined in BULLET.BI
  3091. OP.FilenamePtrOff = VARPTR(TempStr) 'point to filenameZ (Z=0-terminated str)
  3092. OP.FilenamePtrSeg = VARSEG(TempStr)
  3093. OP.ASmode = ReadWrite + DenyNone    'defined in BULLET.BI
  3094. OP.XBlink = datafilehandle          'OpenKXB needs to know the data file handle
  3095. stat = BULLET(OP)
  3096. IF stat THEN 'error
  3097. The ASmode (access/sharing mode) determines how the operating system controls
  3098. access to the file. See OpenFileDOS for the meanings of the various ASmodes.
  3099. Before you can open an index file you must first open its associated data file.
  3100. See: CloseKXBsrc  OpenFileDOS
  3101. ~CloseKXBsrc
  3102. Func: CloseKXB         Pack: HandlePack         Func:  22/Mid-level
  3103. DIM HP AS HandlePack
  3104. HP.Func = CloseDXB              'defined in BULLET.BI
  3105. HP.Handle = indexhandle         'handle of the file to close
  3106. stat = BULLET(HP)
  3107. IF stat THEN 'error
  3108. See: StatKXBsrc
  3109. ~StatKXBsrc
  3110. Func: StatKXB          Pack: StatKeyPack        Func:  23/Mid-level
  3111. DIM SKP AS StatKeyPack
  3112. SKP.Func = StatKXB          'defined in BULLET.BI
  3113. SKP.Handle = indexhandle    'handle to get stats on
  3114. stat = BULLET(SKP)          'must be index handle, use StatHandleXB if you...
  3115. IF stat = 0 THEN            '...don't know the type of file a handle's for
  3116.    'SKP.FileType is set to 0
  3117.    'SKP.Dirty is set to 1 if the file has changed (0=not changed)
  3118.    'SKP.Keys = number of key in the index file (index file=key file)
  3119.    'SKP.KeyLen = physical key length (1-64 bytes)
  3120.    'SKP.XBlink = datafile handle that this index file is associated with
  3121.    'SKP.XBrecno is set to record number associated with last accessed key
  3122.    'SKP.HereSeg is set to this handle's control segment (location in memory)
  3123.    'SKP.CodePageID returns this index file's permanent code page ID
  3124.    'SKP.CountryCode returns this index file's permanent country code
  3125.    'SKP.CollateTableSize = 0 (no collate table present) or 256 (table present)
  3126.    'SKP.KeyFlags = key flags specifed at CreateKXB (except NLS flag may be set)
  3127. ELSE                                               (NLS flag is bit 14, &H4000)
  3128.    'error
  3129. See: ReadKHXBsrc
  3130. ~ReadKHXBsrc
  3131. Func: ReadKHXB         Pack: HandlePack         Func:  24/Mid-level
  3132. DIM HP AS HandlePack
  3133. HP.Func = ReadKHXB              'defined in BULLET.BI
  3134. HP.Handle = indexhandle         'handle of file whose header you want to reload
  3135. stat = BULLET(HP)
  3136. IF stat THEN 'error
  3137. This routine is automatically called by the network lock routines.
  3138. See: FlushKHXBsrc  LockKeyXB
  3139. ~FlushKHXBsrc
  3140. Func: FlushKHXB        Pack: HandlePack         Func:  25/Mid-level
  3141. DIM HP AS HandlePack
  3142. HP.Func = FlushKHXB             'defined in BULLET.BI
  3143. HP.Handle = indexhandle         'handle of file you want to flush
  3144. stat = BULLET(HP)
  3145. IF stat THEN 'error
  3146. Note that the physical write to disk is performed only if the file has changed
  3147. since the open or last flush.
  3148. This routine is automatically called by the network unlock routines.
  3149. See: CopyKHXBsrc  UnlockKeyXB
  3150. ~CopyKHXBsrc
  3151. Func: CopyKHXBsrc      Pack: CopyPack           Func:  26/Mid-level
  3152. DIM CP AS CopyPack
  3153. DIM TempStr AS STRING * 80      'used as fixed-length string for VARPTR()
  3154. TempStr = filename$ + CHR$(0)   'assign filename to a fixed-len string...
  3155. CP.Func = CopyKHXB              'defined in BULLET.BI
  3156. CP.Handle = indexhandle         'handle of file to copy from (the source)
  3157. CP.FilenamePtrOff = VARPTR(TempStr) 'far pointer to filenameZ for copy
  3158. CP.FilenamePtrSeg = VARPTR(TempStr) '(the destination)
  3159. stat = BULLET(CP)
  3160. IF stat THEN 'error
  3161. See: ZapKHXBsrc
  3162. ~ZapKHXBsrc
  3163. Func: ZapKHXB          Pack: HandlePack         Func:  27/Mid-level
  3164. DIM HP AS HandlePack
  3165. HP.Func = ZapKHXB               'defined in BULLET.BI
  3166. HP.Handle = indexhandle         'handle of file you want !ZAP!
  3167. stat = BULLET(HP)
  3168. IF stat THEN 'error
  3169. Note that this removes ALL keys from the index file.
  3170. See: GetDescriptorXBsrc
  3171. ~GetDescriptorXBsrc
  3172. Func: GetDescriptorXB  Pack: DescriptorPack     Func:  30/Mid-level
  3173. DIM DP AS DescriptorPack
  3174. DP.Func = GetDescriptorXB               'defined in BULLET.BI
  3175. DP.Handle = datahandle                  'handle of file
  3176. IF FieldNumber > 0 THEN
  3177.    DP.FieldNumber = FieldNumber         'field number to get info on
  3178. ELSE                                    'or, if 0, then
  3179.    DP.FieldNumber = 0
  3180.    DP.FD.FieldName = fieldname$ + STRING$(10,0)   'fieldname$ to get info on
  3181. ENDIF
  3182. stat = BULLET(DP)
  3183. IF stat = 0 THEN
  3184.    'DP.FD.FieldName is set to field name
  3185.    'DP.FD.FieldType is set to field type
  3186.    'DP.FD.FieldLen is set to field length
  3187.    'DP.FD.FieldDC is set to field DC
  3188. ELSE         
  3189.    'error    
  3190. The DP.FD.FieldLen (and DP.FD.FieldDC) is a byte string so you 
  3191.              
  3192. need to use a FldLen=ASC(DP.FD.FieldLen) for its integer value 
  3193.              
  3194. See: GetRecordXBsrc
  3195. ~GetRecordXBsrc
  3196. Func: GetRecordXB      Pack: AccessPack         Func:  31/Mid-level
  3197. TYPE RecordTYPE                 'simple DBF record layout
  3198. tag AS STRING * 1  <
  3199. code AS STRING * 4     
  3200. THE FIRST BYTE OF YOUR RECORD TYPES MUST BE TAG! 
  3201. bday AS STRING * 8     
  3202. END TYPE
  3203. DIM RecBuff AS RecordTYPE       'record has 2 fields, code/C/4.0, bday/D/8.0
  3204. DIM AP AS AccessPack
  3205. AP.Func = GetRecordXB           'defined in BULLET.BI
  3206. AP.Handle = datahandle          'handle to get record from
  3207. AP.RecNo = RecnoToGet&          'record number to get
  3208. AP.RecPtrOff = VARPTR(RecBuff)  'read record from disk into RecBuff
  3209. AP.RecPtrSeg = VARSEG(RecBuff)
  3210. stat = BULLET(AP)
  3211. IF stat = 0 THEN
  3212.    PRINT RecBuff.code ; ", " ; RecBuff.bday     'sample output: 4321, 19331122
  3213.    'error
  3214. See: AddRecordXBsrc
  3215. ~AddRecordXBsrc
  3216. Func: AddRecordXB      Pack: AccessPack         Func:  32/Mid-level
  3217. TYPE RecordTYPE                 'simple DBF record layout
  3218. tag AS STRING * 1  <
  3219. code AS STRING * 4     
  3220. THE FIRST BYTE OF YOUR RECORD TYPES MUST BE TAG! 
  3221. bday AS STRING * 8     
  3222. END TYPE
  3223. DIM RecBuff AS RecordTYPE       'record has 2 fields, code/C/4.0, bday/D/8.0
  3224. DIM AP AS AccessPack
  3225. 'be sure to init the tag field to a space (ASCII 32)
  3226. RecBuff.tag = " " : RecBuff.code = "1234" : RecBuff.bday = "19331122"
  3227. AP.Func = AddRecordXB           'defined in BULLET.BI
  3228. AP.Handle = datahandle          'handle to add record to
  3229. AP.RecPtrOff = VARPTR(RecBuff)  'write record from RecBuff to disk...
  3230. AP.RecPtrSeg = VARSEG(RecBuff)  '...at next available record number
  3231. stat = BULLET(AP)
  3232. IF stat = 0 THEN
  3233.    PRINT "Record number used by AddRecordXB was "; AP.RecNo
  3234. ELSE 'error
  3235. See: UpdateRecordXBsrc
  3236. ~UpdateRecordXBsrc
  3237. Func: UpdateRecordXB   Pack: AccessPack         Func:  33/Mid-level
  3238. 'see GetRecordXBsrc for this source example's preliminary code
  3239. AP.Func = GetRecordXB           'first get the record to update
  3240. AP.Handle = datahandle
  3241. AP.RecNo = RecnoToGet&          '
  3242. AP.RecPtrOff = VARPTR(RecBuff)  '
  3243.  Do NOT use UpdateRecordXB to change   
  3244. AP.RecPtrSeg = VARSEG(RecBuff)  '
  3245.  any field(s) used in a key expression.
  3246. stat = BULLET(AP)               '
  3247.  Instead use UpdateXB.                 
  3248. IF stat = 0 THEN                '
  3249.    RecBuff.dbay = "19591122"    'change only non-key portions of record
  3250.    AP.Func = UpdateRecordXB     'defined in BULLET.BI
  3251.    stat = BULLET(AP)            'other AP. values are already set from the Get
  3252.    IF stat THEN                 'though you should reassign AP.RecPtrOff/Seg if
  3253.       'error                    'you perform any BASIC string functions between
  3254. 'BULLET calls (none were in this case).
  3255. NOTE: QB/PDS will move strings
  3256. '--by this I mean to set these again
  3257. after a user-break/Ctrl-Break 
  3258. '  AP.RecPtrOff = VARPTR(RecBuff)
  3259. in the QB/QBX environment !!! 
  3260. '  AP.RecPtrSeg = VARSEG(RecBuff)
  3261. '  stat = BULLET(AP) 'do the update call
  3262. See: DeleteRecordXBsrc  UpdateXB
  3263. ~DeleteRecordXBsrc
  3264. Func: DeleteRecordXB   Pack: AccessPack         Func:  34/Mid-level
  3265. DIM AP AS AccessPack
  3266. AP.Func = DeleteRecordXB        'defined in BULLET.BI
  3267. AP.Handle = datahandle          'handle of record to delete
  3268. AP.RecNo = RecnoToDelete&       'to determine which record number any record
  3269. stat = BULLET(AP)               'is, use one of the keyed access routines
  3270. IF stat THEN 'error
  3271. See: UndeleteRecordsrc (XB)
  3272. ~UndeleteRecordsrc (XB)
  3273. Func: UndeleteRecordXB Pack: AccessPack         Func:  35/Mid-level
  3274. DIM AP AS AccessPack
  3275. AP.Func = UndeleteRecordXB      'defined in BULLET.BI
  3276. AP.Handle = datahandle          'handle of record to undelete
  3277. AP.RecNo = RecnoToUndelete&     'to determine which record number any record
  3278. stat = BULLET(AP)               'is use one of the keyed access routines
  3279. IF stat THEN 'error
  3280. See: PackRecordsXBsrc
  3281. ~PackRecordsXBsrc
  3282. Func: PackRecordsXB    Pack: AccessPack         Func:  36/Mid-level
  3283. DIM AP AS AccessPack
  3284. AP.Func = PackRecordsXB         'defined in BULLET.BI
  3285. AP.Handle = datahandle          'handle of data file to pack
  3286. stat = BULLET(AP)
  3287. IF stat THEN 'error
  3288. See: FirstKeyXBsrc
  3289. ~FirstKeyXBsrc
  3290. Func: FirstKeyXB       Pack: AccessPack         Func:  40/Mid-level
  3291. DIM AP AS AccessPack
  3292. DIM TempStr AS STRING * 64      'used as fixed-length string for VARPTR()
  3293.                                 'needs to be at least key length (MAXKEYLEN=64)
  3294. AP.Func = FirstKeyXB            'defined in BULLET.BI
  3295. AP.Handle = indexhandle         'handle to index file to access key from
  3296. AP.KeyPtrOff = VARPTR(TempStr)  'far pointer to key buffer
  3297. AP.KeyPtrSeg = VARSEG(TempStr)  '(the first key is read from disk and put here)
  3298. stat = BULLET(AP)
  3299. IF stat = 0 THEN
  3300.    'TempStr is filled in with the key (for as many bytes as the key length)
  3301.    'so, if the key is a character type, you could PRINT LEFT$(TempStr,KeyLen)
  3302.    'or, if key is a 32-bit LONG then PRINT CVL(LEFT$(TempStr,4)). When using
  3303.    'the key returned, be aware that if UNIQUE was NOT specified then the
  3304.    'enumerator word is attached to the end of the key (the right two bytes).
  3305.    'Also, AP.RecNo is set to the record number of the first key in the index.
  3306.    'error
  3307. See: EqualKeyXBsrc
  3308. ~EqualKeyXBsrc
  3309. Func: EqualKeyXB       Pack: AccessPack         Func:  41/Mid-level
  3310. DIM AP AS AccessPack
  3311. DIM TempStr AS STRING * 64      'used as fixed-length string for VARPTR()
  3312.                                 'passed key to find, start with enum=0
  3313. TempStr = FindKey$ + CHR$(0) + CHR$(0) + CHR$(0) '2 enumerator bytes + 0-term
  3314. AP.Func = EqualKeyXB            'defined in BULLET.BI
  3315. AP.Handle = indexfile           'handle to index file to find key from
  3316. AP.KeyPtrOff = VARPTR(TempStr)  'far pointer to key buffer
  3317. AP.KeyPtrSeg = VARSEG(TempStr)
  3318. stat = BULLET(AP)
  3319. IF stat = 0 THEN
  3320.    'the key matched exactly (including enumerator, if present)
  3321.    'TempStr is NOT ALTERED
  3322.    'AP.RecNo is set to the record number of that key
  3323. ELSEIF stat = 200 THEN
  3324.    AP.Func = NextKeyXB          'if not found, get following key and check the
  3325.    stat = BULLET(AP)            'key proper (key less the enumerator bytes)
  3326.    IF stat = 0 THEN             '(i.e., it may be proper key but enumerator=1)
  3327.       'see NextKeyXBsrc for continuation
  3328. See: NextKeyXBsrc
  3329. ~NextKeyXBsrc
  3330. Func: NextKeyXB        Pack: AccessPack         Func:  42/Mid-level
  3331. 'see EqualKeyXBsrc for preliminary code
  3332. AP.Func = NextKeyXB             'defined in BULLET.BI
  3333. stat = BULLET(AP)               'KEYLEN assumed to equal actual key length...
  3334. IF stat = 0 THEN                '...as returned by StatKXB
  3335.     IF IndexFileIsNotUnique THEN
  3336.        IF LEFT$(TempStr,KeyLen-2) = FindKey$ THEN 'the next key matches!
  3337.                                                   '(except for the enumerator)
  3338. This code example follows up on the EqualKeyXBsrc example. See EqualKeyXB for
  3339. more information on finding partial keys.
  3340. See: PrevKeyXBsrc  EqualKeyXBsrc
  3341. ~PrevKeyXBsrc
  3342. Func: PrevKeyXB        Pack: AccessPack         Func:  43/Mid-level
  3343. DIM AP AS AccessPack
  3344. DIM TempStr AS STRING * 64      'used as fixed-length string for VARPTR()
  3345. 'assume code has already executed to locate a key--this code then gets the key
  3346. 'before that one
  3347. AP.Func = PrevKeyXB             'defined in BULLET.BI
  3348. AP.Handle = indexfile           'handle to index file to access key from
  3349. AP.KeyPtrOff = VARPTR(TempStr)  'far pointer to key buffer
  3350. AP.KeyPtrSeg = VARSEG(TempStr)  '(the prev key is read from disk and put here)
  3351. stat = BULLET(AP)
  3352. IF stat = 0 THEN
  3353.    'TempStr is filled in with the key (for as many bytes as the key length).
  3354.    'Also, AP.RecNo is set to the record number of the key.
  3355.    'error
  3356. See: LastKeyXBsrc
  3357. ~LastKeyXBsrc
  3358. Func: LastKeyXB        Pack: AccessPack         Func:  44/Mid-level
  3359. DIM AP AS AccessPack
  3360. DIM TempStr AS STRING * 64      'used as fixed-length string for VARPTR()
  3361. AP.Func = LastKeyXB             'defined in BULLET.BI
  3362. AP.Handle = indexfile           'handle to index file to access key from
  3363. AP.KeyPtrOff = VARPTR(TempStr)  'far pointer to key buffer
  3364. AP.KeyPtrSeg = VARSEG(TempStr)  '(the last key is read from disk and put here)
  3365. stat = BULLET(AP)
  3366. IF stat = 0 THEN
  3367.    'TempStr is filled in with the key (for as many bytes as the key length)
  3368.    'AP.RecNo is set to the record number of the last key.
  3369.    'error
  3370. See: StoreKeyXBsrc
  3371. ~StoreKeyXBsrc
  3372. Func: StoreKeyXB       Pack: AccessPack         Func:  45/Mid-level
  3373. DIM AP AS AccessPack
  3374. DIM TempStr AS STRING * 64      'used as fixed-length string for VARPTR()
  3375. 'Assume record has been added to data file (AddRecordXB, returning RecNo2Use)
  3376. 'and key has been built (BuildKeyXB returning KeyToAdd$).
  3377.               
  3378. TempStr = KeyToAdd$ + CHR$(0)   'add the key to a UNIQUE index file
  3379. AP.Func = StoreKeyXB            'defined in BULLET.BI
  3380. AP.Handle = indexfile           'handle to index file to insert key into
  3381. AP.RecNo = RecNo2Use            'associate this record number with key
  3382. AP.KeyPtrOff = VARPTR(TempStr)  'far pointer to key buffer
  3383. AP.KeyPtrSeg = VARSEG(TempStr)  '(the last key is read from disk and put here)
  3384. stat = BULLET(AP)
  3385. IF stat = 0 THEN
  3386.    'key added
  3387. ELSEIF stat = 201 THEN
  3388.    'key already exists, which means you need to construct a unique enumerator--
  3389.    'provided the file wasn't created for UNIQUE keys...INSTEAD USE InsertXB!
  3390. See: DeleteKeyXBsrc  InsertXB
  3391. ~DeleteKeyXBsrc
  3392. Func: DeleteKeyXB      Pack: AccessPack         Func:  46/Mid-level
  3393. DIM AP AS AccessPack
  3394. DIM TempStr AS STRING * 64      'used as fixed-length string for VARPTR()
  3395. TempStr = KeyToDelete$ + CHR$(0)   'delete the key from a UNIQUE index file
  3396.                                    '(else need to supply enumerator also)
  3397. AP.Func = DeleteKeyXB           'defined in BULLET.BI
  3398. AP.Handle = indexfile           'handle to index file of key to delete
  3399. AP.KeyPtrOff = VARPTR(TempStr)  'far pointer to key buffer
  3400. AP.KeyPtrSeg = VARSEG(TempStr)  '(this key is searched for exactly)
  3401. stat = BULLET(AP)               'if exact match found the key is deleted!
  3402. IF stat = 0 THEN
  3403.    'key deleted permanently
  3404. ELSEIF stat = 200 THEN
  3405.    'key as stated was not in the index file--if the index is not UNQIUE then
  3406.    'you must supply the exact enumerator along with the key proper to delete
  3407.    '--you can use the CurrentKeyXB routine to obtain the exact current key
  3408.    'other error
  3409. See: BuildKeyXBsrc
  3410. ~BuildKeyXBsrc
  3411. Func: BuildKeyXB       Pack: AccessPack         Func:  47/Mid-level
  3412. DIM AP AS AccessPack
  3413. DIM TempStr AS STRING * 64      'used as fixed-length string for VARPTR()
  3414. 'Assume record has been built and is ready to be added to the data file. The
  3415. 'record is in the variable RecBuff (a fixed-length TYPE variable, typically).
  3416. AP.Func = BuildKeyXB            'defined in BULLET.BI
  3417. AP.Handle = indexfile           'handle to index file key is to be built for
  3418. AP.RecPtrOff = VARPTR(RecBuff)  'far pointer to data record buffer
  3419. AP.RecPtrSeg = VARSEG(RecBuff)
  3420. AP.KeyPtrOff = VARPTR(TempStr)  'far pointer to key buffer
  3421. AP.KeyPtrSeg = VARSEG(TempStr)  '(the built key is put here)
  3422. stat = BULLET(AP)
  3423. IF stat = 0 THEN
  3424.    'key built okay so can do a AddRecordXB followed by a StoreKeyXB
  3425.    'but, again, InsertXB takes care of all this detail and then some--use it
  3426.    'error
  3427. See: CurrentKeyXBsrc
  3428. ~CurrentKeyXBsrc
  3429. Func: CurrentKeyXB     Pack: AccessPack         Func:  48/Mid-level
  3430. DIM AP AS AccessPack
  3431. DIM TempStr AS STRING * 64      'used as fixed-length string for VARPTR()
  3432. AP.Func = CurrentKeyXB          'defined in BULLET.BI
  3433. AP.Handle = indexfile           'handle to index file
  3434. AP.KeyPtrOff = VARPTR(TempStr)  'far pointer to key buffer
  3435. AP.KeyPtrSeg = VARSEG(TempStr)  '(the current key is put here)
  3436. stat = BULLET(AP)
  3437. IF stat = 0 THEN
  3438.    'TempStr set to current key (valid only for KeyLen bytes)
  3439.    'Also, AP.RecNo is set to the record number of the key.
  3440.    'error
  3441. See: GetFirstXBsrc
  3442. ~GetFirstXBsrc
  3443. Func: GetFirstXB       Pack: AccessPack         Func:  60/High-level
  3444. DIM AP AS AccessPack
  3445. DIM TempStr AS STRING * 64      'used as fixed-length string for VARPTR()
  3446. DIM RecBuff AS RecordTYPE       'see AddRecordXBsrc for record layout
  3447. AP.Func = GetFirstXB            'defined in BULLET.BI
  3448. AP.Handle = indexhandle         'handle to index file to access key from
  3449. AP.RecPtrOff = VARPTR(RecBuff)  'far pointer to record buffer
  3450. AP.RecPtrSeg = VARSEG(RecBuff)  '(the record indexed by the key is put here)
  3451. AP.KeyPtrOff = VARPTR(TempStr)  'far pointer to key buffer
  3452. AP.KeyPtrSeg = VARSEG(TempStr)  '(the first key is read from disk and put here)
  3453. stat = BULLET(AP)
  3454. IF stat = 0 THEN
  3455.    'TempStr is filled in with the key (for as many bytes as the key length)
  3456.    'RecBuff is filled in with the data record
  3457.    'AP.RecNo is set to the record number of the first key in the index.
  3458.    'error
  3459. See: GetEqualXBsrc
  3460. ~GetEqualXBsrc
  3461. Func: GetEqualXB       Pack: AccessPack         Func:  61/High-level
  3462. DIM AP AS AccessPack
  3463. DIM TempStr AS STRING * 64      'used as fixed-length string for VARPTR()
  3464. DIM RecBuff AS RecordTYPE       'see AddRecordXBsrc for record layout
  3465.                                 'passed key to find, start with enum=0
  3466. TempStr = FindKey$ + CHR$(0) + CHR$(0) + CHR$(0) '2 enumerator bytes + 0-term
  3467. AP.Func = GetEqualXB            'defined in BULLET.BI
  3468. AP.Handle = indexfile           'handle to index file to find key from
  3469. AP.RecPtrOff = VARPTR(RecBuff)  'far pointer to record buffer
  3470. AP.RecPtrSeg = VARSEG(RecBuff)  '(the record indexed by the key is put here)
  3471. AP.KeyPtrOff = VARPTR(TempStr)  'far pointer to key buffer
  3472. AP.KeyPtrSeg = VARSEG(TempStr)
  3473. stat = BULLET(AP)
  3474. IF stat = 0 THEN
  3475.    'RecBuff, and AP.RecNo filled as expected (TempStr remains the same)
  3476. ELSEIF stat = 200 THEN
  3477.    AP.Func = GetNextXB          'if not found, can get following key--the next
  3478.    stat = BULLET(AP)            'key would logically follow the key not found
  3479.                                 '--this let's you search based on partial keys
  3480. See: GetNextXBsrc
  3481. ~GetNextXBsrc
  3482. Func: GetNextXB        Pack: AccessPack         Func:  62/High-level
  3483. DIM AP AS AccessPack
  3484. DIM TempStr AS STRING * 64      'used as fixed-length string for VARPTR()
  3485. DIM RecBuff AS RecordTYPE       'see AddRecordXBsrc for record layout
  3486. AP.Func = GetFirstXB            'defined in BULLET.BI
  3487. AP.Handle = indexhandle         'handle to index file to access key from
  3488. AP.RecPtrOff = VARPTR(RecBuff)  'far pointer to record buffer
  3489. AP.RecPtrSeg = VARSEG(RecBuff)  '(the record indexed by the key is put here)
  3490. AP.KeyPtrOff = VARPTR(TempStr)  'far pointer to key buffer
  3491. AP.KeyPtrSeg = VARSEG(TempStr)  '(the first key is read from disk and put here)
  3492. stat = BULLET(AP)
  3493. DO WHILE stat = 0               'print all records in key order
  3494.    PRINT AP.RecNo; RecBuff.code; ", "; RecBuff.bday
  3495.    AP.Func = GetNextXB
  3496.    stat = BULLET(AP)
  3497. IF stat <> 202 THEN             'error 202 means end of file (expected)
  3498.    'error other than expected EOF
  3499. See: GetPrevXBsrc
  3500. ~GetPrevXBsrc
  3501. Func: GetPrevXB        Pack: AccessPack         Func:  63/High-level
  3502. DIM AP AS AccessPack
  3503. DIM TempStr AS STRING * 64      'used as fixed-length string for VARPTR()
  3504. DIM RecBuff AS RecordTYPE       'see AddRecordXBsrc for record layout
  3505. AP.Func = GetLastXB             'defined in BULLET.BI
  3506. AP.Handle = indexhandle         'handle to index file to access key from
  3507. AP.RecPtrOff = VARPTR(RecBuff)  'far pointer to record buffer
  3508. AP.RecPtrSeg = VARSEG(RecBuff)  '(the record indexed by the key is put here)
  3509. AP.KeyPtrOff = VARPTR(TempStr)  'far pointer to key buffer
  3510. AP.KeyPtrSeg = VARSEG(TempStr)  '(the last key is read from disk and put here)
  3511. stat = BULLET(AP)
  3512. DO WHILE stat = 0               'print all records in REVERSE key order
  3513.    PRINT AP.RecNo; RecBuff.code; ", "; RecBuff.bday
  3514.    AP.Func = GetPrevXB
  3515.    stat = BULLET(AP)
  3516. IF stat <> 203 THEN             'error 203 means top of file (expected)
  3517.    'error other than expected TOF
  3518. See: GetLastXBsrc
  3519. ~GetLastXBsrc
  3520. Func: GetLastXB        Pack: AccessPack         Func:  64/High-level
  3521. DIM AP AS AccessPack
  3522. DIM TempStr AS STRING * 64      'used as fixed-length string for VARPTR()
  3523. DIM RecBuff AS RecordTYPE       'see AddRecordXBsrc for record layout
  3524. AP.Func = GetLastXB             'defined in BULLET.BI
  3525. AP.Handle = indexhandle         'handle to index file to access key from
  3526. AP.RecPtrOff = VARPTR(RecBuff)  'far pointer to record buffer
  3527. AP.RecPtrSeg = VARSEG(RecBuff)  '(the record indexed by the key is put here)
  3528. AP.KeyPtrOff = VARPTR(TempStr)  'far pointer to key buffer
  3529. AP.KeyPtrSeg = VARSEG(TempStr)  '(the last key is read from disk and put here)
  3530. stat = BULLET(AP)
  3531. IF stat = 0 THEN
  3532.    'TempStr is filled in with the key (for as many bytes as the key length)
  3533.    'RecBuff is filled in with the data record
  3534.    'AP.RecNo is set to the record number of the last key in the index.
  3535.    'error
  3536. See: InsertXBsrc
  3537. ~InsertXBsrc
  3538. Func: InsertXB         Pack: AccessPack         Func:  65/High-level
  3539. REDIM AP(1 TO 4) AS AccessPack  'array of 3 access packs, 1 for each index file
  3540.                                 'TempStr and RecBuff previously defined
  3541. FOR i = 1 TO 3                  '3=number of related indexes to maintain
  3542.    AP(i).Func = InsertXB
  3543.    AP(i).Handle = indexhandle(i)          'each index file's handle
  3544.    AP(i).RecPtrOff = VARPTR(RecBuff) 
  3545.    AP(i).RecPtrSeg = VARSEG(RecBuff) 
  3546.  see AddRecordXBsrc for RecBuff TYPE 
  3547.    AP(i).KeyPtrOff = VARPTR(TempStr) 
  3548. (be sure you reserved the tag field) 
  3549.    AP(i).KeyPtrSeg = VARSEG(TempStr) 
  3550.    AP(i).NextPtrOff = VARPTR(AP(i + 1))   'point to NEXT access pack
  3551.    AP(i).NextPtrSeg = VARSEG(AP(i + 1))   'AP(1 TO 4) to avoid subscript error
  3552. AP(3).NextPtrOff = 0            'reset last access pack to end-link value
  3553. AP(3).NextPtrSeg = 0
  3554. stat = BULLET(AP(1))
  3555. IF stat = 0 THEN                'if stat=0 must still check AP(1).Stat
  3556.    IF AP(1).Stat <> 0 THEN      'error when adding data record
  3557.    TrueError = AP(stat).Stat    'the returned stat is array index of bad pack
  3558. See: UpdateXBsrc
  3559. ~UpdateXBsrc
  3560. Func: UpdateXB         Pack: AccessPack         Func:  66/High-level
  3561. REDIM AP(1 TO 4) AS AccessPack  'array of 3 access packs, 1 for each index file
  3562.                                 'TempStr and RecBuff previously defined
  3563. FOR i = 1 TO 3                  '3=number of related indexes to maintain
  3564.    AP(i).Func = UpdateXB
  3565.    AP(i).Handle = indexhandle(i)          'each index file's handle
  3566.    AP(i).RecNo = RecordNumberToUpdate&    'tell it which record to update
  3567.    AP(i).RecPtrOff = VARPTR(RecBuff)      'RecBuff has new, updated data
  3568.    AP(i).RecPtrSeg = VARSEG(RecBuff)
  3569.    AP(i).KeyPtrOff = VARPTR(TempStr)
  3570.    AP(i).KeyPtrSeg = VARSEG(TempStr)
  3571.    AP(i).NextPtrOff = VARPTR(AP(i + 1))   'point to NEXT access pack
  3572.    AP(i).NextPtrSeg = VARSEG(AP(i + 1))   'AP(1 TO 4) to avoid subscript error
  3573. AP(3).NextPtrOff = 0 : AP(3).NextPtrSeg = 0 'reset last access pack to 0
  3574. stat = BULLET(AP(1))
  3575. IF stat = 0 THEN                'if stat=0 must still check AP(1).Stat
  3576.    IF AP(1).Stat <> 0 THEN      'error when writing data record
  3577.    TrueError = AP(stat).Stat    'the returned stat is array index of bad pack
  3578. See: ReindexXBsrc
  3579. ~ReindexXBsrc
  3580. Func: ReindexXB        Pack: AccessPack         Func:  67/High-level
  3581. REDIM AP(1 TO 4) AS AccessPack  'array of 3 access packs, 1 for each index file
  3582.                                 'DIM'd to 4 to avoid bad subscript in loop
  3583. FOR i = 1 TO 3                  '3=number of related indexes to reindex
  3584.    AP(i).Func = ReindexXB
  3585.    AP(i).Handle = indexhandle(i)          'each index file's handle
  3586.    AP(i).NextPtrOff = VARPTR(AP(i + 1))   'point to NEXT access pack
  3587.    AP(i).NextPtrSeg = VARSEG(AP(i + 1))   'AP(1 TO 4) to avoid subscript error
  3588. AP(3).NextPtrOff = 0
  3589. AP(3).NextPtrSeg = 0            'reset last access pack to end-link value
  3590. stat = BULLET(AP(1))
  3591. IF stat THEN                    'if stat <> 0 then the...
  3592.    TrueError = AP(stat).Stat    '...returned stat is array index of bad pack
  3593. The reason AP() is REDIM AP(1 TO 4) is so that the AP(i + 1) in the code loop
  3594. doesn't create an invalid subscript error.                                   
  3595. See: LockXBsrc
  3596. ~LockXBsrc
  3597. Func: LockXB           Pack: AccessPack         Func:  80/Network
  3598. REDIM AP(1 TO 4) AS AccessPack  'array of 3 access packs, 1 for each index file
  3599.                                 'DIM'd to 4 to avoid bad subscript in loop
  3600. FOR i = 1 TO 3                  '3=number of related indexes to Lock
  3601.    AP(i).Func = LockXB
  3602.    AP(i).Handle = indexhandle(i)          'each index file's handle
  3603.    AP(i).NextPtrOff = VARPTR(AP(i + 1))   'point to NEXT access pack
  3604.    AP(i).NextPtrSeg = VARSEG(AP(i + 1))
  3605. NEXT                            'data file handle known internally by BULLET
  3606. AP(3).NextPtrOff = 0
  3607. AP(3).NextPtrSeg = 0            'reset last access pack to end-link value
  3608. stat = BULLET(AP(1))
  3609. IF stat > 3 THEN                'if stat > 3 (> number of packs) then the...
  3610.    TrueError = AP(3).Stat       '...lock failed on the data file
  3611. ELSEIF stat <> 0 THEN                                          (|last ReadKHXB)
  3612.    TrueError = AP(stat).Stat    '...lock failed on index file # stat
  3613. The Lock routines use a different method to identify the bad pack when the   
  3614. failure was caused by the data file. See above.                              
  3615. See: UnlockXBsrc
  3616. ~UnlockXBsrc
  3617. Func: UnlockXB         Pack: AccessPack         Func:  81/Network
  3618. REDIM AP(1 TO 4) AS AccessPack  'array of 3 access packs, 1 for each index file
  3619.                                 'DIM'd to 4 to avoid bad subscript in loop
  3620. FOR i = 1 TO 3                  '3=number of related indexes to Lock
  3621.    AP(i).Func = UnlockXB
  3622.    AP(i).Handle = indexhandle(i)          'each index file's handle
  3623.    AP(i).NextPtrOff = VARPTR(AP(i + 1))   'point to NEXT access pack
  3624.    AP(i).NextPtrSeg = VARSEG(AP(i + 1))
  3625. NEXT                            'data file handle known internally by BULLET
  3626. AP(3).NextPtrOff = 0
  3627. AP(3).NextPtrSeg = 0            'reset last access pack to end-link value
  3628. stat = BULLET(AP(1))
  3629. IF stat > 3 THEN                'if stat > 3 (> number of packs) then the...
  3630.    TrueError = AP(3).Stat       '...unlock failed on the data file
  3631. ELSEIF stat <> 0 THEN
  3632.    TrueError = AP(stat).Stat    '...unlock failed on index file # stat
  3633. The Lock routines use a different method to identify the bad pack when the   
  3634. failure was caused by the data file. See above.                              
  3635. See: LockKeyXBsrc
  3636. ~LockKeyXBsrc
  3637. Func: LockKeyXB        Pack: AccessPack         Func:  82/Network
  3638. REDIM AP(1 TO 4) AS AccessPack  'array of 3 access packs, 1 for each index file
  3639.                                 'DIM'd to 4 to avoid bad subscript in loop
  3640. FOR i = 1 TO 3                  '3=number of related indexes to Lock
  3641.    AP(i).Func = LockXB
  3642.    AP(i).Handle = indexhandle(i)          'each index file's handle
  3643.    AP(i).NextPtrOff = VARPTR(AP(i + 1))   'point to NEXT access pack
  3644.    AP(i).NextPtrSeg = VARSEG(AP(i + 1))
  3645. AP(3).NextPtrOff = 0
  3646. AP(3).NextPtrSeg = 0            'reset last access pack to end-link value
  3647. stat = BULLET(AP(1))
  3648. IF stat <> 0 THEN
  3649.    TrueError = AP(stat).Stat    'lock failed on index file # stat
  3650.                                 '--if stat > 3 then failed on last internal
  3651.                                 '--ReadKHXB...This is EXTREMELY unlikely
  3652. See: UnlockKeyXBsrc
  3653. ~UnlockKeyXBsrc
  3654. Func: UnlockKeyXB      Pack: AccessPack         Func:  83/Network
  3655. REDIM AP(1 TO 4) AS AccessPack  'array of 3 access packs, 1 for each index file
  3656.                                 'DIM'd to 4 to avoid bad subscript in loop
  3657. FOR i = 1 TO 3                  '3=number of related indexes to Lock
  3658.    AP(i).Func = UnlockKeyXB
  3659.    AP(i).Handle = indexhandle(i)          'each index file's handle
  3660.    AP(i).NextPtrOff = VARPTR(AP(i + 1))   'point to NEXT access pack
  3661.    AP(i).NextPtrSeg = VARSEG(AP(i + 1))
  3662. AP(3).NextPtrOff = 0
  3663. AP(3).NextPtrSeg = 0            'reset last access pack to end-link value
  3664. stat = BULLET(AP(1))
  3665. IF stat <> 0 THEN
  3666.    TrueError = AP(stat).Stat    'unlock failed on index file # stat
  3667. See: LockDataXBsrc
  3668. ~LockDataXBsrc
  3669. Func: LockDataXB       Pack: AccessPack         Func:  84/Network
  3670. DIM AP AS AccessPack
  3671. AP.Func = LockDataXB            'defined in BULLET.BI
  3672. AP.Handle = datahandle          'handle of data file to lock
  3673. AP.RecNo = 0&                   '=0 to lock all or, set to actual record number
  3674. stat = BULLET(AP)               '   to lock as in AP.RecNo = lockThisRec&
  3675. IF stat THEN 'error
  3676. See: UnlockDataXBsrc
  3677. ~UnlockDataXBsrc
  3678. Func: UnlockDataXB     Pack: AccessPack         Func:  85/Network
  3679. DIM AP AS AccessPack
  3680. AP.Func = UnlockDataXB          'defined in BULLET.BI
  3681. AP.Handle = datahandle          'handle of data file to unlock
  3682. AP.RecNo = 0&                   '=0 to unlock all or, set to actual record num
  3683. stat = BULLET(AP)               '   to unlock as in AP.RecNo = lockThisRec&
  3684. IF stat THEN 'error
  3685.                                 'note: you cannot unlock parts of a file with
  3686.                                 '1 single unlock (where AP.RecNo=0). Instead,
  3687.                                 'you must unlock each record individually--
  3688.                                 'that is, if you made any single-record locks
  3689. See: DriveRemoteXBsrc
  3690. ~DriveRemoteXBsrc
  3691. Func: DriveRemoteXB    Pack: RemotePack         Func:  86/Network
  3692. DIM RP AS RemotePack
  3693. RP.Func = DriveRemoteXB         'defined in BULLET.BI
  3694. RP.Handle = drive2check         'drive to check (0=default, 1=A:,2=B:,3=C:...)
  3695. stat = BULLET(RP)
  3696. IF stat = 0 THEN
  3697.    'RP.IsRemote set to 0 if drive local, 1 if remote
  3698.    'RP.Flags set to DX register as returned by DOS
  3699.    'RP.IsShare set to 0 if SHARE.EXE is not loaded, non-zero SHARE installed
  3700.   'error  (like invalid drive)
  3701. See: FileRemoteXBsrc
  3702. ~FileRemoteXBsrc
  3703. Func: FileRemoteXB     Pack: RemotePack         Func:  87/Network
  3704. DIM RP AS RemotePack
  3705. RP.Func = FileRemoteXB          'defined in BULLET.BI
  3706. RP.Handle = filehandle          'file handle to check
  3707. stat = BULLET(RP)
  3708. IF stat = 0 THEN
  3709.    'RP.IsRemote set to 0 if file local, 1 if remote
  3710.    'RP.Flags set to DX register as returned by DOS
  3711.    'RP.IsShare set to 0 if SHARE.EXE is not loaded, non-zero SHARE installed
  3712.   'error  (like invalid handle)
  3713. See: SetRetriesXBsrc
  3714. ~SetRetriesXBsrc
  3715. Func: SetRetriesXB     Pack: SetRetriesPack     Func:  88/Network
  3716. DIM SRP AS SetRetriesPack
  3717. SRP.Func = SetRetriesXB
  3718. SRP.Mode = 1             '1=set to user values, 0=set DOS default
  3719. SRP.Pause = 5000         'do 5,000 loops between retries
  3720. SRP.Retries = 5          'try 5 times before giving up with error
  3721. stat = BULLET(SRP)
  3722. IF stat THEN
  3723.    'error                'it's unlikely an error occurs
  3724. See: DeleteFileDOSsrc
  3725. ~DeleteFileDOSsrc
  3726. Func: DeleteFileDOS    Pack: DOSFilePack        Func: 100/DOS
  3727. DIM DFP AS DOSFilePack
  3728. DIM TempStr AS STRING * 80
  3729. TempStr = file2delete$ + CHR$(0)
  3730. DFP.Func = DeleteFileDOS        'defined in BULLET.BI
  3731. DFP.FilenamePtrOff = VARPTR(TempStr)
  3732. DFP.FilenamePtrSeg = VARSEG(TempStr)
  3733. stat = BULLET(DFP)
  3734. IF stat THEN 'error
  3735. See: RenameFileDOSsrc
  3736. ~RenameFileDOSsrc
  3737. Func: RenameFileDOS    Pack: DOSFilePack        Func: 101/DOS
  3738. DIM DFP AS DOSFilePack
  3739. DIM TempStr AS STRING * 80
  3740. DIM TempStr2 AS STRING * 80
  3741. TempStr = file2rename$ + CHR$(0)
  3742. TempStr2 = newfilename$ + CHR$(0)
  3743. DFP.Func = RenameFileDOS        'defined in BULLET.BI
  3744. DFP.FilenamePtrOff = VARPTR(TempStr)
  3745. DFP.FilenamePtrSeg = VARSEG(TempStr)
  3746. DFP.NewNamePtrOff = VARPTR(TempStr2)
  3747. DFP.NewNamePtrSeg = VARSEG(TempStr2)
  3748. stat = BULLET(DFP)
  3749. IF stat THEN 'error
  3750. See: CreateFileDOSsrc
  3751. ~CreateFileDOSsrc
  3752. Func: CreateFileDOS    Pack: DOSFilePack        Func: 102/DOS
  3753. DIM DFP AS DOSFilePack
  3754. DIM TempStr AS STRING * 80
  3755. TempStr = file2create$ + CHR$(0)
  3756. DFP.Func = CreateFileDOS        'defined in BULLET.BI
  3757. DFP.FilenamePtrOff = VARPTR(TempStr)
  3758. DFP.FilenamePtrSeg = VARSEG(TempStr)
  3759. DFP.Attr = 0                    'normal file directory attribute
  3760. stat = BULLET(DFP)
  3761. IF stat THEN 'error
  3762. See: AccessFileDOSsrc
  3763. ~AccessFileDOSsrc
  3764. Func: AccessFileDOS    Pack: DOSFilePack        Func: 103/DOS
  3765. DIM DFP AS DOSFilePack
  3766. DIM TempStr AS STRING * 80
  3767. TempStr = file2access$ + CHR$(0)
  3768. DFP.Func = AccessFileDOS        'defined in BULLET.BI
  3769. DFP.FilenamePtrOff = VARPTR(TempStr)
  3770. DFP.FilenamePtrSeg = VARSEG(TempStr)
  3771. DFP.ASmode = &H42               'attempt R/W DENY NONE access
  3772. stat = BULLET(DFP)
  3773. IF stat THEN 'error
  3774. See: OpenFileDOSsrc
  3775. ~OpenFileDOSsrc
  3776. Func: OpenFileDOS      Pack: DOSFilePack        Func: 104/DOS
  3777. DIM DFP AS DOSFilePack
  3778. DIM TempStr AS STRING * 80
  3779. TempStr = file2open$ + CHR$(0)
  3780. DFP.Func = OpenFileDOS          'defined in BULLET.BI
  3781. DFP.FilenamePtrOff = VARPTR(TempStr)
  3782. DFP.FilenamePtrSeg = VARSEG(TempStr)
  3783. DFP.ASmode = &H42               'open in R/W DENY NONE access
  3784. stat = BULLET(DFP)
  3785. IF stat = 0 THEN
  3786.    'DFP.Handle set to handle of open file
  3787.    'error
  3788. See: SeekFileDOSsrc
  3789. ~SeekFileDOSsrc
  3790. Func: SeekFileDOS      Pack: DOSFilePack        Func: 105/DOS
  3791. DIM DFP AS DOSFilePack
  3792. DFP.Func = SeekFileDOS          'defined in BULLET.BI
  3793. DFP.Handle = handle
  3794. DFP.SeekOffset = 0&             'position 0 relative EOF (get length of file)
  3795. DFP.Method = 2                  'seek from END of file
  3796. stat = BULLET(DFP)
  3797. IF stat = 0 THEN
  3798.    'DFP.SeekOffset set to absolute current offset
  3799.    '--in this case, the DFP.SeekOffset equals then length of the file
  3800.    'error
  3801. See: ReadFileDOSsrc
  3802. ~ReadFileDOSsrc
  3803. Func: ReadFileDOS      Pack: DOSFilePack        Func: 106/DOS
  3804. DIM DFP AS DOSFilePack
  3805. DIM ReadBuff AS STRING * 512    'sector buffer
  3806. DFP.Func = ReadFileDOS          'defined in BULLET.BI
  3807. DFP.Handle = handle
  3808. DFP.Bytes = Bytes2Read          '16-bit value, in this case 512 since that's
  3809. DFP.BufferPtrOff = VARPTR(ReadBuff)            'the size of ReadBuff
  3810. DFP.BufferPtrSeg = VARSEG(ReadBuff)
  3811. stat = BULLET(DFP)
  3812. IF stat = 0 THEN
  3813.    IF DFP.Bytes <> Bytes2Read THEN              'check if EOF processed
  3814.       'hit EOF before reading all 512 bytes
  3815.    ELSE
  3816.       'ReadBuff filled with 512 bytes of data read from the current disk pos
  3817.       'disk position moved to the last byte read + 1
  3818.    ENDIF
  3819.    'error
  3820. See: ExpandFileDOSsrc
  3821. ~ExpandFileDOSsrc
  3822. Func: ExpandFileDOS    Pack: DOSFilePack        Func: 107/DOS
  3823. DIM DFP AS DOSFilePack
  3824. DFP.Func =  ExpandFileDOS       'defined in BULLET.BI
  3825. DFP.Handle = handle
  3826. DFP.SeekOffset = Bytes2ExpandBy&
  3827. stat = BULLET(DFP)
  3828. IF stat = 0 THEN
  3829.    'file expanded by number of bytes specified
  3830.    'error
  3831. See: WriteFileDOSsrc
  3832. ~WriteFileDOSsrc
  3833. Func: WriteFileDOS     Pack: DOSFilePack        Func: 108/DOS
  3834. DIM DFP AS DOSFilePack
  3835. DIM WriteBuff AS STRING * 512   'sector buffer
  3836. DFP.Func = WriteFileDOS         'defined in BULLET.BI
  3837. DFP.Handle = handle
  3838. DFP.Bytes = Bytes2Write         '16-bit value, in this case 512 since that's
  3839. DFP.BufferPtrOff = VARPTR(WriteBuff)           'the size of WriteBuff
  3840. DFP.BufferPtrSeg = VARSEG(WriteBuff)
  3841. stat = BULLET(DFP)
  3842. IF stat = -2 THEN
  3843.    'disk full
  3844. ELSE IF stat THEN
  3845.    'other error
  3846.    'okay
  3847. Unlike ReadFileDOS, if the number of bytes actually written does not equal
  3848. Bytes2Write, the WriteFileDOS routine returns a DISK FULL error code (-2).
  3849. See: CloseFileDOSsrc
  3850. ~CloseFileDOSsrc
  3851. Func: CloseFileDOS     Pack: DOSFilePack        Func: 109/DOS
  3852. DIM DFP AS DOSFilePack
  3853. DFP.Func = CloseFileDOS         'defined in BULLET.BI
  3854. DFP.Handle =handle2close
  3855. stat = BULLET(DFP)
  3856. IF stat THEN 'error
  3857. See: MakeDirDOSsrc
  3858. ~MakeDirDOSsrc
  3859. Func: MakeDirDOS       Pack: DOSFilePack        Func: 110/DOS
  3860. DIM DFP AS DOSFilePack
  3861. DIM TempStr AS STRING * 80
  3862. TempStr = subdir2make$ + CHR$(0)
  3863. DFP.Func = MakeDirDOS           'defined in BULLET.BI
  3864. DFP.FilenamePtrOff = VARPTR(TempStr)
  3865. DFP.FilenamePtrSeg = VARSEG(TempStr)
  3866. stat = BULLET(DFP)
  3867. IF stat THEN 'error
  3868. See: DeleteFileDOSsrc
  3869.