home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / bullet25.zip / common / bullet2.inf (.txt) < prev    next >
OS/2 Help File  |  1997-06-25  |  277KB  |  11,413 lines

  1.  
  2. ΓòÉΓòÉΓòÉ 1. Copyright ΓòÉΓòÉΓòÉ
  3.  
  4. 25-Jun-1997 
  5.  
  6.           BULLET is Copyright 1992-97, and is owned by the author, Cornel Huth, 
  7.           and is protected by United States copyright laws and international 
  8.           treaty provisions.  License restrictions apply. 
  9.  
  10.  
  11. ΓòÉΓòÉΓòÉ 2. License Agreement ΓòÉΓòÉΓòÉ
  12.  
  13. Before using this software, BULLET you must agree to the following: 
  14.  
  15.    1. A BULLET license grants you the right to use the BULLET library code on a 
  16.       royalty-free basis according to the terms of this License Agreement. 
  17.  
  18.    2. You are required to have one license per developer that is programming 
  19.       with Bullet. 
  20.  
  21.    3. There is no restriction on the number of users you may support, and no 
  22.       restriction on the number of different end-user programs you may 
  23.       distribute that use BULLET.  You may allow any number of simultaneous 
  24.       users to use your end-user program. 
  25.  
  26.    4. The dynamic link library, BULLET*.DLL, may be distributed with your 
  27.       end-user program.  No other BULLET product may be distributed without 
  28.       permission. 
  29.  
  30.    5. Evaluation use is limited to 300 records, and for the sole purpose of 
  31.       evaluating the software.  The BULLET library code may not be distributed 
  32.       in any form without a registered BULLET license.  A BULLET license is 
  33.       obtained only with purchase of a BULLET package, purchased from an 
  34.       authorized BULLET distributor. 
  35.  
  36.    6. BULLET is owned by the author, Cornel Huth, and is protected by United 
  37.       States copyright laws and international treaty provisions.  You are not 
  38.       permitted to make copies of this software except for archival purposes. 
  39.  
  40.    7. You may not rent or lease BULLET. You may not transfer this license 
  41.       without the written permission of the author.  If this software is an 
  42.       update or upgrade, you may not sell or give away previous versions. 
  43.  
  44.    8. You may not reverse engineer, decompile, or disassemble this software if 
  45.       the intent or result is to alter the software. 
  46.  
  47.    9. There are no expressed or implied warranties with this software. 
  48.  
  49.   10. All liabilities in the use of this software rest with the user. 
  50.  
  51.   11. U.S. Government Restricted Rights.  This software is provided with 
  52.       restricted rights.  Use, duplication, or disclosure by the Government is 
  53.       subject to restrictions as set forth in subparagraph (c)(1)(ii) of the 
  54.       Rights in Technical Data and Computer Software clause at 52.227-7013. The 
  55.       software is owned by Cornel Huth/6402 Ingram Rd/San Antonio Texas 
  56.       78238/USA.  This agreement is governed by the laws of the Great State of 
  57.       Texas, the United States of America, and all other countries of Earth. 
  58.  
  59.  Any questions concerning this License Agreement should be directed to Product 
  60.  Support. 
  61.  
  62.  Failure to comply with any part of this License Agreement may result in 
  63.  license revocation. 
  64.  
  65.  
  66. ΓòÉΓòÉΓòÉ 3. Installation ΓòÉΓòÉΓòÉ
  67.  
  68. Installation instructions are located in the README text file included with 
  69. your package. 
  70.  
  71.  
  72. ΓòÉΓòÉΓòÉ 4. Product Support ΓòÉΓòÉΓòÉ
  73.  
  74. Technical support in the use of Bullet is available for licensed users at the 
  75. 40th Floor BBS or by way of the Internet. 
  76.  
  77. 40th Floor BBS: 
  78. +1(210)684-8065  N-8-1 
  79.  
  80. Internet: 
  81. support@40th.com 
  82. http://www.40th.com 
  83.  
  84. Response time is usually within 24 hours by internet e-mail or if you leave a 
  85. message at the support BBS.  Alternatively, you may post a letter to Cornel 
  86. Huth/6402 Ingram Rd/San Antonio TX 78238/USA. 
  87.  
  88. The latest in-version (2.x) release of BULLET 2 is available for download from 
  89. the BBS or from the internet at the www.40th.com site (alternate is 
  90. www.txdirect.net/~cornel/), or $5 by postal mail.  Re-createable bugs are fixed 
  91. immediately.  Contact support if you have any questions or requests. 
  92.  
  93. For everyone else, or for general information, send e-mail to: 
  94. info@40th.com 
  95.  
  96.  
  97. ΓòÉΓòÉΓòÉ 4.1. Bug Report Form ΓòÉΓòÉΓòÉ
  98.  
  99. When requesting support for possible bug(s) use the following as a guideline: 
  100.  
  101.    1. Include a complete problem description. 
  102.    2. Include sample source of the problem, if necessary (small is best). 
  103.    3. Include necessary data files, include files, etc. 
  104.    4. Include step-by-step procedure to follow in order to recreate the 
  105.       problem. 
  106.  
  107.  Once done, send it to support by way of the BBS, e-mail, or postal mail to 
  108.  addresses listed in Product Support. 
  109.  
  110.  
  111. ΓòÉΓòÉΓòÉ 5. Ordering Information ΓòÉΓòÉΓòÉ
  112.  
  113. To order Bullet by check, bank check, money-order, or cash, use form ORDER.FRM. 
  114. For credit card order, use form ORDER.CC. 
  115.  
  116. Payment Options 
  117.  
  118. Γûá Check, money-order, cash 
  119.  
  120. Your funds have to be in US Dollars and, if by check, have to be drawn on or 
  121. payable through a US bank.  If sending currency, use Registered AirMail. 
  122. Personal checks may require 10 working days to clear.  Most major non-American 
  123. banks have branch banks in the US.  Contact your bank for details.  Direct 
  124. wire-transfer is available: enquire to sales@40th.com. 
  125.  
  126. To order, send payment and the order form ORDER.FRM to: 
  127.  
  128.    Cornel Huth
  129.    6402 Ingram Rd
  130.    San Antonio, Texas 78238-3915
  131.    USA
  132.  
  133. Γûá Credit card, Eurochecks in DM, other 
  134.  
  135. For credit card orders or for orders that cannot use the Direct-To-Author order 
  136. form, use the special Bullet/BMT Micro order form, or see the file !ORDER.CC in 
  137. the distribution package. 
  138.  
  139. Delivery Options 
  140.  
  141. Standard AirMail to all destinations is available at no extra charge.  If a 
  142. printed manual is ordered, it will be AirMailed first-class. 
  143.  
  144. Updates 
  145.  
  146. Updates are available for $5 (to cover disk and shipping costs) for any 2.x 
  147. version update at your option level.  Updates may be downloaded from the Bullet 
  148. support BBS or intenet free of charge 
  149.  
  150. Note:  All shipments outside of the US may go through your country's Customs. 
  151. Each package is valued at the total price of the order, less any shipping 
  152. costs, if any, unless pre-arranged otherwise.  Your Customs Office may delay 
  153. mail delivery if duty is required. 
  154.  
  155. Click here [Γûá] for the check, money-order, cash order form. 
  156.  
  157. Click here [Γûá] for the credit card order from. 
  158.  
  159.  
  160. ΓòÉΓòÉΓòÉ 5.1. Order Form for Check, Money-order, or Cash ΓòÉΓòÉΓòÉ
  161.  
  162. Printing this section from here may not fit on a single page.  Use the file 
  163. ORDER.FRM instead, or select the 'Services' menu item from here (upper-left), 
  164. and select 'Copy to file' to print this to .\TEXT.TMP. 
  165.  
  166. Direct-To-Author Order Form (also see Credit Card Order Form)
  167. Bullet 2.5 for OS/2 Order Form for Check, Money-order, or Cash
  168.  
  169.  
  170.                                         Cost Per    Number of
  171.        ORDERING:  BULLET 2.5            License     Licenses    Extended
  172.      -----------------------------------            --------    --------
  173.  
  174.      Bullet 2 (includes all platforms)    $89.00  x          =
  175.      -----------------------------------           --------     ---------
  176.  
  177.                                                              =
  178.      Bullet 2 printed manual (OPTIONAL)   $20.00  x -------     ---------
  179.  
  180.                                                  SUB-TOTAL  = $
  181.  When ordering direct-to-author you                             ---------
  182.  save 15% on handling fees.  Allow at
  183.  least 10 business days for your order       15% DISCOUNT   =  -
  184.  to be processed when using this form                           ---------
  185.  once it has been received.
  186.                                            BULLET 2  TOTAL  = $
  187.                                                                 =========
  188.  
  189.  
  190. Send TOTAL payment on check (US Dollars/US bank), money-order, or cash to
  191.  
  192.         CORNEL HUTH                       Always endorse your letter
  193.         6402 INGRAM RD                             AirMail
  194.         SAN ANTONIO TX 78238-3915          if you are not in the USA
  195.         USA
  196.  
  197.    PLEASE PRINT - For comments add a separate page and mark here [  ]
  198.  
  199. Your Name>
  200.            -------------------------------------------------- (required)
  201.  
  202.   Company>
  203.            -------------------------------------------------- (optional)
  204.  
  205.   Address>
  206.            -------------------------------------------------------------
  207.  
  208.  
  209.            -------------------------------------------------------------
  210.  
  211.  
  212.            -------------------------------------------------------------
  213.  
  214.     E-mail>                                               Disk
  215.            ---------------------------------------------- Size> --------
  216.  
  217.  Telephone                             Fax
  218.    Number> --------------------------- No.> ----------------------------
  219.  
  220.            This form is not for credit cards  Today's Date>
  221.            ----------------------------------               ---/----/---
  222.            Check must be Payable from US Bank
  223.  
  224.  
  225. ΓòÉΓòÉΓòÉ 5.2. Order Form for Credit Card ΓòÉΓòÉΓòÉ
  226.  
  227. Printing this section from here will not fit on a single page.  Use the file 
  228. ORDER.CC instead, or select the 'Services' menu item from here (upper-left), 
  229. and select 'Copy to file' to print this to .\TEXT.TMP.  Cut-and-paste as 
  230. needed. 
  231.  
  232.    To order Bullet by credit card (or Eurochecks in DM) use this form,
  233.    payable to BMT Micro.  All other orders should use the Direct-To-
  234.    Author order form.  All shipping is done by the author direct to
  235.    you, and is always the current release of Bullet.  All Bullet 2
  236.    versions include a printed manual and include free shipping to all
  237.    destinations (AirMail).
  238.  
  239.                   Mail Orders To: BMT Micro
  240.                                   PO Box 15016
  241.                                   WILMINGTON NC 28408
  242.                                   USA
  243.  
  244.                     Voice Orders: 800AM - 700PM EST (-5 GMT)
  245.                                   (800) 414-4268 (orders only)
  246.                                   (910) 791-7052
  247.  
  248.                       Fax Orders: (910) 350-2937  24 hours / 7 Days
  249.                                   (800) 346-1672  24 hours / 7 Days
  250.  
  251.          Online Orders via modem: (910) 350-8061  10 lines, all 14.4K
  252.                                   (910) 799-0923  Direct 28.8K line
  253.  
  254.      Ordering and general ordering questions:
  255.                          Via AOL: bmtmicro
  256.                          via MSN: bmtmicro
  257.                      Via Prodigy: HNGP66D
  258.                   via Compuserve: 74031,307
  259.                     via Internet: orders@bmtmicro.com
  260.                                   telnet@bmtmicro.com
  261.                                   www.bmtmicro.com
  262.  
  263.  
  264.      We accept Visa, Mastercard, Discover, American Express, Diners
  265.      Club, Carte Blanche, Cashiers Check, Personal Check.   Personal
  266.      checks are subject to clearance.  Eurochecks in DM are welcome.
  267.      DM, Sterling, and US Currency is welcome but send only by
  268.      registered mail, return reciept requested.   We cannot be liable
  269.      for lost cash sent through the mail.
  270.  
  271.      Purchase orders are welcome, subject to approval.   The minimum
  272.      amount is $250.00.
  273.  
  274.      Information for our German customers is explained in the last
  275.      paragraph of this order form.
  276.  
  277.      -------------------------------cut here-----------------------------
  278.      Name:
  279.           ------------------------------------------------------(required)
  280.      Company:
  281.              ---------------------------------------------------(optional)
  282.      Address:
  283.              -------------------------------------------------------------
  284.  
  285.              -------------------------------------------------------------
  286.      City:                                State/Province:
  287.           --------------------------------               -----------------
  288.      Postal/ZIP Code:                     Country:
  289.                      ---------------------        ------------------------
  290.      Phone:
  291.            ---------------------------------------------------------------
  292.      Fax:
  293.          -----------------------------------------------------------------
  294.      E-Mail #1
  295.               ------------------------------------------------------------
  296.      E-Mail #2
  297.               ------------------------------------------------------------
  298.                                         Cost Per    Number of
  299.        ORDERING:  BULLET 2.5            License     Licenses    Extended
  300.      -----------------------------------            --------    --------
  301.  
  302.      Bullet 2 (includes all platforms)    $89.00  x          =
  303.      -----------------------------------           --------     ---------
  304.  
  305.                                                              =
  306.      Bullet 2 printed manual (OPTIONAL)   $20.00  x -------     ---------
  307.  
  308.                                                  SUB-TOTAL  = $
  309.                                                                 ---------
  310.  
  311.                  North Carolina Residents add 6% Sales Tax  =  +
  312.                                                                 ---------
  313.  
  314.                                            BULLET 2  TOTAL  = $
  315.                                                                 =========
  316.      ---------------------------------------------------------------------
  317.      |                                                                   |
  318.      | For credit card payment only                                      |
  319.      |                                                                   |
  320.      | Circle one: VISA / Master / Discover / American Express / Diners  |
  321.      |                                                                   |
  322.      | Credit card number:                                               |
  323.      |                     --------------------------------------------- |
  324.      | Expiration date:                                                  |
  325.      |                  ------------------------------------------------ |
  326.      |                                                                   |
  327.      | Authorization signature:                                          |
  328.      |                          ---------------------------------------- |
  329.      ---------------------------------------------------------------------
  330.      -------------------------------cut here-----------------------------
  331.  
  332.  
  333.                    ORDERING FROM INSIDE GERMANY ONLY
  334.                    =================================
  335.  
  336. Persons in Germany wishing to order shareware may also transfer funds
  337. into our account with Deutsche Bank.   Once the money is deposited you
  338. may either fax a confirmation to us with proof of deposit or wait until
  339. Deutsche Bank notifies us of the transaction (usually 10-18 business days).
  340. Account information is as follows:
  341.  
  342. Deutsche Bank / Frankfurt Branch
  343. Empf╨önger:  Thomas Bradford / BMT Micro
  344. Konto-Nummer: 0860221
  345. Bankleitzahl: 500-700-10
  346.  
  347. When you make the transfer, be sure to put your name and the program you
  348. are registering on the transfer.
  349.  
  350. Current exchange rates can be obtained by sending an email to
  351. dm_to_us@bmtmicro.com.   An automated reply will return todays exchange
  352. rates.
  353.  
  354. It is very important that you send us a completed order form by
  355. either email or fax if you deposit money into this account for a
  356. registration.  Fill the order form out as usual except in the credit
  357. card number field put "DEUTSCHE BANK".   We will file the order and
  358. use it to match against the deposit information we receive from the
  359. bank.
  360.  
  361.                                IMPORTANT!
  362.                                ----------
  363. When you email us your order form, we will reply with an
  364. acknowledgement.   If you do not get an acknowledgement within 24 hours
  365. please send your order again in case it was lost.  This extra bit of
  366. caution can save a lot of confusion.
  367.  
  368. If you are concerned that your order is taking too long to process, feel
  369. free to check with us about the status of your order.   It's important
  370. to all of us that you feel safe doing business with our company and
  371. please feel free to suggest ways we can improve our service to you.
  372.  
  373.  
  374. ΓòÉΓòÉΓòÉ 6. Tutorial ΓòÉΓòÉΓòÉ
  375.  
  376. This tutorial describes how to set up a basic database.  It describes file 
  377. layout and how to use Bullet to enter into and read from the database.  It does 
  378. not describe aspects that do not relate to Bullet, such as how to load list 
  379. boxes, create dialogs, etc.  This tutorial creates a music CD collection 
  380. database. 
  381.  
  382. The tutorial follows. 
  383.  
  384.  
  385. ΓòÉΓòÉΓòÉ 6.1. Tutorial: Output Requirements ΓòÉΓòÉΓòÉ
  386.  
  387. The goal of this tutorial is to create a database for a music CD collection. 
  388. The method used is a suggested method; it is by no means the only way to 
  389. develop a database, and only touches the surface of database programming.  That 
  390. said... 
  391.  
  392. The most important thing to do is to know what output you want.  From that, you 
  393. know what input is needed.  For the 'CD database', I've drawn up a list of 
  394. things that I want: 
  395.  
  396. Title, artist, and year.  Must have those.  Track name (the song name), track 
  397. number, and play time would be essential, too.  How about who was playing on 
  398. the track and instruments they used?  Put that on your list -- it's not on this 
  399. one. 
  400.  
  401. All these could be entered into a single file as a single database record, but 
  402. that would be a pretty poor design.  A single data file may seem to be the 
  403. obvious way, but in the long run, it's not very good at all.  This database 
  404. uses two data files.  This concept -- multiple data files -- is especially 
  405. useful when the database is more complex.  For example, an accounting system 
  406. would employ many physical data files.  It could be done in one, sure, but the 
  407. maintenance would be very difficult. 
  408.  
  409. Two tables are used:  The Title-Artist-Year table (Title/CTAY), and the 
  410. TrackNumber-TrackName-Time table (Tracks/CTTT).  A table is a file composed of 
  411. rows and columns.  A row is a record; a column is a field.  No two rows may be 
  412. exactly alike (what would be the point?).  In addition to the fields listed 
  413. (the Title, Artist, and Year, for instance), each table includes a Code field. 
  414. TrackNumber is included as a field value in the second table since the physical 
  415. ordering of rows cannot be used for this purpose (it could, technically, but it 
  416. is unwise to depend on row order being preserved since there is nothing 
  417. enforcing the physical ordering of records). 
  418.  
  419. The Code field for the Title table (CTAY) is generated by the program and is 
  420. composed of the first 4 characters of the Title, plus the first 4 characters of 
  421. the Artist, plus the year (all four characters of it).  This code is also used 
  422. in the Tracks table (CTTT).  This serves two purposes:  First, it ensures that 
  423. each Track record is unique (with pretty good certainty; without it, it is 
  424. possible that TrackNumber-TrackName-Time alone may occur more than once), and 
  425. second, it can be used as the primary key when being accessed through the 
  426. foreign key in the Title table (see Record Layout Diagrams).  By searching CTAY 
  427. (the Title Table) for a desired title, or artist, or even year, and using the 
  428. Code field from that row, you can match it to the Code in CTTT (Track Table) to 
  429. find the tracks that belong to that title row (or artist, or year -- whatever 
  430. the search was based on).  To speed up searching, indexes are maintained and 
  431. used for lookups.  For a very large CD collection (say, several thousand CD 
  432. titles, and tens of thousands of tracks), the database can still be very 
  433. quickly queried for whatever information you need (and have programmed). 
  434.  
  435.  
  436. ΓòÉΓòÉΓòÉ 6.2. Tutorial: Record Layout ΓòÉΓòÉΓòÉ
  437.  
  438. The Code field is generated by your program.  Other fields are input data.  The 
  439. following are the data record layouts of the DBF files (tag fields not shown). 
  440. The time field may be created as a text field with the form "mm:ss", or could 
  441. even be made into a 'seconds' field.  This database uses the more direct 
  442. "mm:ss" since that's how it's read off the CD. Note that this information is 
  443. already stored digitally on the CD itself (running time), but that would 
  444. require additional coding and is not relevant to this tutorial (but oh, how 
  445. sweet it could be). 
  446.  
  447.  CTAY TABLE
  448. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  449. Γöé   CODE     Γöé      TITLE      Γöé     ARTIST      ΓöéYEAR Γöé
  450. Γöé            Γöé                 Γöé                 Γöé     Γöé
  451. ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  452.  MexiConc1993  Mexican Moon      Concrete Blonde  1993
  453.  No NCran1994  No Need to Argue  Cranberries, The 1994
  454.  MachDeep1972  Machine Head      Deep Purple      1972
  455.  
  456.  
  457.               CTTT TABLE
  458.              ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  459.              Γöé    CODE    ΓöéTRKΓöé     TRACKNAME      ΓöéTIME Γöé
  460.              Γöé            Γöé   Γöé                    Γöé     Γöé
  461.              ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  462.               MexiConc1993  01 Jenny I Read         05:18
  463.               MexiConc1993  02 Mexican Moon         05:03
  464.               MexiConc1993  03 Heal It Up           04:21
  465.               MexiConc1993  04 Jonestown            06:06
  466.               MexiConc1993  05 Rain                 03:28
  467.               MexiConc1993  06 I Call It Love       05:15
  468.               MexiConc1993  07 Jesus Forgive Me     05:17
  469.               MexiConc1993  08 When You Smile       04:18
  470.               MexiConc1993  09 Close To Home        03:31
  471.               MexiConc1993  10 One Of My Kind       03:55
  472.               MexiConc1993  11 End Of The Line      04:39
  473.               MexiConc1993  12 Blind Ambition       06:10
  474.               MexiConc1993  13 Bajo La Lune         05:07
  475.               No NCran1994  01 Ode To My Family     04:30
  476.               No NCran1994  02 I Can't Be With You  03:07
  477.               No NCran1994  03 Twenty One           03:08
  478.               No NCran1994  04 Zombie               05:06
  479.               No NCran1994  05 Empty                03:26
  480.               No NCran1994  06 Everything I Said    03:53
  481.               No NCran1994  07 The Icicle Melts     02:54
  482.               No NCran1994  08 Disappointment       04:14
  483.               No NCran1994  09 Ridiculous Thoughts  04:31
  484.               No NCran1994  10 Dreaming My Dreams   03:37
  485.               No NCran1994  11 Yeat's Grave         02:59
  486.               No NCran1994  12 Daffodil Lament      06:09
  487.               No NCran1994  13 No Need To Argue     02:56
  488.               MachDeep1972  01 Highway Star         06:05
  489.               MachDeep1972  02 Maybe I'm A Leo      04:51
  490.               MachDeep1972  03 Pictures Of Home     05:03
  491.               MachDeep1972  04 Never Before         03:56
  492.               MachDeep1972  05 Smoke On The Water   05:40
  493.               MachDeep1972  06 Lazy                 07:19
  494.               MachDeep1972  07 Space Truckin'       04:31
  495.  
  496.  
  497. ΓòÉΓòÉΓòÉ 6.3. Tutorial: Index Files Used ΓòÉΓòÉΓòÉ
  498.  
  499. The index files created for this database are, for CTAY: Title+Artist and 
  500. Artist+Title (the + indicates a compound key made up of more than one field); 
  501. for CTTT: Code+TrackName and TrackName+Code.  With these indexes, searching can 
  502. be made on CD title, by Artist, or by TrackName.  If searching by year is 
  503. required, an additional index could be used, such as Year+Artist+Title (Title 
  504. being used as part of the key in case an Artist releases more than one title in 
  505. a year). 
  506.  
  507. To search by CD title, a title is used as the key.  Even a partial title can be 
  508. used during the actual lookup.  For example, 'Mexican'.  From this, a search is 
  509. made in the Title+Artist index.  The first key starting with 'Mexican' is 
  510. returned.  The index can then be traversed to find any other keys also starting 
  511. with this (by getting the next key).  Since Bullet has high-level access 
  512. routines (GET_FIRST_XB, for example), where a key search returns the data 
  513. record, once a key is found its data is already in memory (the record is 
  514. typically read directly into a structure variable you have set up).  This lets 
  515. you move through the CTAY file getting each record in key order, one at a time 
  516. (one key and record per call to Bullet). 
  517.  
  518. With the data record in memory, the Code field in the record (CTAY table) is 
  519. used as a foreign key into CTTT.  A new search needs to be done, this time on 
  520. the Code+TrackName index of the CTTT table.  With the search key set to 
  521. 'MexiConc1993' (the foreign key field in CTAY of the record that first matched 
  522. 'Mexican'), the Code+TrackName index for CTTT is searched.  The first key 
  523. starting with 'MexiConc1993' is returned, and its data record.  In that record 
  524. is the track name, track number, and track time.  When done with that record, 
  525. the index can be tranversed in-order (forward, or even backward), and, so long 
  526. as the first 12 characters of the Code+TrackName key match 'MexiConc1993', that 
  527. key's record is used.  When the match is no longer true in those first 12 
  528. characters, which in the example data occurs after 13 tracks have been read, it 
  529. means that all matching keys in that index file have been found, and there are 
  530. no others matching the criterion. 
  531.  
  532. The TrackName part of Code+TrackName (the part of the key after the first 12 
  533. characters) is not needed as a match criterion in this case; TrackName is being 
  534. used solely for the purpose of making the key unique to that particular CD 
  535. Title (all Code fields are the same for each trackname on the CD). 
  536.  
  537. A possible additional index file would be a key based on Code, for CTAY (there 
  538. is such an index already for CTTT).  This would allow indexed access to the 
  539. CTAY table when looking for the Title of a track name.  (In other words, you 
  540. have a list of track names of all CDs in the database, in track name order, and 
  541. want to know the CD Title for each track you see.)  Even without an index this 
  542. can be done by using the Code value in CTTT as a sequential search lookup value 
  543. in CTAY (searching for the matching Code value in CTAY).  This additional index 
  544. is not used here. 
  545.  
  546.  
  547. ΓòÉΓòÉΓòÉ 6.4. Tutorial: Creating the Data Files ΓòÉΓòÉΓòÉ
  548.  
  549. Now that the output requirements are known, and the layout of the data records 
  550. of the two data files constructed, and the index access methods designed, the 
  551. database can be created.  Bullet provides routines to create the files of the 
  552. database according to specifications that you supply. 
  553.  
  554. The CTAY (Code-Title-Artist-Year) and CTTT (Code-Track-TrackName-Time) tables 
  555. are to be in this format: 
  556.  
  557.   CTAY TABLE
  558.  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  559.  Γöé   CODE     Γöé      TITLE      Γöé     ARTIST      ΓöéYEAR Γöé
  560.  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  561.   MexiConc1993  Mexican Moon      Concrete Blonde  1993   (sample record)
  562.      :
  563.  
  564.  CODE      character data, 12 bytes
  565.  TITLE     character data, 32 bytes
  566.  ARTIST    character data, 35 bytes
  567.  YEAR      character data, 4 bytes
  568.  
  569.  
  570.   CTTT TABLE
  571.  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  572.  Γöé    CODE    ΓöéTRKΓöé     TRACKNAME      ΓöéTIME Γöé
  573.  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  574.   MexiConc1993  01 Jenny I Read         05:18   (sample record)
  575.       :
  576.  
  577.  CODE      character data, 12 bytes
  578.  TRK       character data, 2 bytes
  579.  TRACKNAME character data, 40 bytes
  580.  TIME      character data, 5 bytes
  581.  
  582. The fields are sized primarily on expected need.  Since each DBF record has a 
  583. 1-byte tag field, the sum of the above record layouts, including the tag byte, 
  584. is aligned to an even 4-byte size.  An admirable goal, but not a primary design 
  585. consideration.  CTAY is 84 bytes per record; CTTT is 60 bytes per record. 
  586.  
  587. Data is not entered during the create process.  That comes later.  The create 
  588. is only to make the physical files.  The following is the Bullet code required 
  589. to build the two data files.  The index files are covered later. 
  590.  
  591. typedef struct _CTAY {
  592.  CHAR tag;
  593.  CHAR code[12];
  594.  CHAR title[32];
  595.  CHAR artist[35];
  596.  CHAR year[4];
  597. } CTAY;         // (total CTAY record length is 84 bytes)
  598. CTAY ctayRec;
  599.  
  600. CHAR ctayName[] = "CTAY.DBF";
  601. ULONG ctayID=0;                             // handle of CTAY file
  602. FIELDDESCTYPE ctayFieldList[4];             // 4 fields used by the record
  603. memset(ctayFieldList,0,sizeof(ctayFieldList));  // init unused bytes to 0
  604.  
  605. typedef struct _CTTT {
  606.  CHAR tag;
  607.  CHAR code[12];
  608.  CHAR trk[2];
  609.  CHAR trackName[40];
  610.  CHAR time[5];
  611. } CTTT;         // (total CTTT record length is 60 bytes)
  612. CTTT ctttRec;
  613.  
  614. CHAR ctttName[] = "CTTT.DBF";
  615. ULONG ctttID=0;
  616. FIELDDESCTYPE ctttFieldList[4];
  617. memset(ctttFieldList,0,sizeof(ctttFieldList));
  618.  
  619. // field descriptor info for CTAY
  620.  
  621. strcpy(ctayFieldList[0].fieldName, "CODE");
  622. ctayFieldList[0].fieldType = 'C';
  623. ctayFieldList[0].fieldLen = 12;
  624. ctayFieldList[0].fieldDC = 0;
  625.  
  626. strcpy(ctayFieldList[1].fieldName, "TITLE");
  627. ctayFieldList[1].fieldType = 'C';
  628. ctayFieldList[1].fieldLen = 32;
  629. ctayFieldList[1].fieldDC = 0;
  630.  
  631. strcpy(ctayFieldList[2].fieldName, "ARTIST");
  632. ctayFieldList[2].fieldType = 'C';
  633. ctayFieldList[2].fieldLen = 35;
  634. ctayFieldList[2].fieldDC = 0;
  635.  
  636. strcpy(ctayFieldList[3].fieldName, "YEAR");
  637. ctayFieldList[3].fieldType = 'C';
  638. ctayFieldList[3].fieldLen = 4;
  639. ctayFieldList[3].fieldDC = 0;
  640.  
  641. // field descriptor info for CTTT
  642.  
  643. strcpy(ctttFieldList[0].fieldName, "CODE");
  644. ctttFieldList[0].fieldType = 'C';
  645. ctttFieldList[0].fieldLen = 12;
  646. ctttFieldList[0].fieldDC = 0;
  647.  
  648. strcpy(ctttFieldList[1].fieldName, "TRACK");
  649. ctttFieldList[1].fieldType = 'C';
  650. ctttFieldList[1].fieldLen = 2;
  651. ctttFieldList[1].fieldDC = 0;
  652.  
  653. strcpy(ctttFieldList[2].fieldName, "TRACKNAME");
  654. ctttFieldList[2].fieldType = 'C';
  655. ctttFieldList[2].fieldLen = 40;
  656. ctttFieldList[2].fieldDC = 0;
  657.  
  658. strcpy(ctttFieldList[3].fieldName, "TIME");
  659. ctttFieldList[3].fieldType = 'C';
  660. ctttFieldList[3].fieldLen = 5;
  661. ctttFieldList[3].fieldDC = 0;
  662.  
  663. // create the CTAY file
  664.  
  665. CDP.func = CREATE_DATA_XB;
  666. CDP.filenamePtr = ctayName;
  667. CDP.noFields = 4;
  668. CDP.fieldListPtr = ctayFieldList;
  669. CDP.fileID = 3;
  670. rez = BULLET(&CDP);
  671. if (rez) {
  672.    printf("Failed CTAY create.  Err: %d\n",rez);
  673.    return(rez);
  674. }
  675.  
  676. // create the CTTT file
  677.  
  678. CDP.func = CREATE_DATA_XB;
  679. CDP.filenamePtr = ctttName;
  680. CDP.noFields = 4;
  681. CDP.fieldListPtr = ctttFieldList;
  682. CDP.fileID = 3;
  683. rez = BULLET(&CDP);
  684. if (rez) {
  685.    printf("Failed CTTT create.  Err: %d\n",rez);
  686.    return(rez);
  687. }
  688.  
  689.  
  690. ΓòÉΓòÉΓòÉ 6.5. Tutorial: Opening the Data Files ΓòÉΓòÉΓòÉ
  691.  
  692. Before using a data file it must be opened.  Any DBF file can be opened, 
  693. whether created by Bullet or another program.  Before creating indexes for the 
  694. data files created here, the data files must be open.  The handles of the open 
  695. data files are used in the index file create process. 
  696.  
  697.  
  698. // open CTAY and store handle to ctayID
  699.  
  700. OP.func = OPEN_DATA_XB;
  701. OP.filenamePtr = ctayData;
  702. OP.asMode = READWRITE | DENYNONE;
  703. rez = BULLET(&OP);
  704. if (rez) {
  705.    printf("Failed CTAY file open.  Err: %d\n",rez);
  706.    return(rez);
  707. }
  708. ctayID = OP.handle;
  709.  
  710. // open CTTT and store handle to ctttID
  711.  
  712. OP.func = OPEN_DATA_XB;
  713. OP.filenamePtr = ctttData;
  714. OP.asMode = READWRITE | DENYNONE;
  715. rez = BULLET(&OP);
  716. if (rez) {
  717.    printf("Failed CTTT file open.  Err: %d\n",rez);
  718.    return(rez);
  719. }
  720. ctttID = OP.handle;
  721.  
  722.  
  723. ΓòÉΓòÉΓòÉ 6.6. Tutorial: Creating the Index Files ΓòÉΓòÉΓòÉ
  724.  
  725. Two pairs of index files are used.  For CTAY, Title+Artist and Artist+Title; 
  726. for CTTT, Code+TrackName and TrackName+Code.  These are expected to be unique, 
  727. and so the index files are specified to not accept duplicate keys.  Also, 
  728. rather than using the full field sizes for key expressions, substrings are 
  729. specified.  Long keys affect performance, both in index file size and general 
  730. access speed (smaller is usually better), and using the entire field data does 
  731. little to differentiate the key (for the uniqueness requirement).  If 
  732. DUPS_ALLOWED were specified, even shorter keys could be used, though duplicates 
  733. generally are not desirable.  If there comes a record whose generated key is 
  734. not unique (i.e., it already belongs to another already-added record), either 
  735. modify the data entered so that its key is different, if possible, or redo your 
  736. index files to allow duplicates.  You could also play if 'safe' and permit 
  737. duplicates keys to occur from the outset, knowing that not many duplicates will 
  738. occur, where if they do, you can continue and let Bullet managed the duplicate 
  739. key with an enumerator.  If many duplicates of keys are possible, re-evaluate 
  740. your key expression to make it more unique.  This is done by using a compound 
  741. key with more field components.  Still, the fewer components in a key, and the 
  742. shorter, the better the key is. 
  743.  
  744. Index file creation: 
  745.  
  746. CHAR xTitleName[] = "TITLE.IX3";
  747. CHAR xTitleExp[] = "SUBSTR(TITLE,1,8)+SUBSTR(ARTIST,1,8)";
  748. CHAT xTitleBuffer[16];          // key buffer for later use
  749.                                 // note that if DUPS_ALLOWED, the key buffer must
  750.                                 // provide room for the enumerator (2 bytes more)
  751.  
  752. CHAR xArtistName[] = "ARTIST.IX3";
  753. CHAR xArtistExp[] = "SUBSTR(ARTIST,1,8)+SUBSTR(TITLE,1,8)";
  754. CHAT xArtistBuffer[16];
  755.  
  756. CHAR xCodeName[] = "CODETRK.IX3";
  757. CHAR xCodeExp[] = "CODE+SUBSTR(TRACKNAME,1,12)";
  758. CHAT xCodeBuffer[24];
  759.  
  760. CHAR xTrackName[] = "TRKNAME.IX3";
  761. CHAR xTrackExp[] = "SUBSTR(TRACKNAME,1,12)+CODE";
  762. CHAT xTrackBuffer[24];
  763.  
  764. // create two index files for CTAY
  765.  
  766. CIP.func = CREATE_INDEX_XB;
  767. CIP.filenamePtr = xTitleName;
  768. CIP.keyExpPtr = xTitleExp;
  769. CIP.xbLink = ctayID;            // the handle of the open CTAY file
  770. CIP.sortFunction = NLS_SORT;    // sort key by NLS for proper mixed-case order
  771. CIP.codePage = 0;               // use OS-default code page
  772. CIP.countryCode = 0;            // use OS-default country code
  773. CIP.collatePtr = NULL;          // no need for a special collate table
  774. CIP.nodeSize = 512;             // 512-byte node size (or 1024, 2048 bytes)
  775. rez = BULLET(&CIP);
  776. if (rez) {
  777.    printf("Failed Title index create.  Err: %d\n",rez);
  778.    return(rez);
  779. }
  780.  
  781. CIP.filenamePtr = xArtistName;
  782. CIP.keyExpPtr = xArtistExp;     // other values still valid from above
  783. rez = BULLET(&CIP);
  784. if (rez) {
  785.    printf("Failed Artist index create.  Err: %d\n",rez);
  786.    return(rez);
  787. }
  788.  
  789. // create two index files for CTTT
  790.  
  791. CIP.func = CREATE_INDEX_XB;
  792. CIP.filenamePtr = xCodeName;
  793. CIP.keyExpPtr = xCodeExp;
  794. CIP.xbLink = ctttID;            // as above...
  795. CIP.sortFunction = NLS_SORT;
  796. CIP.codePage = 0;
  797. CIP.countryCode = 0;
  798. CIP.collatePtr = NULL;
  799. CIP.nodeSize = 512;
  800. rez = BULLET(&CIP);
  801. if (rez) {
  802.    printf("Failed Code index create.  Err: %d\n",rez);
  803.    return(rez);
  804. }
  805.  
  806. CIP.filenamePtr = xTrackName;
  807. CIP.keyExpPtr = xTrackExp;      // other values still valid from above
  808. rez = BULLET(&CIP);
  809. if (rez) {
  810.    printf("Failed TrackName index create.  Err: %d\n",rez);
  811.    return(rez);
  812. }
  813.  
  814.  
  815. ΓòÉΓòÉΓòÉ 6.7. Tutorial: Opening the Index Files ΓòÉΓòÉΓòÉ
  816.  
  817. Before using an index file it must be opened.  Only Bullet index files can be 
  818. opened. 
  819.  
  820. // open Title index and store handle to xTitleID
  821.  
  822. OP.func = OPEN_INDEX_XB;
  823. OP.filenamePtr = xTitleName;
  824. OP.asMode = READWRITE | DENYNONE;
  825. OP.xbLink = ctayID;                     // note xbLink
  826. rez = BULLET(&OP);
  827. if (rez) {
  828.    printf("Failed Title index open.  Err: %d\n",rez);
  829.    return(rez);
  830. }
  831. xTitleID = OP.handle;
  832.  
  833. // open Artist index and store handle to artistID
  834.  
  835. OP.func = OPEN_INDEX_XB;
  836. OP.filenamePtr = xArtistName;
  837. OP.asMode = READWRITE | DENYNONE;
  838. OP.xbLink = ctayID;
  839. rez = BULLET(&OP);
  840. if (rez) {
  841.    printf("Failed Artist index open.  Err: %d\n",rez);
  842.    return(rez);
  843. }
  844. xArtistID = OP.handle;
  845.  
  846. // open Code index and store handle to xCodeID
  847.  
  848. OP.func = OPEN_INDEX_XB;
  849. OP.filenamePtr = xCodeName;
  850. OP.asMode = READWRITE | DENYNONE;
  851. OP.xbLink = ctttID;
  852. rez = BULLET(&OP);
  853. if (rez) {
  854.    printf("Failed Code index open.  Err: %d\n",rez);
  855.    return(rez);
  856. }
  857. xCodeID = OP.handle;
  858.  
  859. // open TrackName index and store handle to xTrackNameID
  860.  
  861. OP.func = OPEN_INDEX_XB;
  862. OP.filenamePtr = xTrackName;
  863. OP.asMode = READWRITE | DENYNONE;
  864. OP.xbLink = ctttID;
  865. rez = BULLET(&OP);
  866. if (rez) {
  867.    printf("Failed TrackName index open.  Err: %d\n",rez);
  868.    return(rez);
  869. }
  870. xTrackNameID = OP.handle;
  871.  
  872.  
  873. ΓòÉΓòÉΓòÉ 6.8. Tutorial: Inserting CD Title Data ΓòÉΓòÉΓòÉ
  874.  
  875. The files have been created, and are open.  Data may now inserted into the 
  876. database.  The term 'inserted' is used in contrast to 'added' since Bullet 
  877. 'adds' data only, while it 'inserts' data and key information together (and 
  878. especially, the key is inserted, in order).  The CD data entry would typically 
  879. be done via the keyboard.  This tutorial assumes that this has already been 
  880. done, and that the data items are in the following structure variables: 
  881. ctayRec for CD title data; ctttRec for track data. 
  882.  
  883. First, the CD title record is added to CTAY with a key inserted into the Title 
  884. index and another key into Artist index.  Data entered by the user consists of 
  885. CD title, artist, and year.  The Code field is generated by the program code, 
  886. shown below. 
  887.  
  888. // ctayRec has CD title, artist, and year -- generate Code field data
  889.  
  890. strncpy(ctayRec.code  ,ctayRec.title,4);   // first 4 of title
  891. strncpy(ctayRec.code+4,ctayRec.artist,4);  // first 4 of artist
  892. strncpy(ctayRec.code+8,ctayRec.year,4);    // and 4 of year make the Code field
  893.  
  894. // insert CD title data (one data record added, two index files inserted into)
  895.  
  896. AP[0].func = INSERT_XB;
  897. AP[0].handle = xTitleID;        // handle of Title index
  898. AP[0].recNo = 0;                // required
  899. AP[0].recPtr = &ctayRec;        // the CD title record
  900. AP[0].keyPtr = xTitleBuffer;    // key buffer
  901. AP[0].nextPtr = &AP[1];         // since two index files, point to next
  902. AP[1].handle = xArtistID:       // handle of Artist index
  903. AP[1].recNo = 0x80000000;       // required
  904. AP[1].recPtr = &ctayRec;        // the CD title record
  905. AP[1].keyPtr = xArtistBuffer;   // key buffer
  906. AP[1].nextPtr = NULL;
  907.  
  908. rez = BULLET(&AP[0]);
  909. if (rez) {                      // rez is not error, but pack index of error
  910.    rc = AP[abs(rez)-1].stat;
  911.    printf("Insert failed, pack: %d, err: %d\n",rez,rc);
  912.    return(rc);
  913. }
  914.  
  915. A CD title has been entered.  That's the first part of the data entry.  Next, 
  916. each track on that CD needs to be entered.  It needs the Code field data 
  917. generated above, along with the general track data (track name, etc.). 
  918.  
  919.  
  920. ΓòÉΓòÉΓòÉ 6.9. Tutorial: Inserting CD Track Data ΓòÉΓòÉΓòÉ
  921.  
  922. During the CD title insert, a Code field value was generated.  That field value 
  923. is used for each of the track entries inserted into database for this CD.  The 
  924. actual track data has already been placed in the ctttRec structure variable (by 
  925. the main program code, not shown here), and only the Code field of ctttRec 
  926. needs to be set.  Once done, the track record is inserted, this time into the 
  927. CTTT data file and the Code and Track index files. 
  928.  
  929. //
  930. // this code section is repeated for each track on the CD
  931. //
  932.  
  933. // copy Code field data from CTAY
  934.  
  935. strncpy(ctttRec.code,ctayRec.code,12); // use Title's Code for each Track entry
  936.  
  937. // insert track data (one data record added, two index files inserted into)
  938.  
  939. AP[0].func = INSERT_XB;
  940. AP[0].handle = xCodeID;         // handle of Code index
  941. AP[0].recNo = 0;                // required
  942. AP[0].recPtr = &ctttRec;        // the track record
  943. AP[0].keyPtr = xCodeBuffer;     // key buffer
  944. AP[0].nextPtr = &AP[1];         // since two index files, point to next
  945. AP[1].handle = xTrackID:        // handle of TrackName index
  946. AP[1].recNo = 0x80000000;       // required
  947. AP[1].recPtr = &ctttRec;        // the track record
  948. AP[1].keyPtr = xTrackBuffer;    // key buffer
  949. AP[1].nextPtr = NULL;
  950.  
  951. rez = BULLET(&AP[0]);
  952. if (rez) {                      // rez is not error, but pack index of error
  953.    rc = AP[abs(rez)-1].stat;
  954.    printf("Insert failed, pack: %d, err: %d\n",rez,rc);
  955.    return(rc);
  956. }
  957.  
  958. // and repeat for each track on the CD
  959.  
  960. The database now contains a complete entry for the one CD.  This process is 
  961. repeated for each CD that is to entered into the database.  This is the data 
  962. entry process.  Data retrieval is covered next. 
  963.  
  964.  
  965. ΓòÉΓòÉΓòÉ 6.10. Tutorial: Retrieving Data ΓòÉΓòÉΓòÉ
  966.  
  967. The database can be accessed in several different ways.  For indexed access, 
  968. any index file can be used.  Alternatively, direct access without an index 
  969. could also be used.  Generally, since there's no guarantee that the physical 
  970. order of rows in the database is in any order at all, index access is usually 
  971. desired.  Possible retrievals are by: 
  972.  
  973. 1. CD title, in alphabetical order, and, from information from the CD title, 
  974. all tracks on the CD.  The tracks are read into an array and sorted by track 
  975. number.  Alternatively, a separate index could be used to order track entries 
  976. by TrackNo+TrackName(+etc.), but since there are so few tracks per CD 
  977. (generally less than 20), it's much more efficient to simply get all tracks for 
  978. a CD title into an array, and then sort that array for presentation. 
  979. Otherwise, an index file would need to be maintained on a permanent basis, and 
  980. for something that can easily be done at run-time (and then discarded). 
  981.  
  982. 2. Artist, in alpha order.  Access is similar to CD title, above, since it uses 
  983. the same data file (CTAY).  As above, tracks for each artist's title can then 
  984. be retrieved.  The only difference between this and the CD title access is that 
  985. this lists CDs by artist, rather than by title. 
  986.  
  987. 3. Track name, in alphabetical order.  This lists all tracks by track name, in 
  988. order, with different tracks intermixed with CD titles.  In other words, if 
  989. three CDs had the track called "In the Summer Time", then each of those tracks 
  990. would appear together, one after the other.  There is no index available in 
  991. this database to access the CD on which the track name appears, so you cannot 
  992. go from trackname alone to CD title (by index).  However, since the Code field 
  993. is available, and is common to each data file, the Code field value of a track 
  994. record can be used to sequentially search the Title records for a match.  This 
  995. is a non-indexed search.  Access is slower than if an index were available, but 
  996. unless you created indexes for all possible search methods, some sequential 
  997. (read: slow) searching may be required.  For smaller files (less than 10,000 
  998. records), or where only a few such searches occur, this may be perfectly 
  999. acceptable. 
  1000.  
  1001. An index on Code exists (for CTTT, but not CTAY), and you may find a use for 
  1002. this other than for use as a foreign key lookup.  Also, you may create ad hoc 
  1003. index files whenever you need to, and these can be deleted when no longer 
  1004. required.  Since Bullet can create an index for even a large file in just a few 
  1005. seconds, this is a viable option; the few seconds needed to create an index may 
  1006. be many times repaid in the time saved in sequential searches on a non-indexed 
  1007. access. 
  1008.  
  1009. The first retrieval mentioned is shown next. 
  1010.  
  1011. // for each CD title in the database, display all its tracks
  1012.  
  1013.                         // ctayRec already defined
  1014. CTTT cttyRecs[59];      // store each Track record for later sorting by track#
  1015.  
  1016. // This would be repeated for each CD title (only the first is shown).
  1017. // Note: For the next CD title, GET_NEXT_XB would be used.  If necessary,
  1018. // the key just accessed could be stored (preserved), then laster reaccessed
  1019. // using GET_EQUAL_XB again, and then immediately followed with a GET_NEXT_XB.
  1020. // This way, you can stop processing completely, and restart up where you left
  1021. // off.
  1022.  
  1023. // files are locked as required (e.g., full-lock, shared)
  1024.  
  1025. AP.func = GET_FIRST_XB;
  1026. AP.handle = xTitleID;
  1027. AP.recPtr = &ctayRec;
  1028. AP.keyPtr = xTitleBuffer;
  1029. rez = BULLET(&AP);
  1030. while (rez==0) {
  1031.    printf("Title: %s  Artist: %s  Year: %s\n",
  1032.            ctayRec.title,
  1033.            ctayRec.artist,
  1034.            ctayRec.year);
  1035.  
  1036.    // get each track belonging to this CD title (same Code values)
  1037.  
  1038.    int trk=0;                            // counter
  1039.    memset(xCodeBuffer,0,sizeof(xCodeBuffer)); // clear it to 0
  1040.    strncpy(xCodeBuffer,ctayRec.code,12); // copy Code to search-for buffer
  1041.  
  1042.    AP.func = GET_EQUAL_XB;
  1043.    AP.handle = xCodeID;
  1044.    AP.recPtr = &ctttRecs[trk];
  1045.    AP.keyPtr = xCodeBuffer;             // find Code
  1046.    rez = BULLET(&AP);
  1047.  
  1048.    // rather than print each when gotten, collect them, sort, then display
  1049.    // if rez==0 here then Code matched exactly, no strncmp needed, otherwise,
  1050.    // there's no match on the first 12 characters of Code
  1051.  
  1052.    AP.func = GET_NEXT_XB;               // continue getting while same Code
  1053.    while (rez==0) {
  1054.       trk++;                            // limit to array size...
  1055.       AP.recPtr = &ctttRecs[trk];       // read into next array record
  1056.       rez = BULLET(&AP);
  1057.       if (rez==0) {
  1058.  
  1059.          // if code field in CTTT no longer the same as CTAY, then have them all
  1060.  
  1061.          if (strncmp(ctttRecs[trk].code,ctayRec.code,12)!=0) {
  1062.             rez = 1;
  1063.             break;                      // different Code fields
  1064.          }
  1065.       }
  1066.    }
  1067.  
  1068.    // if rez==1 or at end of file then no error, sort and display --
  1069.    // trk at this point is number of tracks that matched Code (1-based)
  1070.    // DoSortOf... routine sorts the ctttRecs array with trk count of elements
  1071.  
  1072.    if ((rez==1) | (rez==EXB_END_OF_FILE)) {
  1073.       DoSortOfTheTrackRecordsByTrackNumber(&ctttRecs[0],trk);
  1074.  
  1075.       // print each track record, now sorted by track number
  1076.  
  1077.       for (i=0;i < trk;i++) {
  1078.          printf("Trk: %s  Name: %s   Time: %s\n",
  1079.                  ctttRecs[i].trk,
  1080.                  ctttRecs[i].trackName,
  1081.                  ctttRecs[i].time);
  1082.       }
  1083.    else {
  1084.        printf("failed, rez: %d\n",rez);
  1085.        return(rez);
  1086.    }
  1087. }
  1088.  
  1089.  
  1090. ΓòÉΓòÉΓòÉ 6.11. Tutorial: Preparing to End Your Program ΓòÉΓòÉΓòÉ
  1091.  
  1092. It's proper programming practice to perform an orderly shutdown of Bullet when 
  1093. ending your program.  This also extends to files, too, where even if you are 
  1094. not ending your program, but are finished using a file, close that file so that 
  1095. you release the resources allocated for it. 
  1096.  
  1097. In the event that an abnormal termination occurs, and you are unable to release 
  1098. outstanding locks and close all files, you may choose to call EXIT_XB and allow 
  1099. that to close files (the OS releases locks when the file is closed).  If you 
  1100. are unable to call even EXIT_XB, there is still another method that gets 
  1101. Bullet's attention.  During Bullet initialization, the EXIT_XB routine is 
  1102. registered with the OS so that whenever your program terminates (or is 
  1103. terminated), EXIT_XB is called automatically.  This ensures that headers are 
  1104. properly written in all but the most severe of abnormal terminations (abend), 
  1105. such as a lockup. 
  1106.  
  1107. // all outstanding locks should have been released immediately after use
  1108.  
  1109. // close each file that was opened
  1110.  
  1111. HP.func = CLOSE_DATA_XB
  1112. HP.handle = xTitleID;
  1113. if (HP.handle) rez = BULLET(&HP);
  1114. if (rez) printf("close failed, err: %d\n",rez);
  1115.  
  1116. HP.handle = xArtistID;
  1117. if (HP.handle) rez = BULLET(&HP);
  1118. if (rez) printf("close failed, err: %d\n",rez);
  1119.  
  1120. HP.handle = xCodeID;
  1121. if (HP.handle) rez = BULLET(&HP);
  1122. if (rez) printf("close failed, err: %d\n",rez);
  1123.  
  1124. HP.handle = xTrackID;
  1125. if (HP.handle) rez = BULLET(&HP);
  1126. if (rez) printf("close failed, err: %d\n",rez);
  1127.  
  1128. EP.func = EXIT_XB;
  1129. rez = BULLET(&EP);
  1130. if (rez) printf("exit failed, err: %d\n",rez);
  1131.  
  1132. // Bullet is now deinitialized, and must be INIT_XB'ed before further use
  1133.  
  1134.  
  1135. ΓòÉΓòÉΓòÉ 7. History of Changes ΓòÉΓòÉΓòÉ
  1136.  
  1137. Changes Made 
  1138.  
  1139. 2.50 25-Jun-97: 
  1140.  
  1141.    1. Modifed Win32 DLL to work in NT4. 
  1142.    2. Changed the way a Next/Prev key access works after reaching EOF/TOF. 
  1143.       E.g., now when EOF is reached a Prev key access will get the second to 
  1144.       last key, in order, rather than re-getting the last key. 
  1145.    3. Fixed when using ATOMIC_MODE=1 in SET_SYSVARS_XB, and you have 
  1146.       DUPS_ALLOWED allowed, when using INSERT_XB, UPDATE_XB, or LAST_KEY_XB, 
  1147.       where error EXB_KEY_NOT_FOUND (8501) was returned when the key newly 
  1148.       inserted/updated already existed. 
  1149.    4. Fixed PREV_KEY/GET_PREV_XB where only the first encounter of 
  1150.       EXB_TOP_OF_FILE was returned, after which out-of-order key was returned. 
  1151.  
  1152.  2.14 29-May-97: 
  1153.  
  1154.    1. Fix for key order bug dropping to ASCII sort even when ASCII sort was not 
  1155.       picked. 
  1156.  
  1157.  2.13 23-Nov-96: 
  1158.  
  1159.    1. Added EQUAL_OR_GREATER_KEY/LESSER_KEY for fuzzy key access (atomic). 
  1160.    2. Added GET_EQUAL_OR_GREATER/LESSER for fuzzy key+record access (atomic). 
  1161.    3. Increased maximum fields from 255 to 1024 for dBASE 5 DBFs. 
  1162.    4. Update of data record would not set DBF dirty flag, though effect was 
  1163.       minimal (last update timestamp in DBF header not set). 
  1164.    5. Fixed Bullet/2 REXX interface DLL dispatcher. 
  1165.  
  1166.  2.12 6-Nov-96: 
  1167.  
  1168.    1. New, lower prices!  Order direct-from-author or from BMT Micro. 
  1169.    2. New source example, compact.c, to compact DBFs with attached DBT memo 
  1170.       file. 
  1171.    3. Release 2.12.  Code version is 2.11. 
  1172.  
  1173.  2.11 16-Oct-96: 
  1174.  
  1175.    1. New order option, option E, includes DOSX32, OS/2 and Win32 versions of 
  1176.       Bullet all in one box. 
  1177.  
  1178.  2.105 11-Oct-96: 
  1179.  
  1180.    1. Added OS function override revectoring for all OS calls made, and added 
  1181.       supporting query/set routines, QUERY/SET_VECTORS_XB. 
  1182.    2. Added USE_ANSI_SET flag for index file collate sequence table (esp. for 
  1183.       Windows), in addition to standard OEM character set, for use at 
  1184.       CREATE_INDEX_XB. 
  1185.    3. Added shared/exclusive region locking mode for NT. 
  1186.    4. UPDATE_XB efficiency improved, esp. with large number of index files. 
  1187.    5. Internal sort efficiency improved (even faster). 
  1188.    6. Improved demo program samples; also added compile option for generating 
  1189.       console or windowed app. 
  1190.    7. Consolidated Bullet header files into one, for all platforms, with 
  1191.       minimal conditionals; the file is named bullet_2.h. 
  1192.  
  1193.  2.103 4-Oct-1996: 
  1194.  
  1195.    1. Win32 version would fail under NT (and Win32s) because of un-saved 
  1196.       register into consecutive kernel calls. 
  1197.    2. Win32s now supported. 
  1198.    3. Win32 version now in a single DLL (supports Watcom (old and new) and VC4, 
  1199.       both, and both Win32 and Win32s). 
  1200.    4. CREATE_INDEX_XB was always using OS-supplied codepage/country code. 
  1201.    5. Added callback support in reindex and pack records, esp. useful for 
  1202.       DOSX32 and Win32s. 
  1203.    6. UPPER() in key expression would fail. 
  1204.  
  1205.  2.101 28-Aug-1996: 
  1206.  
  1207.    1. REINDEX_XB would fail on certain key sizes, causing an access 
  1208.       violation/GPF. 
  1209.  
  1210.  2.100 3-Aug-1996: 
  1211.  
  1212.    1. REINDEX_XB and GET_LAST_XB could fail if DUPS_ALLOWED. 
  1213.    2. Sort functions 1, 2, and 3 were operating as expected but 4-6 were using 
  1214.       3. 
  1215.    3. Node scanning was using the wrong sort-compare function (1 was using 3, 2 
  1216.       was using 1, and 3 was using 2). 
  1217.    4. UPDATE_XB was returning failed pack's AP[].stat=1 instead of true error 
  1218.       code if the update failed when inserting a new key. 
  1219.    5. BUILD_KEY_XB was not issuing skip tag warning, and was not passing 
  1220.       .recPtr to external build key function. 
  1221.    6. PACK_RECORDS_XB and DEBUMP_RECORD_XB values in bullet2.h were 
  1222.       interchanged: Pack is 47; Debump is 46. 
  1223.    7. DEBUMP_RECORD_XB requires FLUSH_DATA_HEADER_XB call prior to use. 
  1224.    8. Documentation errata: GET_DESCRIPTOR_XB uses DP.handle for IN; includes 
  1225.       DP.FD.altFieldLength for OUT (DP.fieldOffset noted previously) 
  1226.    9. GET_DESCRIPTOR_XB was not returning info in DP.FD.* when accessed by 
  1227.       fieldName. 
  1228.   10. SDP.lastUpdate year was returned with year-256 (1996 was 1740). 
  1229.   11. GET_ERROR_CLASS_XB was not returning useful info. 
  1230.   12. ZAP_INDEX_HEADER_XB had been making index data start at 16KB size. 
  1231.   13. DosExitList() handler is now dropped after calling EXIT_XB. 
  1232.  
  1233.  2.051 24-Apr-96: 
  1234.  
  1235.    1. Fixes to transaction routines InsertXB and UpdateXB, including Insert 
  1236.       rollback fix with multiple packs. 
  1237.    2. Update pack number return value fix. 
  1238.    3. Update w/ multiple packs fix, and an Update rollback fix. 
  1239.    4. Fix of GetKeyForRecordXB when DUPS_ALLOWED. 
  1240.  
  1241.  2.050 26-Feb-96: 
  1242.  
  1243.    1. Shareware refresh released. 
  1244.  
  1245.  2.044 31-Jan-96: 
  1246.  
  1247.    1. Fixed DUPS_ALLOWED bug at INSERT_XB where error EXB_TOP_OF_FILE or error 
  1248.       EXB_TOO_MANY_DUPLICATES would be returned. 
  1249.  
  1250.  2.043  3-Jan-96: 
  1251.  
  1252.    1. Added atomic key access for NEXT_KEY, PREV_KEY, GET_NEXT, and GET_PREV 
  1253.       for simpler use in multi-threaded programs. 
  1254.    2. Changed EXB_SHARED_LOCK_ON in BULLET2.H (was ERR_ rather than EXB_). 
  1255.  
  1256.  2.042 20-Dec-95: 
  1257.  
  1258.    1. MAKE_DIR_DOS was expecting directory name in DFP.bufferPtr.  Changed to 
  1259.       expect path in DFP.filenamePtr. 
  1260.  
  1261.  2.040 28-Oct-95: 
  1262.  
  1263.    1. BACKUP_FILE_XB extended to back up related memo file on DBF backup. 
  1264.    2. [2.033] Fixed memo file problems. 
  1265.    3. [2.032] Win95 version available. 
  1266.    4. [2.031] DOSX32 version available. 
  1267.  
  1268.  2.031 11-Sep-95: 
  1269.  
  1270.    1. Added DP.fieldOffset to documentation for GET_DESCRIPTOR_XB. 
  1271.    2. Instance tracker purified of DosEnterCritSec need. 
  1272.  
  1273.  2.030 9-Sep-95: 
  1274.  
  1275.    1. Removed erroneous '...header reload...' in online docs of RELOCK_DATA_XB. 
  1276.    2. Default maximum filesizes set to 2047 MB from 2048 MB (absolute max is 
  1277.       4095 MB). 
  1278.    3. Fixed REINDEX_XB so that it actually uses re-evaluted key expression. 
  1279.    4. ATEXIT_XB is obsolete. 
  1280.    5. BREAK_XB is obsolete. 
  1281.  
  1282.  2.020 31-Aug-95: 
  1283.  
  1284.    1. Locality and other cache-related options can be set at file open. 
  1285.    2. IP.versionBullet changed to *1000 from *100 (2020 is version 2.020). 
  1286.    3. Instance tracker corrected. 
  1287.  
  1288.  2.01  22-Aug-95: 
  1289.  
  1290.    1. Changed index header to 1024 bytes from 768 for sector-alignment. 
  1291.    2. Changed header ID to '31ch' from '30ch'. 
  1292.  
  1293.  2.00  20-Aug-95: 
  1294.  
  1295.  Preliminary release. 
  1296.  
  1297.  
  1298. ΓòÉΓòÉΓòÉ 8. Bullet Include File ΓòÉΓòÉΓòÉ
  1299.  
  1300. The Bullet/2 C/C++ header file, BULLET_2.H: 
  1301.  
  1302.  
  1303. /* BULLET_2.H    23-Nov-96-chh
  1304.  *
  1305.  *  Bullet header for 32-bit C/C++ (DOSX32, OS/2, and Win32s/Win32)
  1306.  *  Bullet call numbers, parameter packs, and error number equates
  1307.  *
  1308.  *  Requires PLATFORM defined and set to ON_DOSX32 (3), ON_OS2 (4),
  1309.  *  or ON_WIN32 (5) before getting here.  For example:
  1310.  *    #define PLATFORM ON_DOSX32  (ON_DOSX32 defined as 3)
  1311.  *
  1312.  */
  1313.  
  1314. #ifndef __BULLET_H
  1315. #define __BULLET_H
  1316.  
  1317. /*
  1318.  * The #pragma pack(1)/#pragma pack() is no longer required since all
  1319.  * structure members in this header will align properly -- all are
  1320.  * 32-bit size except for the structure "FieldDescType", but fieldDA
  1321.  * member (a LONG) is at a 32-bit alignment already (at byte offset +12).
  1322.  * The altFieldLength member, same structure, is also already at
  1323.  * proper alignment for a 16-bit value (at byte offset +18).  If, for
  1324.  * some reason, your compiler aligns the members differently, then you
  1325.  * must use the appropriate compiler pragma to prevent this -- the
  1326.  * FieldDescType size is 32 bytes exactly.  It is not likely that any
  1327.  * conforming compiler will alter this structure, but, now you know what
  1328.  * to do if it does.
  1329.  *
  1330.  * #pragma pack(1)
  1331.  *
  1332.  * NOTE: In your program source code, when you layout your record buffer
  1333.  * structure, you must use the #pragma pack(1)/#pragma pack() directives
  1334.  * around it since it will be, most likely, modified.  The reason is that
  1335.  * this structure MUST start with the implicit TAG field (a BYTE), and so,
  1336.  * unless you use only BYTE/CHAR members in your structure (Bullet can use
  1337.  * binary field values), or take special care to align the record layout
  1338.  * so no padding is performed by the compiler, then you will need to use
  1339.  * the pack(1) pragma.
  1340.  *
  1341.  * #pragma pack()
  1342.  */
  1343.  
  1344. /* Re: Bullet/X for DOSX32:
  1345.  * (refer to ccdosfn.c for more)
  1346.  * Bullet ccdosfn.c provides no OS call support to determine the
  1347.  * system country code and code page ID.  This can be coded in
  1348.  * ccdosfn.c, but it is quite compiler- and extender-dependent.
  1349.  * The current state is to supply a collate sequence table for
  1350.  * country code=1 and code page=437 (the table is statically coded).
  1351.  * For other sort tables, modify as required.  If support for this
  1352.  * at the system level is made available at run-time, you may
  1353.  * want to change the following to 0, for both CTRYCODE and CODEPAGE.
  1354.  * Until this is so coded, you cannot use 0 here (as with the Win32
  1355.  * and OS/2 versions), else error EXB_216501 (8251) is the result.
  1356.  * This table is added to each index file (if NLS or a user sort).
  1357.  */
  1358.  
  1359. #ifndef PLATFORM
  1360.  #error No PLATFORM specified
  1361.  #error ---------------------
  1362. #endif
  1363.  
  1364. #ifndef ON_DOSX32
  1365.  #define ON_DOSX32 3
  1366.  #define ON_OS2    4
  1367.  #define ON_WIN32  5
  1368. #endif
  1369.  
  1370. #if PLATFORM == ON_DOSX32
  1371.  #define CTRYCODE 1     /* 0 signifies default country code (at index create) */
  1372.  #define CODEPAGE 437   /* 0 signifies default code page (at index create) */
  1373.                         /* but DOS extender may not support OS call to get info */
  1374.                         /* see ccdosfn.c for making changes for DOSX32 platform */
  1375.  #define RELOCK_AVAIL 0 /* relock not supported */
  1376.  
  1377.  #define VOID void      /* these are already defined if Win32 or OS/2, but not DOS */
  1378.  #define SHORT short
  1379.  #define LONG long
  1380.  #define CHAR char
  1381.  
  1382.  typedef unsigned char BYTE;
  1383.  typedef unsigned short USHORT;
  1384.  typedef unsigned long ULONG;
  1385.  typedef unsigned char *PSZ;
  1386.  typedef VOID *PVOID;
  1387.  
  1388.  #define APIENTRY __cdecl
  1389.  
  1390. #elif PLATFORM == ON_OS2
  1391.  #define CTRYCODE 0
  1392.  #define CODEPAGE 0
  1393.  #define RELOCK_AVAIL 1    /* relock is supported */
  1394.  
  1395.  /* above types are assumed defined in os2def.h */
  1396.  
  1397. #elif PLATFORM == ON_WIN32
  1398.  #define CTRYCODE 0
  1399.  #define CODEPAGE 0     /* may be ANSI or OEM code page value, depending on USE*CHARSET flag */
  1400.  #define RELOCK_AVAIL 0 /* relock not supported */
  1401.  
  1402.  /* above types are assume defined in windef.h and winnt.h */
  1403.  
  1404. #else
  1405.  #error No PLATFORM specified
  1406.  #error ---------------------
  1407.  
  1408. #endif
  1409.  
  1410. #ifndef __BLT_DYNA    // define this if using run-time loading of BULLET*.DLL
  1411.                       // via LoadLibrary(Win32) or DosLoadModule(OS/2)
  1412.  #ifdef __cplusplus
  1413.   extern "C" LONG APIENTRY BULLET(PVOID datapack);
  1414.  #else
  1415.   extern LONG APIENTRY BULLET(PVOID datapack);
  1416.  #endif
  1417.  
  1418. #else
  1419.  
  1420.   LONG (* APIENTRY BULLET)(PVOID datapack);
  1421.  
  1422. #endif
  1423.  
  1424.  
  1425.  
  1426. /* The following on mutex-semaphore protection does not apply to Bullet/X */
  1427. /* unless the semaphore routines (in ccdosfn.c) are coded to do something */
  1428.  
  1429. /* All Bullet routines are mutex-semaphore protected except the following:
  1430.  *
  1431.  * MEMORY_XB            STAT_HANDLE_XB          GET_ERROR_CLASS_XB
  1432.  * QUERY_SYSVARS_XB     QUERY_VECTORS_XB        CHECK_REMOTE_XB
  1433.  * STAT_DATA_XB         STAT_INDEX_XB
  1434.  *
  1435.  * This means that any thread can call the above routines at any time.  All
  1436.  * other calls in the current process block until the previous thread exits
  1437.  * BULLET.  The default mutex wait is 0 milliseconds, and can be set via
  1438.  * SET_SYSVARS_XB using the MUTEX_SEM_TIMEOUT index.  In the case of
  1439.  * STAT_DATA_XB and STAT_INDEX_XB, these should be used only when there
  1440.  * is no chance that another thread may close that file handle while the
  1441.  * routine is working.
  1442.  *
  1443.  */
  1444.  
  1445.  
  1446.  
  1447. /* ************************************************************************
  1448.  *
  1449.  * xxx.func call numbers
  1450.  *
  1451.  * ************************************************************************/
  1452.  
  1453. #define GEN_ERR_XB              0
  1454. #define INIT_XB                 1  /* system */
  1455. #define EXIT_XB                 2
  1456. #define MEMORY_XB               4
  1457. #define BACKUP_FILE_XB          6
  1458. #define STAT_HANDLE_XB          7
  1459. #define GET_ERROR_CLASS_XB      8
  1460.  
  1461. #define QUERY_SYSVARS_XB        10 /* advanced system */
  1462. #define SET_SYSVARS_XB          11
  1463. #define SET_DVMON_XB            12 /* reserved */
  1464. #define QUERY_VECTORS_XB        13
  1465. #define SET_VECTORS_XB          14
  1466.  
  1467. #define CREATE_DATA_XB          20 /* data control mid-level */
  1468. #define OPEN_DATA_XB            21
  1469. #define CLOSE_DATA_XB           22
  1470. #define STAT_DATA_XB            23
  1471. #define READ_DATA_HEADER_XB     24
  1472. #define FLUSH_DATA_HEADER_XB    25
  1473. #define COPY_DATA_HEADER_XB     26
  1474. #define ZAP_DATA_HEADER_XB      27
  1475.  
  1476. #define CREATE_INDEX_XB         30 /* key control mid-level */
  1477. #define OPEN_INDEX_XB           31
  1478. #define CLOSE_INDEX_XB          32
  1479. #define STAT_INDEX_XB           33
  1480. #define READ_INDEX_HEADER_XB    34
  1481. #define FLUSH_INDEX_HEADER_XB   35
  1482. #define COPY_INDEX_HEADER_XB    36
  1483. #define ZAP_INDEX_HEADER_XB     37
  1484.  
  1485. #define GET_DESCRIPTOR_XB       40 /* data access mid-level */
  1486. #define GET_RECORD_XB           41
  1487. #define ADD_RECORD_XB           42
  1488. #define UPDATE_RECORD_XB        43
  1489. #define DELETE_RECORD_XB        44
  1490. #define UNDELETE_RECORD_XB      45
  1491. #define DEBUMP_RECORD_XB        46
  1492. #define PACK_RECORDS_XB         47
  1493.  
  1494. #define GET_MEMO_SIZE_XB        50 /* memo access mid-level */
  1495. #define GET_MEMO_XB             51
  1496. #define ADD_MEMO_XB             52
  1497. #define UPDATE_MEMO_XB          53
  1498. #define DELETE_MEMO_XB          54
  1499. #define MEMO_BYPASS_XB          59 /* see below for bypass ordinals */
  1500.  
  1501. #define BYPASS_CREATE_MEMO       1 /* The bypass routines are automatically */
  1502. #define BYPASS_OPEN_MEMO         2 /* performed by BULLET but can be done */
  1503. #define BYPASS_CLOSE_MEMO        3 /* manually, if needed - these numbers are */
  1504. #define BYPASS_READ_MEMO_HEADER  4 /* put in MDP.memoBypass, with MDP.func */
  1505. #define BYPASS_FLUSH_MEMO_HEADER 5 /* set to MEMO_BYPASS_XB */
  1506.  
  1507.  
  1508.  
  1509. #define FIRST_KEY_XB            60 /* key access mid-level */
  1510. #define EQUAL_KEY_XB            61
  1511. #define EQUAL_OR_GREATER_KEY_XB 110
  1512. #define EQUAL_OR_LESSER_KEY_XB  111
  1513. #define NEXT_KEY_XB             62
  1514. #define PREV_KEY_XB             63
  1515. #define LAST_KEY_XB             64
  1516. #define STORE_KEY_XB            65
  1517. #define DELETE_KEY_XB           66
  1518. #define BUILD_KEY_XB            67
  1519. #define GET_CURRENT_KEY_XB      68
  1520. #define GET_KEY_FOR_RECORD_XB   69
  1521.  
  1522. #define GET_FIRST_XB            70 /* key and data access high-level */
  1523. #define GET_EQUAL_XB            71
  1524. #define GET_EQUAL_OR_GREATER_XB 112
  1525. #define GET_EQUAL_OR_LESSER_XB  113
  1526. #define GET_NEXT_XB             72
  1527. #define GET_PREV_XB             73
  1528. #define GET_LAST_XB             74
  1529. #define INSERT_XB               75
  1530. #define UPDATE_XB               76
  1531. #define REINDEX_XB              77
  1532.  
  1533. #define LOCK_XB                 80 /* network control */
  1534. #define UNLOCK_XB               81
  1535. #define LOCK_INDEX_XB           82
  1536. #define UNLOCK_INDEX_XB         83
  1537. #define LOCK_DATA_XB            84
  1538. #define UNLOCK_DATA_XB          85
  1539. #define CHECK_REMOTE_XB         86
  1540. #define RELOCK_XB               87
  1541. #define RELOCK_INDEX_XB         88
  1542. #define RELOCK_DATA_XB          89
  1543.  
  1544. #define DELETE_FILE_DOS         90 /* DOS file I/O low-level */
  1545. #define RENAME_FILE_DOS         91
  1546. #define CREATE_FILE_DOS         92
  1547. #define OPEN_FILE_DOS           93
  1548. #define SEEK_FILE_DOS           94
  1549. #define READ_FILE_DOS           95
  1550. #define WRITE_FILE_DOS          96
  1551. #define CLOSE_FILE_DOS          97
  1552. #define ACCESS_FILE_DOS         98
  1553. #define EXPAND_FILE_DOS         99
  1554. #define MAKE_DIR_DOS            100
  1555. #define COMMIT_FILE_DOS         101
  1556.  
  1557. /* ************************************************************************
  1558.  *
  1559.  * operating system file I/O equates
  1560.  *
  1561.  * ************************************************************************/
  1562.  
  1563. #define READONLY        0x00000000 /* std file access mode */
  1564. #define WRITEONLY       0x00000001 /* no underscore used for std equates */
  1565. #define READWRITE       0x00000002
  1566.  
  1567. #define DENYREADWRITE   0x00000010 /* std file share mode, cannot be 0 */
  1568. #define DENYWRITE       0x00000020
  1569. #define DENYREAD        0x00000030
  1570. #define DENYNONE        0x00000040
  1571. #define NOINHERIT       0x00000080
  1572.  
  1573. #define NO_LOCALITY     0x00000000 /* optional cache modes */
  1574. #define SEQ_LOCALITY    0x00010000
  1575. #define RND_LOCALITY    0x00020000
  1576. #define MIX_LOCALITY    0x00030000
  1577. #define SKIP_CACHE      0x00100000 /* not inherited by child process */
  1578. #define WRITE_THROUGH   0x00400000 /* not inherited by child process */
  1579.  
  1580.  
  1581. #define LOCK_SHARED      1         /* a read-only lock, OS/2 and NT only */
  1582. #define LOCK_EXCLUSIVE   0         /* default */
  1583.  
  1584. /* ************************************************************************
  1585.  *
  1586.  * .sortFunction IDs, Query/SetSysVars|Vectors item IDs
  1587.  *
  1588.  * ************************************************************************/
  1589.  
  1590. // SORT_SET flag:  USE_*_CHARSET defaults to OEM character set, and is used
  1591. // (OEM or ANSI) if the .sortFunction is NLS or a custom sort-compare.
  1592.  
  1593. #define USE_OEM_CHARSET  (0 << 17) /* for DOSX32, OS/2, and Windows */
  1594. #define USE_ANSI_CHARSET (1 << 17) /* for Windows (.sortFunction flag) */
  1595.  
  1596. #define DUPS_ALLOWED (1 << 16) /* allow duplicate keys (.sortFunction flag) */
  1597.  
  1598. /* All Bullet system vars set to default values at INIT_XB */
  1599. /* Sorts 1-19 also used as CIP.sortFunction (can be OR'ed with DUPS_ALLOWED) */
  1600. /* Intrinsic sorts (1-6) are read-only (R-O) */
  1601.  
  1602. #define ASCII_SORT 1    /* sort by: ASCII value (R-O) */
  1603. #define NLS_SORT   2    /* NLS (R-O) */
  1604. #define S16_SORT   3    /* 16-bit signed integer (R-O) */
  1605. #define U16_SORT   4    /* 16-bit unsigned integer (R-O) */
  1606. #define S32_SORT   5    /* 32-bit signed integer (R-O) */
  1607. #define U32_SORT   6    /* 32-bit unsigned integer (R-O) */
  1608.  
  1609. /* sorts 7 to 9 are reserved */
  1610. /* Custom sort-compare functions are from 10 to 19 */
  1611.  
  1612. #define BUILD_KEY_FUNC  20      /* key build function ptr */
  1613. #define PARSER_FUNC     21      /* key expression parser function ptr */
  1614.  
  1615. #define MUTEX_SEM_HANDLE     29 /* handle of Bullet's mutex semaphore (R-O) */
  1616. #define LOCK_TIMEOUT         30 /* lock-wait timeout (default=0, no wait)*/
  1617. #define MUTEX_SEM_TIMEOUT    31 /* mutex semaphore-wait timeout (def=0,none) */
  1618. #define PACK_BUFFER_SIZE     32 /* pack buffer size (def=0, min autosize) */
  1619. #define REINDEX_BUFFER_SIZE  33 /* reindex buffer size (def=0, min autosize) */
  1620. #define REINDEX_PACK_PCT     34 /* reindex node pack % (default=100, max) */
  1621. #define TMP_PATH_PTR         35 /* temporary file path ptr (default=NULL) */
  1622. #define REINDEX_SKIP_TAG     36 /* index skip tag select (default=0, none) */
  1623. #define COMMIT_AT_EACH       37 /* commit each insert/update in pack (def=0) */
  1624. #define MEMO_BLOCKSIZE       38 /* memo block size (default=512 bytes) */
  1625. #define MEMO_EXTENSION       39 /* memo filename extension (default='DBT\0') */
  1626. #define MAX_DATAFILE_SIZE    40 /* max data size (default=0x7FEFFFFF=2095MB) */
  1627. #define MAX_INDEXFILE_SIZE   41 /* max index size (default=0x7FEFFFFF=2095MB)*/
  1628. #define ATOMIC_MODE          42 /* bit0=1 atomic next/prev key access (def=0)*/
  1629. #define CALLBACK_PTR         43 /* callback at reindex/pack (def=0, none) */
  1630.  
  1631. /* ************************************************************************
  1632.  *
  1633.  * Query/SetVectors vector IDs
  1634.  *
  1635.  * ************************************************************************/
  1636.  
  1637. #define VECTOR_CLOSE_FILE           2
  1638. #define VECTOR_CREATE_DIR           3
  1639. #define VECTOR_CREATE_FILE          4
  1640. #define VECTOR_CREATE_UNIQUE_FILE   5
  1641. #define VECTOR_DELETE_FILE          6
  1642. #define VECTOR_LENGTH_FILE          7
  1643. #define VECTOR_MOVE_FILE            8
  1644. #define VECTOR_OPEN_FILE            9
  1645. #define VECTOR_READ_FILE           10
  1646. #define VECTOR_SEEK_FILE           11
  1647. #define VECTOR_UPDATE_DIR_ENTRY    12
  1648. #define VECTOR_WRITE_FILE          13
  1649. #define VECTOR_LOCK_FILE           14
  1650. #define VECTOR_IS_DRIVE_REMOTE     15
  1651. #define VECTOR_IS_FILE_REMOTE      16
  1652. #define VECTOR_EXITLIST            17
  1653. #define VECTOR_REMOVE_EXITLIST     18
  1654. #define VECTOR_FREE                19
  1655. #define VECTOR_GET_SORT_TABLE      20
  1656. #define VECTOR_GET_COUNTRY_INFO    21
  1657. #define VECTOR_GET_ERROR_CLASS     22
  1658. #define VECTOR_GET_MEMORY          23
  1659. #define VECTOR_GET_TMP_DIR         24
  1660. #define VECTOR_GET_VERSION         25
  1661. #define VECTOR_MALLOC              26
  1662. #define VECTOR_SET_HANDLE_COUNT    27
  1663. #define VECTOR_GET_TIME_INFO       28
  1664. #define VECTOR_UPPERCASE           29
  1665. #define VECTOR_CLOSE_MUTEX_SEM     30
  1666. #define VECTOR_CREATE_MUTEX_SEM    31
  1667. #define VECTOR_RELEASE_MUTEX_SEM   32
  1668. #define VECTOR_REQUEST_MUTEX_SEM   33
  1669.  
  1670.  
  1671. /* ************************************************************************
  1672.  *
  1673.  * Parameter pack structures, typedefs
  1674.  *
  1675.  * ************************************************************************/
  1676.  
  1677. /* AP, CP, CDP, etc., are suggested variable names */
  1678.  
  1679. typedef struct _ACCESSPACK {
  1680. ULONG func;
  1681. ULONG stat;
  1682. ULONG handle;         /* I, handle of Bullet file to access */
  1683. LONG  recNo;          /* IO, record number */
  1684. PVOID recPtr;         /* I, programmer's record buffer */
  1685. PVOID keyPtr;         /* I, programmer's key buffer */
  1686. PVOID nextPtr;        /* I, NULL if not xaction, else next AP in list */
  1687. } ACCESSPACK; /* AP */
  1688. typedef ACCESSPACK *PACCESSPACK;
  1689.  
  1690. /* CBP is the structure received by the callback procedure */
  1691. /* structure members are filled in by Bullet */
  1692.  
  1693. typedef struct _CALLBACKPACK {
  1694. ULONG sizeIs;         /* structure size (current 16 bytes) */
  1695. ULONG callMode;       /* 0=from reindex; 1=from DBF pack */
  1696. ULONG handle;         /* file handle */
  1697. ULONG data1;          /* for callMode=0/1: progress percent (1-99,0) */
  1698. } CALLBACKPACK; /* CBP */
  1699. typedef CALLBACKPACK *PCALLBACKPACK;
  1700.  
  1701. typedef struct _COPYPACK {
  1702. ULONG func;
  1703. ULONG stat;
  1704. ULONG handle;         /* I, handle of Bullet file to copy */
  1705. PSZ   filenamePtr;    /* I, filename to use (drv+path must exist if used) */
  1706. } COPYPACK; /* CP */
  1707. typedef COPYPACK *PCOPYPACK;
  1708.  
  1709. typedef struct _CREATEDATAPACK {
  1710. ULONG func;
  1711. ULONG stat;
  1712. PSZ   filenamePtr;    /* I, filename to use */
  1713. ULONG noFields;       /* I, 1 to 1024 */
  1714. PVOID fieldListPtr;   /* I, descriptor list, 1 per field */
  1715. ULONG fileID;         /* I, 0x03 for standard DBF, 0x8B if memo file also */
  1716. } CREATEDATAPACK; /* CDP */
  1717. typedef CREATEDATAPACK *PCREATEDATAPACK;
  1718.  
  1719. typedef struct _CREATEINDEXPACK {
  1720. ULONG func;
  1721. ULONG stat;
  1722. PSZ   filenamePtr;    /* I, filename to use */
  1723. PSZ   keyExpPtr;      /* I, e.g., "SUBSTR(LNAME,1,4)+SSN" */
  1724. LONG  xbLink;         /* I, opened data file handle this indexes */
  1725. ULONG sortFunction;   /* I, 1-9 system, 10-19 custom */
  1726. ULONG codePage;       /* I, 0=use process default */
  1727. ULONG countryCode;    /* I, 0=use process default */
  1728. PVOID collatePtr;     /* I, NULL=use cc/cp else use passed table for sort */
  1729. ULONG nodeSize;       /* I, 512, 1024, or 2048 */
  1730. } CREATEINDEXPACK; /* CIP */
  1731. typedef CREATEINDEXPACK *PCREATEINDEXPACK;
  1732.  
  1733. typedef struct _FIELDDESCTYPE {
  1734. BYTE  fieldName[11];  /* IO, upper A-Z and _; 1-10 chars, 0-filled, 0-term */
  1735. BYTE  fieldType;      /* IO, C,D,L,N, or M */
  1736. LONG  fieldDA;        /* x, offset within record (run-time storage option) */
  1737. BYTE  fieldLen;       /* IO, C=1-255,D=8,L=1,N=1-19,M=10 */
  1738. BYTE  fieldDC;        /* IO, fieldType=N then 0-15 else 0 */
  1739. USHORT altFieldLength;/* IO, 0 */
  1740. BYTE  filler[12];     /* I, 0 */
  1741. } FIELDDESCTYPE; /* nested in _DESCRIPTORPACK */
  1742. typedef FIELDDESCTYPE *PFIELDDESCTYPE;
  1743.  
  1744. typedef struct _DESCRIPTORPACK {
  1745. ULONG func;
  1746. ULONG stat;
  1747. ULONG handle;         /* I, handle of DBF file */
  1748. ULONG fieldNumber;    /* IO, first field is 1 */
  1749. ULONG fieldOffset;    /* O, offset of field within record (tag=offset 0) */
  1750. FIELDDESCTYPE FD;     /* IO FD.fieldName only, O for rest of FD */
  1751. } DESCRIPTORPACK; /* DP */
  1752. typedef DESCRIPTORPACK *PDESCRIPTORPACK;
  1753.  
  1754. typedef struct _DOSFILEPACK {
  1755. ULONG func;
  1756. ULONG stat;
  1757. PSZ   filenamePtr;    /* I, filename to use */
  1758. ULONG handle;         /* IO, handle of open file */
  1759. ULONG asMode;         /* I, access-sharing mode */
  1760. ULONG bytes;          /* IO, bytes to read, write, length of */
  1761. LONG  seekTo;         /* IO, seek to offset, current offset */
  1762. ULONG method;         /* I, seek method (0=start of file, 1=current, 2=end) */
  1763. PVOID bufferPtr;      /* I, buffer to read into or write from */
  1764. ULONG attr;           /* I, attribute to create file with */
  1765. PSZ   newNamePtr;     /* I, name to use on rename */
  1766. } DOSFILEPACK; /* DFP */
  1767. typedef DOSFILEPACK *PDOSFILEPACK;
  1768.  
  1769. typedef struct _EXITPACK {
  1770. ULONG func;
  1771. ULONG stat;
  1772. } EXITPACK; /* EP */
  1773. typedef EXITPACK *PEXITPACK;
  1774.  
  1775. typedef struct _HANDLEPACK {
  1776. ULONG func;
  1777. ULONG stat;
  1778. ULONG handle;         /* I, handle of Bullet file */
  1779. } HANDLEPACK; /* HP */
  1780. typedef HANDLEPACK *PHANDLEPACK;
  1781.  
  1782. typedef struct _INITPACK {
  1783. ULONG func;
  1784. ULONG stat;
  1785. ULONG JFTsize;        /* I, max opened files (20-1024+) */
  1786. ULONG versionDOS;     /* O, e.g., 230 for 2.30 */
  1787. ULONG versionBullet;  /* O, e.g., 2019 for 2.019 */
  1788. ULONG versionOS;      /* O, e.g., 4=OS/2 32-bit */
  1789. PVOID exitPtr;        /* O, function pointer to EXIT_XB routine */
  1790. } INITPACK; /* IP */
  1791. typedef INITPACK *PINITPACK;
  1792.  
  1793. typedef struct _LOCKPACK {
  1794. ULONG func;
  1795. ULONG stat;
  1796. ULONG handle;         /* I, handle of Bullet file to lock */
  1797. ULONG xlMode;         /* I, index lock mode (0=exclusive, 1=shared) */
  1798. ULONG dlMode;         /* I, data lock mode (0=exclusive, 1=shared) */
  1799. LONG  recStart;       /* I, if data, first record # to lock, or 0 for all */
  1800. ULONG recCount;       /* I, if data and recStart!=0, # records to lock */
  1801. PVOID nextPtr;        /* I, NULL if not xaction, else next LP in list */
  1802. } LOCKPACK; /* LP */
  1803. typedef LOCKPACK *PLOCKPACK;
  1804.  
  1805. typedef struct _MEMODATAPACK {
  1806. ULONG func;
  1807. ULONG stat;
  1808. ULONG dbfHandle;      /* I, handle of DBF file to which this memo file belongs */
  1809. ULONG memoBypass;     /* I, memo bypass function to do, if any */
  1810. PVOID memoPtr;        /* I, ptr to memo record buffer */
  1811. ULONG memoNo;         /* IO, memo record number (aka block number) */
  1812. ULONG memoOffset;     /* I, position within record to start read/update */
  1813. ULONG memoBytes;      /* IO, number of bytes to read/update */
  1814. } MEMODATAPACK; /* MDP */
  1815. typedef MEMODATAPACK *PMEMODATAPACK;
  1816.  
  1817. typedef struct _MEMORYPACK {
  1818. ULONG func;
  1819. ULONG stat;
  1820. ULONG memory;         /* O, not used in OS/2 */
  1821. } MEMORYPACK; /* MP */
  1822. typedef MEMORYPACK *PMEMORYPACK;
  1823.  
  1824. typedef struct _OPENPACK {
  1825. ULONG func;
  1826. ULONG stat;
  1827. ULONG handle;         /* O, handle of file opened */
  1828. PSZ   filenamePtr;    /* I, Bullet file to open */
  1829. ULONG asMode;         /* I, access-sharing-cache mode */
  1830. LONG  xbLink;         /* I, if index open, xbLink=handle of its opened DBF */
  1831. } OPENPACK; /* OP */
  1832. typedef OPENPACK *POPENPACK;
  1833.  
  1834. typedef struct _QUERYSETPACK {
  1835. ULONG func;
  1836. ULONG stat;
  1837. ULONG item;           /* I, Bullet sysvar item to get/set */
  1838. ULONG itemValue;      /* IO, current/new value */
  1839. } QUERYSETPACK; /* QSP */
  1840. typedef QUERYSETPACK *PQUERYSETPACK;
  1841.  
  1842. typedef struct _REMOTEPACK {
  1843. ULONG func;
  1844. ULONG stat;
  1845. ULONG handle;         /* I, handle of file, or if 0, use RP.drive */
  1846. ULONG drive;          /* I, drive (1=A,2=B,3=C,...0=current) to check */
  1847. ULONG isRemote;       /* O, =1 of handle/drive is remote, =0 if local */
  1848. ULONG flags;          /* O, 0 */
  1849. ULONG isShare;        /* O, 1 */
  1850. } REMOTEPACK; /* RP */
  1851. typedef REMOTEPACK *PREMOTEPACK;
  1852.  
  1853. typedef struct _STATDATAPACK {
  1854. ULONG func;
  1855. ULONG stat;
  1856. ULONG handle;         /* I, handle to check */
  1857. ULONG fileType;       /* O, bit0=1 data file */
  1858. ULONG flags;          /* O, bit0=1 dirty, bit1=1 full-lock, bit2=1 shared */
  1859. ULONG progress;       /* O, 0,1-99% pack progress */
  1860. PVOID morePtr;        /* O, 0 */
  1861. ULONG fields;         /* O, fields per record */
  1862. ULONG asMode;         /* O, access-sharing-cache mode */
  1863. PSZ   filenamePtr;    /* O, filename used in open */
  1864. ULONG fileID;         /* O, first byte of DBF file */
  1865. ULONG lastUpdate;     /* O, high word=year,low byte=day, high byte=month */
  1866. ULONG records;        /* O, data records (including "deleted") */
  1867. ULONG recordLength;   /* O, record length */
  1868. ULONG xactionFlag;    /* O, 0 */
  1869. ULONG encryptFlag;    /* O, 0 */
  1870. PVOID herePtr;        /* O, this file's control address */
  1871. ULONG memoHandle;     /* O, handle of open memo file (0 if none) */
  1872. ULONG memoBlockSize;  /* O, memo file block size */
  1873. ULONG memoFlags;      /* O, bit0=1 dirty */
  1874. ULONG memoLastRecord; /* O, last accessed memo record (0 if none) */
  1875. ULONG memoLastSize;   /* O, size of last accessed memo record (in bytes, +8) */
  1876. ULONG lockCount;      /* O, number of full-locks in force */
  1877. } STATDATAPACK; /* SDP */
  1878. typedef STATDATAPACK *PSTATDATAPACK;
  1879.  
  1880. typedef struct _STATHANDLEPACK {
  1881. ULONG func;
  1882. ULONG stat;
  1883. ULONG handle;         /* I, handle to check */
  1884. LONG  ID;             /* O, bit0=1 data file, bit0=1 index file */
  1885. } STATHANDLEPACK; /* SHP */
  1886. typedef STATHANDLEPACK *PSTATHANDLEPACK;
  1887.  
  1888. typedef struct _STATINDEXPACK {
  1889. ULONG func;
  1890. ULONG stat;
  1891. ULONG handle;         /* I, handle to check */
  1892. ULONG fileType;       /* O, bit0=0 index file */
  1893. ULONG flags;          /* O, bit0=1 dirty, bit1=1 full-lock, bit2=1 shared */
  1894. ULONG progress;       /* O, 0,1-99% reindex progress */
  1895. PVOID morePtr;        /* O, 0 */
  1896. ULONG xbLink;         /* O, XB file link handle */
  1897. ULONG asMode;         /* O, access-sharing-cache mode */
  1898. PSZ   filenamePtr;    /* O, pointer to filename used in open */
  1899. ULONG fileID;         /* O, "31ch" */
  1900. PSZ   keyExpPtr;      /* O, pointer to key expression */
  1901. ULONG keys;           /* O, keys in file */
  1902. ULONG keyLength;      /* O, key length */
  1903. ULONG keyRecNo;       /* O, record number of current key */
  1904. PVOID keyPtr;         /* O, ptr to current key value (valid to keyLength) */
  1905. PVOID herePtr;        /* O, this file's control address */
  1906. ULONG codePage;       /* O, code page at create time */
  1907. ULONG countryCode;    /* O, country code at create time */
  1908. PVOID CTptr;          /* O, collate table ptr, NULL=no collate table present */
  1909. ULONG nodeSize;       /* O, node size */
  1910. ULONG sortFunction;   /* O, sort function ID */
  1911. ULONG lockCount;      /* O, number of full-locks in force */
  1912. } STATINDEXPACK; /* SIP */
  1913. typedef STATINDEXPACK *PSTATINDEXPACK;
  1914.  
  1915. typedef struct _XERRORPACK {
  1916. ULONG func;
  1917. ULONG stat;           /* I, error to check */
  1918. ULONG errClass;       /* O, class of error */
  1919. ULONG action;         /* O, action recommended for error */
  1920. ULONG location;       /* O, location of error */
  1921. } XERRORPACK; /* XEP */
  1922. typedef XERRORPACK *PXERRORPACK;
  1923.  
  1924.  
  1925. /* ************************************************************************
  1926.  *
  1927.  * Error codes
  1928.  *
  1929.  * ************************************************************************/
  1930.  
  1931. #define EXB_NOT_ENOUGH_MEMORY   8  /* cannot get memory requested */
  1932. #define EXB_INVALID_DRIVE       15 /* not a valid drive letter */
  1933. #define EXB_UNEXPECTED_EOF      38 /* unexpect EOF (bytes read != bytes asked) */
  1934. #define EXB_DISK_FULL           39 /* disk full on WriteFile */
  1935. #define EXB_FILE_EXISTS         80 /* cannot create file since it already exists */
  1936. #define EXB_SEM_OWNER_DIED      105 /* in place of Win32 error 80h (mutex) */
  1937. #define EXB_TIMEOUT             640 /* in place of Win32 error 102h (mutex) */
  1938.  
  1939. /* Other operating system errors are as returned by OS itself */
  1940.  
  1941. /* System/general error codes */
  1942.  
  1943. #define EXB_OR_WITH_FAULTS      8192 /* 8192+1 to +4, close-type errors */
  1944.  
  1945.                                      /* ERR_216501/6 are for Bullet/x only */
  1946. #define EXB_216501              8251 /* INT21/6501h not supported by DOS extender */
  1947.                                      /* (do not use default cc/cp) */
  1948. #define EXB_216506              8256 /* INT21/6506h not supported by DOS extender */
  1949.                                      /* (provide a custom collate table) */
  1950.  
  1951. #define EXB_ILLEGAL_CMD         8300 /* function not allowed */
  1952. #define EXB_OLD_DOS             8301 /* OS version < MIN_DOS_NEEDED */
  1953. #define EXB_NOT_INITIALIZED     8302 /* init not active, must do INIT_XB */
  1954. #define EXB_ALREADY_INITIALIZED 8303 /* init already active, must do EXIT_XB */
  1955. #define EXB_TOO_MANY_HANDLES    8304 /* more than 1024 opens requested */
  1956. #define EXB_SYSTEM_HANDLE       8305 /* Bullet won't use or close handles 0-2 */
  1957. #define EXB_FILE_NOT_OPEN       8306 /* file not open (not Bullet handle, including xbLink) */
  1958. #define EXB_FILE_IS_DIRTY       8307 /* tried to reload header but current still dirty */
  1959. #define EXB_BAD_FILETYPE        8308 /* tried key op on non-key file, data op on non... */
  1960. #define EXB_TOO_MANY_PACKS      8309 /* too many INSERT,UPDATE,REINDEX,LOCK_XB packs */
  1961. #define EXB_NULL_RECPTR         8310 /* null record pointer passed to Bullet */
  1962. #define EXB_NULL_KEYPTR         8311 /* null key pointer passed to Bullet */
  1963. #define EXB_NULL_MEMOPTR        8312 /* null memo pointer passed to Bullet */
  1964. #define EXB_EXPIRED             8313 /* evaluation time period has expired */
  1965. #define EXB_BAD_INDEX           8314 /* Query/SetSysVars index beyond last one */
  1966. #define EXB_RO_INDEX            8315 /* SetSysVar index item is read-only */
  1967. #define EXB_FILE_BOUNDS         8316 /* file size > 4GB, or > system var sets */
  1968. #define EXB_FORCE_ROLLBACK      8397 /* rollback test completed (internal use) */
  1969. #define EXB_INVALID_DLL         8398 /* DLL seems to be invalid, 8399 same */
  1970.  
  1971. /* Multi-access error codes */
  1972.  
  1973. #define EXB_BAD_LOCK_MODE       8401 /* lock mode (LP) not valid */
  1974. #define EXB_NOTHING_TO_RELOCK   8402 /* cannot relock without existing full-lock */
  1975. #define EXB_SHARED_LOCK_ON      8403 /* write access needed but lock is shared (flush on backup) */
  1976.  
  1977. /* Index error codes */
  1978.  
  1979. #define EXB_KEY_NOT_FOUND       8501 /* exact match of key not found */
  1980. #define EXB_KEY_EXISTS          8502 /* key exists already and dups not allowed */
  1981. #define EXB_END_OF_FILE         8503 /* already at last index order */
  1982. #define EXB_TOP_OF_FILE         8504 /* already at first index order */
  1983. #define EXB_EMPTY_FILE          8505 /* nothing to do since no keys */
  1984. #define EXB_CANNOT_GET_LAST     8506 /* cannot locate last key */
  1985. #define EXB_BAD_INDEX_STACK     8507 /* index file is corrupt */
  1986. #define EXB_BAD_INDEX_READ0     8508 /* index file is corrupt */
  1987. #define EXB_BAD_INDEX_WRITE0    8509 /* index file is corrupt */
  1988.  
  1989. #define EXB_OLD_INDEX           8521 /* old index, run through ReindexOld to update */
  1990. #define EXB_UNKNOWN_INDEX       8522 /* not a Bullet index file */
  1991. #define EXB_KEY_TOO_LONG        8523 /* keylength > 62 (or 64 if unique), or is 0 */
  1992.  
  1993. #define EXB_PARSER_NULL         8531 /* parser function pointer is NULL */
  1994. #define EXB_BUILDER_NULL        8532 /* build key function pointer is NULL */
  1995. #define EXB_BAD_SORT_FUNC       8533 /* CIP.sortFunction not valid */
  1996. #define EXB_BAD_NODE_SIZE       8534 /* CIP.nodeSize is not 512, 1024, or 2048 */
  1997. #define EXB_FILENAME_TOO_LONG   8535 /* CIP.filenamePtr->pathname > max path length */
  1998.  
  1999. #define EXB_KEYX_NULL           8541 /* expression is effectively NULL */
  2000. #define EXB_KEYX_TOO_LONG       8542 /* CIP.keyExpPtr->expression > 159 */
  2001. #define EXB_KEYX_SYM_TOO_LONG   8543 /* fieldname/funcname in expression > 10 chars */
  2002. #define EXB_KEYX_SYM_UNKNOWN    8544 /* fieldname/funcname in expression unknown */
  2003. #define EXB_KEYX_TOO_MANY_SYMS  8545 /* too many symbols/fields used in expression */
  2004. #define EXB_KEYX_BAD_SUBSTR     8546 /* invalid SUBSTR() operand in expression */
  2005. #define EXB_KEYX_BAD_SUBSTR_SZ  8547 /* SUBSTR() exceeds field's size */
  2006. #define EXB_KEYX_BAD_FORM       8548 /* didn't match expected symbol in expression */
  2007.  
  2008. #define EXB_NO_READS_FOR_RUN    8551 /* unlikely, use different reindex buffer size */
  2009. #define EXB_TOO_MANY_RUNS       8552 /* unlikely, too many runs (64K or more runs) */
  2010. #define EXB_TOO_MANY_RUNS_FOR_BUFFER 8553 /* unlikely, too many runs for run buffer */
  2011. #define EXB_TOO_MANY_DUPLICATES 8554 /* more than 64K "identical" keys */
  2012.  
  2013. #define EXB_INSERT_RECNO_BAD    8561 /* AP.recNo cannot be > 0 if inserting */
  2014. #define EXB_PREV_APPEND_EMPTY   8562 /* no prev append for insert yet AP.recNo==80000000h */
  2015. #define EXB_PREV_APPEND_MISMATCH 8563 /* prev append's xbLink does not match this */
  2016. #define EXB_INSERT_KBO_FAILED   8564 /* could not back out key at INSERT_XB */
  2017. #define EXB_INSERT_DBO_FAILED   8565 /* could not back out data records at INSERT_XB */
  2018.  
  2019. #define WRN_NOTHING_TO_UPDATE   8571 /* all AP.recNo=0 at UPDATE_XB */
  2020. #define EXB_INTERNAL_UPDATE     8572 /* internal error UPDATE_XB, not in hdl/rec# list */
  2021.  
  2022. #define EXB_FAILED_DATA_RESTORE 8573 /* could not restore original data record (*) */
  2023. #define EXB_FAILED_KEY_DELETE   8574 /* could not remove new key (*) */
  2024. #define EXB_FAILED_KEY_RESTORE  8575 /* could not restore original key(*) */
  2025. /* *original error, which forced a back-out, has been replaced by this error */
  2026. /* this error is always returned in the first AP.stat (-1 on data, 1 on index) */
  2027.  
  2028. /* Data error codes */
  2029.  
  2030. #define EXB_EXT_XBLINK          8601 /* xbLink handle is not internal DBF (is -1) */
  2031. #define EXB_FIELDNAME_TOO_LONG  8602 /* fieldname is > 10 characters */
  2032. #define EXB_RECORD_TOO_LONG     8603 /* record length is > 64K */
  2033. #define EXB_FIELD_NOT_FOUND     8604 /* fieldname not found in descriptor info */
  2034. #define EXB_BAD_FIELD_COUNT     8605 /* fields <= 0 or >= MAX_FIELDS (Init,Open) */
  2035.                                      /* and also GetDescriptor by field number */
  2036. #define EXB_BAD_HEADER          8606 /* bad header (reclen=0, etc., from LocateTo, Flush) */
  2037. #define EXB_BUFFER_TOO_SMALL    8607 /* buffer too small (pack buffer < reclen in pack) */
  2038. #define EXB_INTERNAL_PACK       8608 /* internal error in PackRecords */
  2039. #define EXB_BAD_RECNO           8609 /* record number=0 or > records in data file hdr */
  2040.                                      /* or Pack on empty data file */
  2041. #define WRN_RECORD_TAGGED       8610 /* record's tag field matches skip tag */
  2042.  
  2043. /* Memo error codes */
  2044.  
  2045. #define WRN_CANNOT_OPEN_MEMO    8701 /* DBF says memo file but memo open fails */
  2046. #define EXB_MEMO_NOT_OPEN       8702 /* no open memo file for operation */
  2047. #define EXB_BAD_BLOCKSIZE       8703 /* memo blocksize must be at least 24 bytes */
  2048. #define EXB_MEMO_DELETED        8704 /* memo is deleted */
  2049. #define EXB_MEMO_PAST_END       8705 /* memo data requested is past end of record */
  2050. #define EXB_BAD_MEMONO          8706 /* memo number is not valid */
  2051. #define EXB_MEMO_IN_USE         8707 /* memo add encountered likely corrupt memo file */
  2052. #define EXB_BAD_AVAIL_LINK      8708 /* memo avail link cannot be valid (is 0) */
  2053. #define EXB_MEMO_ZERO_SIZE      8709 /* memo data has no size */
  2054. #define EXB_MEMO_IS_SMALLER     8710 /* memo attempt to shrink but already <= size */
  2055.  
  2056. #endif /* ifndef __BULLET_H */
  2057.  
  2058.  
  2059. ΓòÉΓòÉΓòÉ 9. Bullet Functions ΓòÉΓòÉΓòÉ
  2060.  
  2061. System level                    Advanced system-level 
  2062.  
  2063.  INIT_XB                        QUERY_SYSVARS_XB 
  2064.  EXIT_XB                        SET_SYSVARS_XB 
  2065.  MEMORY_XB                      SET_DVMON_XB 
  2066.  BACKUP_FILE_XB                 QUERY_VECTORS_XB 
  2067.  STAT_HANDLE_XB                 SET_VECTORS_XB 
  2068.  GET_ERROR_CLASS_XB 
  2069.  
  2070.  Data low-level                 Data mid-level                     Memo 
  2071.                                                                    mid-level 
  2072.  
  2073.  CREATE_DATA_XB                 GET_DESCRIPTOR_XB 
  2074.                                                                    GET_MEMO_SIZE_XB 
  2075.  OPEN_DATA_XB                   GET_RECORD_XB                      GET_MEMO_XB 
  2076.  CLOSE_DATA_XB                  ADD_RECORD_XB                      ADD_MEMO_XB 
  2077.  STAT_DATA_XB                   UPDATE_RECORD_XB 
  2078.                                                                    UPDATE_MEMO_XB 
  2079.  READ_DATA_HEADER_XB            DELETE_RECORD_XB 
  2080.                                                                    DELETE_MEMO_XB 
  2081.  FLUSH_DATA_HEADER_XB           UNDELETE_RECORD_XB 
  2082.                                                                    MEMO_BYPASS_XB 
  2083.  COPY_DATA_HEADER_XB            DEBUMP_RECORD_XB 
  2084.  ZAP_DATA_HEADER_XB             PACK_RECORDS_XB 
  2085.  
  2086.  Index low-level                Index mid-level                    Index 
  2087.                                                                    high-level 
  2088.  
  2089.  CREATE_INDEX_XB                FIRST_KEY_XB                       GET_FIRST_XB 
  2090.  OPEN_INDEX_XB                  EQUAL_KEY_XB                       GET_EQUAL_XB 
  2091.  CLOSE_INDEX                    EQUAL_OR_GREATER_KEY_XB 
  2092.                                                                    GET_EQUAL_OR_GREATER_XB 
  2093.  STAT_INDEX_XB                  EQUAL_OR_LESSER_KEY_XB 
  2094.                                                                    GET_EQUAL_OR_LESSER_XB 
  2095.  READ_INDEX_HEADER_XB           NEXT_KEY_XB                        GET_NEXT_XB 
  2096.  FLUSH_INDEX_HEADER_XB          PREV_KEY_XB                        GET_PREV_XB 
  2097.  COPY_INDEX_HEADER_XB           LAST_KEY_XB                        GET_LAST_XB 
  2098.  ZAP_INDEX_HEADER_XB            STORE_KEY_XB                       INSERT_XB 
  2099.                                 DELETE_KEY_XB                      UPDATE_XB 
  2100.                                 BUILD_KEY_XB                       REINDEX_XB 
  2101.                                 GET_CURRENT_KEY_XB 
  2102.                                 GET_KEY_FOR_RECORD_XB 
  2103.  
  2104.  Network level                  CP level 
  2105.  
  2106.  LOCK_XB                        DELETE_FILE_DOS 
  2107.  UNLOCK_XB                      RENAME_FILE_DOS 
  2108.  LOCK_INDEX_XB                  CREATE_FILE_DOS 
  2109.  UNLOCK_INDEX_XB                OPEN_FILE_DOS 
  2110.  LOCK_DATA_XB                   SEEK_FILE_DOS 
  2111.  UNLOCK_DATA_XB                 READ_FILE_DOS 
  2112.  CHECK_REMOTE_XB                WRITE_FILE_DOS 
  2113.  RELOCK_XB                      CLOSE_FILE_DOS 
  2114.  RELOCK_INDEX_XB                ACCESS_FILE_DOS 
  2115.  RELOCK_DATA_XB                 EXPAND_FILE_DOS 
  2116.                                 MAKE_DIR_DOS 
  2117.                                 COMMIT_FILE_DOS 
  2118.  
  2119.  
  2120. ΓòÉΓòÉΓòÉ 9.1. INIT_XB ΓòÉΓòÉΓòÉ
  2121.  
  2122. Pack: INITPACK                 Source Example 
  2123.  
  2124.      IN               OUT
  2125.    IP.func          IP.stat
  2126.    IP.JFTsize       IP.versionDOS
  2127.                     IP.versionBullet
  2128.                     IP.versionOS
  2129.                     IP.exitPtr
  2130.  
  2131.  This must be the first routine called (except for SET_VECTORS_XB).  If it has 
  2132.  already been called the system variables are restored to their defaults, and 
  2133.  an error is returned.  Otherwise, the entire Bullet system is initialized, and 
  2134.  EXIT_XB is registered with the OS ExitList handler (DosExitList). 
  2135.  
  2136.  For more than the default open files (generally 20), set IP.JFTsize to the 
  2137.  total number of concurrently open files you need.  Depending on your version, 
  2138.  Bullet manages up to 1024 Bullet files per process (total data and index; memo 
  2139.  files are not counted against this total).  Setting this less than 20 does 
  2140.  nothing.  This number is for Bullet files, your files, pipes -- anything using 
  2141.  a handle.  If you need to account for handles that you are managing, you 
  2142.  should add those to IP.JFTsize.  For example, if you need 10 data files, each 
  2143.  with a memo file, and 2 index files per data file, that is 40 total Bullet 
  2144.  files.  If you need to use 15 other handles, for whatever use, add that number 
  2145.  to the 40 Bullet files, for a total setting of 55.  The OS also uses 3 handles 
  2146.  for itself, so, for all these, IP.JFTsize=58 would be the minimum.  You can 
  2147.  set it higher, but unused handles are wasted handles. In addition, if the 
  2148.  current process has fewer total handles available than the number you 
  2149.  specified in IP.JFTsize, Bullet sets the total available handles to IP.JFTsize 
  2150.  (as the absolute number of handles required).  If the current process already 
  2151.  has more total handles than IP.JFTsize, no action is taken. 
  2152.  
  2153.  On return (where no error occurred), the operating system version is in 
  2154.  IP.versionDOS (*100) and the Bullet version (*1000) in IP.versionBullet. 
  2155.  IP.versionOS return is based on the following table: 
  2156.  
  2157.       Bullet Platform   IP.versionOS
  2158.          MS-DOS 16-bit      0
  2159.           Win3x 16-bit      1
  2160.          DOSX32 32-bit      3
  2161.            OS/2 32-bit      4
  2162.           Win32 32-bit      5
  2163.  
  2164.  IP.exitPtr returns with the function pointer to the EXIT_XB routine. This 
  2165.  function pointer is redundant unless specifically mentioned as being required 
  2166.  for your platform.  It is not needed in OS/2, but is useful for other 
  2167.  platforms, for example, for use with atexit(), part of C's standard library. 
  2168.  
  2169.  Win32s, as run in Windows 3.1, returns IP.versionDOS equal to its level.  For 
  2170.  example, if running Win31, using win32s version 1.25, IP.versionDOS returns as 
  2171.  125, not 310 as might be expected. 
  2172.  
  2173.  Note:  References under OUT using *AP.keyPtr or similar (note then *) are used 
  2174.  throughout this manual and indicate that Bullet updates the contents at 
  2175.  AP.keyPtr with data (i.e., Bullet filled the buffer). 
  2176.  
  2177.  
  2178. ΓòÉΓòÉΓòÉ 9.2. EXIT_XB ΓòÉΓòÉΓòÉ
  2179.  
  2180. Pack: EXITPACK                 Source Example 
  2181.  
  2182.      IN               OUT
  2183.    EP.func          EP.stat
  2184.  
  2185.  Call EXIT_XB before ending your program to release any remaining resources 
  2186.  back to the OS.  Open files should be closed by using CLOSE_DATA_XB and 
  2187.  CLOSE_INDEX_XB. EXIT_XB closes any Bullet files that are still open. 
  2188.  
  2189.  This routine is registered with the operating system and so is called 
  2190.  automatically when your program terminates in OS/2, or with the C startup code 
  2191.  if atexit() is used. 
  2192.  
  2193.  
  2194. ΓòÉΓòÉΓòÉ 9.3. ATEXIT_XB ΓòÉΓòÉΓòÉ
  2195.  
  2196. This routine is obsolete.  In OS/2, the EXIT_XB shutdown procedure is 
  2197. registered with the operating system.  For those systems that do not offer this 
  2198. feature in the OS, the compiler run-time routine atexit() is used immediately 
  2199. after calling INIT_XB, using IP.exitPtr as the function pointer for atexit(). 
  2200.  
  2201.  
  2202. ΓòÉΓòÉΓòÉ 9.4. MEMORY_XB ΓòÉΓòÉΓòÉ
  2203.  
  2204. Pack: MEMORYPACK               Source Example 
  2205.  
  2206.      IN               OUT
  2207.    MP.func          MP.stat
  2208.                     MP.memory
  2209.  
  2210.  MP.memory returns with the number of bytes in the private memory arena 
  2211.  allocatable by the process according to DosQuerySysInfo for QSV_MAXPRMEM, or 
  2212.  as provided by the OS.  It is for informational use only. 
  2213.  
  2214.  Note:  This routine is not mutex-protected. 
  2215.  
  2216.  
  2217. ΓòÉΓòÉΓòÉ 9.5. BACKUP_FILE_XB ΓòÉΓòÉΓòÉ
  2218.  
  2219. Pack: COPYPACK                 Source Example 
  2220.  
  2221.      IN               OUT
  2222.    CP.func          CP.stat
  2223.    CP.handle
  2224.    CP.filenamePtr
  2225.  
  2226.  Copy an open BULLET index file or data/memo files.  BULLET repacks and 
  2227.  reindexes files in place, requiring less disk space to perform the function. 
  2228.  This routine allows a file to be safely copied for a possible later restore. 
  2229.  
  2230.  This function is recommended prior to packing a data file with 
  2231.  PACK_RECORDS_XB.  For index files, COPY_INDEX_HEADER_XB is sufficient since 
  2232.  index files are easily recreated so long as you have the data file along with 
  2233.  the index file header. 
  2234.  
  2235.  A full-lock should be in force before copying.  A shared lock may be used. 
  2236.  
  2237.  If CP.handle belongs to a DBF data file, and if a memo file is attached, the 
  2238.  memo file backup name is as CP.filenamePtr, the backup DBF pathname, but the 
  2239.  extension is always set to "._BT".  For example, if CP.handle is for a DBF 
  2240.  that has a DBT memo file attached, then the current state of the DBF file is 
  2241.  copied to CP.filenamePtr, say, "\CURRBACK\ACCT.DBF", and, in this case, the 
  2242.  DBT memo file is copied to "\CURRBACK\ACCT._BT".  The name of the original 
  2243.  DBF/DBT does not matter.  If MEMO_EXTENSION of SET_SYSVARS_XB has changed the 
  2244.  default, then that extension is used on the memo copy, with '_' replacing its 
  2245.  first character. 
  2246.  
  2247.  To prevent the backing up of a DBT memo file when backing up a DBF data file, 
  2248.  set CP.handle = -CP.handle (i.e., negative CP.handle).  This way, the DBT memo 
  2249.  file is not copied.  To backup only a DBT file, close the DBF and copy the DBT 
  2250.  by some other means. 
  2251.  
  2252.  
  2253. ΓòÉΓòÉΓòÉ 9.6. STAT_HANDLE_XB ΓòÉΓòÉΓòÉ
  2254.  
  2255. Pack: STATHANDLEPACK           Source Example 
  2256.  
  2257.      IN               OUT
  2258.    SHP.func         SHP.stat
  2259.    SHP.handle       SHP.ID
  2260.  
  2261.  Get information on a file handle number to determine if it is a BULLET file, 
  2262.  and if so, its type:  index or data. 
  2263.  
  2264.       SHP.ID   File type
  2265.          0     index, IX3  use STAT_INDEX_XB for file stats
  2266.          1     data, DBF   use STAT_DATA_XB for file stats
  2267.         -1     unknown
  2268.  
  2269.  Only bit0 of SHP.ID is significant if not -1.  So, if bit0=0 then the handle 
  2270.  belongs to an index file.  If bit0=1 then it's a data file. 
  2271.  
  2272.  Memo file handles return as unknown.  A DBF file's memo file handle is stored 
  2273.  in the DBF file's data area, and is returned by STAT_DATA_XB in 
  2274.  SDP.memoHandle. 
  2275.  
  2276.  Note:  This routine is not mutex-protected. 
  2277.  
  2278.  
  2279. ΓòÉΓòÉΓòÉ 9.7. GET_ERROR_CLASS_XB ΓòÉΓòÉΓòÉ
  2280.  
  2281. Pack: XERRORPACK               Source Example 
  2282.  
  2283.      IN               OUT
  2284.    XEP.func         XEP.errClass
  2285.    XEP.stat         XEP.action
  2286.                     XEP.location
  2287.  
  2288.  Get the extended error information for the code passed in XEP.stat. This 
  2289.  information includes the error classification, recommended action, and origin 
  2290.  of the error. 
  2291.  
  2292.  Any system error code can be specified, not necessarily the one that last 
  2293.  occurred.  If a return code is not a BULLET code, then it is a system error 
  2294.  code (from the CP, DosXXX routines). 
  2295.  
  2296.  The ERRCLASS, ERRACT, and ERRLOC items below are OS/2 values, names and 
  2297.  descriptions for DosErrClass(). 
  2298.  
  2299.   Error Classification
  2300.  
  2301.     Value   Name                Description
  2302.       1    ERRCLASS_OUTRES     Out of resources
  2303.       2    ERRCLASS_TEMPSIT    Temporary situation
  2304.       3    ERRCLASS_AUTH       Authorization failed
  2305.       4    ERRCLASS_INTRN      Internal error
  2306.       5    ERRCLASS_HRDFAIL    Device hardware failure
  2307.       6    ERRCLASS_SYSFAIL    System failure
  2308.       7    ERRCLASS_APPEAR     Probably application error
  2309.       8    ERRCLASS_NOTFND     Item not located
  2310.       9    ERRCLASS_BADFMT     Bad format for function or data
  2311.      10    ERRCLASS_LOCKED     Resource or data locked
  2312.      11    ERRCLASS_MEDIA      Incorrect media, CRC error
  2313.      12    ERRCLASS_ALREADY    Action already taken or done, or resource already exists
  2314.      13    ERRCLASS_UNK        Unclassified
  2315.      14    ERRCLASS_CANT       Cannot perform requested action
  2316.      15    ERRCLASS_TIME       Timeout
  2317.  
  2318.  
  2319.   Recommended Action
  2320.  
  2321.     Value   Name                Description
  2322.       1    ERRACT_RETRY        Retry immediately
  2323.       2    ERRACT_DLYRET       Delay and retry
  2324.       3    ERRACT_USER         Bad user input - get new values
  2325.       4    ERRACT_ABORT        Terminate in an orderly manner
  2326.       5    ERRACT_PANIC        Terminate immediately
  2327.       6    ERRACT_IGNORE       Ignore error
  2328.       7    ERRACT_INTRET       Retry after user intervention
  2329.  
  2330.  
  2331.   Origin
  2332.  
  2333.     Value   Name                Description
  2334.       1    ERRLOC_UNK          Unknown
  2335.       2    ERRLOC_DISK         Disk
  2336.       3    ERRLOC_NET          Network
  2337.       4    ERRLOC_SERDEV       Serial device
  2338.       5    ERRLOC_MEM          Memory
  2339.  
  2340.  Note:  This routine is not mutex-protected. 
  2341.  
  2342.  
  2343. ΓòÉΓòÉΓòÉ 9.8. QUERY_SYSVARS_XB ΓòÉΓòÉΓòÉ
  2344.  
  2345. Pack: QUERYSETPACK             Source Example 
  2346.  
  2347.      IN               OUT
  2348.    QSP.func         QSP.stat
  2349.    QSP.item         QSP.itemValue
  2350.  
  2351.  Query a BULLET system variable. 
  2352.  
  2353.  To get the function pointers to the sort-compare functions, use: 
  2354.  
  2355.    QSP.item           FuncPtr To
  2356.    ASCII_SORT        ASCII sort compare
  2357.    NLS_SORT          NLS sort compare
  2358.    S16_SORT          16-bit signed integer
  2359.    U16_SORT          16-bit unsigned integer
  2360.    S32_SORT          32-bit signed integer
  2361.    U32_SORT          32-bit unsigned integer
  2362.  
  2363.  All intrinsic sort compares (1-6) point to the same function. They cannot be 
  2364.  called except by BULLET itself.  The integer compare routines are based on 
  2365.  Intel byte order.  For Motorola byte order, ASCII sort can be used for 
  2366.  all-positive numbers, otherwise a custom sort-compare should be used. 
  2367.  
  2368.     QSP.item          FuncPtr To
  2369.      10-19           Custom sort-compare functions
  2370.  
  2371.  Before creating or opening an index file with a custom sort-compare function 
  2372.  (which is specified during CREATE_INDEX_XB), that function's address must 
  2373.  first be sent to BULLET using SET_SYSVARS_XB. Thereafter, that function must 
  2374.  be available whenever that index file is accessed.  See Custom Sort-Compare 
  2375.  Function for creating custom sort-compare functions. 
  2376.  
  2377.  To get the function pointers to the build key and expression parser routines, 
  2378.  use: 
  2379.  
  2380.     QSP.item          FuncPtr To
  2381.    BUILD_KEY_FUNC    Build key routine
  2382.    PARSER_FUNC       Key expression parser routine
  2383.  
  2384.  Before creating or opening an index file with a custom build key or expression 
  2385.  parser routine (which is specified at any time, but must be used in a 
  2386.  consistent manner), that routine's address must first be sent to BULLET using 
  2387.  SET_SYSVARS_XB.  Thereafter, that routine should be available since it may be 
  2388.  required again.  See Custom Build-Key Routine for creating a custom build-key 
  2389.  routine and Custom Expression Parser Routine for creating a custom key 
  2390.  expression parser. 
  2391.  
  2392.  To get the BULLET system variables' values, use: 
  2393.  
  2394.     QSP.item             Value To
  2395.    26 (read-only)        low-word: number of xb$Malloc(), high-word: number of xb$Free()
  2396.    27 (read-only)        Max instances (2, 32, 999)
  2397.    28 (read-only)        Max files (100, 250, 1024)
  2398.    29 (read-only)        Handle of Bullet's mutex semaphore
  2399.  
  2400.    LOCK_TIMEOUT          Lock file bytes timeout, in milliseconds (default=0)
  2401.    MUTEX_SEM_TIMEOUT     Mutex semaphore request timeout, in milliseconds (default=0)
  2402.    PACK_BUFFER_SIZE      Pack buffer size, in bytes (default=0: autosize)
  2403.    REINDEX_BUFFER_SIZE   Reindex buffer size, in bytes (default=0: autosize)
  2404.    REINDEX_PACK_PCT      Reindex node pack percentage, 50-100% (default=100)
  2405.    TMP_PATH_PTR          Temporary file path pointer (default=NULL, where TMP= used, then .\)
  2406.    REINDEX_SKIP_TAG      Reindex tag field character to skip (default=0, no skip)
  2407.    COMMIT_AT_EACH        Commit each individual file during INSERT/UPDATE_XB (default=0, defer until flush)
  2408.    MEMO_BLOCKSIZE        Memo file block size (default=512 bytes; minimum is 24 bytes)
  2409.    MEMO_EXTENSION        Memo file extension (default is "DBT\0")
  2410.    MAX_DATAFILE_SIZE     Max data file size-1 (default=2047MB, absolute max is 4095MB)
  2411.    MAX_INDEXFILE_SIZE    Max index file size-1 (default=2047MB, absolute max is 4095MB)
  2412.    ATOMIC_MODE           Atomic mode (bit0=1 then atomic Next and Prev access, default=0)
  2413.    CALLBACK_PTR          Callback routine at reindex/pack (def=0, none)
  2414.  
  2415.  The timeout values determine if the kernel should wait for a pre-determined 
  2416.  time before returning an error if the resource cannot be obtained.  The lock 
  2417.  timeout specifies how long to wait for a lock to be obtained in case some 
  2418.  other process has a lock on the same resource.  The mutex timeout specifies 
  2419.  how long to wait for access to BULLET in case some other thread in this 
  2420.  process is in BULLET.  Multiple processes can access BULLET at the same time, 
  2421.  but only one thread in each process can be inside BULLET at any one time. 
  2422.  
  2423.  The buffer sizes, when 0, default to a minimum reasonable size.  Performance 
  2424.  is acceptable at these sizes.  For best performance, provide as much real 
  2425.  memory as possible, up to 512KB.  Larger buffers can be used. 
  2426.  
  2427.  The reindex node pack percentage determines how many keys are packed on a 
  2428.  node.  100% forces as many keys as possible, minus 1. 
  2429.  
  2430.  If the temporary file path pointer is NULL (the default), then the TMP= 
  2431.  environment variable is used to locate any temporary files created by BULLET, 
  2432.  or if that is not found, then the current directory is used.  The pointer 
  2433.  supplied, if any, should be to a string containing an existing path (drive 
  2434.  should be included; a trailing '\' is optional, but recommended).  See 
  2435.  REINDEX_XB for size requirements. 
  2436.  
  2437.  The reindex skip tag character, if encountered in the DBF record's tag field 
  2438.  (the first byte of each record), causes the reindex routine to not place that 
  2439.  record's key value into the index file.  Also, BUILD_KEY_XB returns a warning 
  2440.  if the record supplied has a matching tag character. To disable skip tag 
  2441.  processing, set it to 0. 
  2442.  
  2443.  Inserts and Updates, by default, do not commit each file when that pack is 
  2444.  processed.  Instead, it is left to the programmer to issue a FLUSH_XB to 
  2445.  commit.  To force a commit after each pack file is processed, set CommitAtEach 
  2446.  to 1.  This is not one single commit, but a commit for each file in the pack, 
  2447.  after that file has been processed, but before the next file in the pack is. 
  2448.  This will not prevent a roll-back should it be needed. 
  2449.  
  2450.  A memo file can have at most 589,822 blocks.  At the default 512 bytes per 
  2451.  block, that equates to about 288MB.  If you need more memo space, increase the 
  2452.  block size.  The memo extension default is "DBT\0".  Generally, it's a good 
  2453.  idea to leave it at this. 
  2454.  
  2455.  The maximum file sizes are enforced when adding to or reading from DBF files, 
  2456.  and when inserting into or reading from index files.  The default is 2047 MB 
  2457.  (0x7FEFFFFF).  If your file system permits 4GB files, set the values to 4095 
  2458.  MB (0xFFEFFFFF). 
  2459.  
  2460.  The Atomic mode flag determines how key access is handled.  When bit0=0, the 
  2461.  default, the key routines, NEXT_KEY_XB, PREV_KEY_XB, and GET_NEXT_XB, 
  2462.  GET_PREV_XB, use the internal position of the last gotten key as their 
  2463.  starting point.  In multi-threaded code, it's possible that another thread has 
  2464.  since accessed the same file handle and altered the last gotten key.  By 
  2465.  setting bit0=1, key access (next or previous) can now specify a starting point 
  2466.  (typically already set up in AP.keyPtr), rather than starting at the last 
  2467.  accessed key for that handle (which may have been changed by another thread). 
  2468.  
  2469.  The Callback routine receives a pointer to a CALLBACK structure on the stack. 
  2470.  The callback routine may clean the stack (e.g., a _syscall routine).  It may 
  2471.  also leave it for the caller to clean (e.g., a _stdcall or __cdecl routine). 
  2472.  See bd_rix.c on the distribution disk for an example.  When the CALLBACK_PTR 
  2473.  == NULL (default), no callback is made.  Currently, the callback is made 
  2474.  during REINDEX_XB and PACK_RECORDS calls, at a rate dependent on the 
  2475.  *_BUFFER_SIZE. 
  2476.  
  2477.  Note:  This routine is not mutex-protected. 
  2478.  
  2479.  
  2480. ΓòÉΓòÉΓòÉ 9.9. SET_SYSVARS_XB ΓòÉΓòÉΓòÉ
  2481.  
  2482. Pack: QUERYSETPACK             Source Example 
  2483.  
  2484.      IN               OUT
  2485.    QSP.func         QSP.stat
  2486.    QSP.item         QSP.itemValue
  2487.    QSP.itemValue
  2488.  
  2489.  Set a BULLET system variable, returning the previous value. 
  2490.  
  2491.  To use, set QSP.item to the item to set, and QSP.itemValue with the value to 
  2492.  use (function's address, variable's timeout value, etc., whatever the case may 
  2493.  be).  On return, QSP.itemValue is the previous value that QSP.item was set to. 
  2494.  
  2495.    QSP.item           FuncPtr To
  2496.    ASCII_SORT        ASCII sort compare
  2497.    NLS_SORT          NLS sort compare
  2498.    S16_SORT          16-bit signed integer
  2499.    U16_SORT          16-bit unsigned integer
  2500.    S32_SORT          32-bit signed integer
  2501.    U32_SORT          32-bit unsigned integer
  2502.  
  2503.  All intrinsic sort compares (1-6) point to the same function. They cannot be 
  2504.  called except by BULLET itself.  They should not be overloaded with custom 
  2505.  functions.  If you have a custom sort-compare, use one of the custom slots. 
  2506.  The integer compare routines are based on Intel byte order.  For Motorola byte 
  2507.  order, ASCII sort can be used for all-positive numbers, otherwise a custom 
  2508.  sort-compare should be used. 
  2509.  
  2510.     QSP.item          FuncPtr To
  2511.      10-19           Custom sort-compare functions
  2512.  
  2513.  Before creating or opening an index file with a custom sort-compare function 
  2514.  (which is specified during CREATE_INDEX_XB), that function's address must 
  2515.  first be sent to BULLET using this routine. Thereafter, that function must be 
  2516.  available whenever that index file is accessed.  See Custom Sort-Compare 
  2517.  Function for creating custom sort-compare functions. 
  2518.  
  2519.  To set the function pointers to the build key and expression parser routines, 
  2520.  use: 
  2521.  
  2522.     QSP.item          FuncPtr To
  2523.    BUILD_KEY_FUNC    Build key routine
  2524.    PARSER_FUNC       Key expression parser routine
  2525.  
  2526.  Before creating or opening an index file with a custom build key or expression 
  2527.  parser routine (which is specified at any time, but must be used in a 
  2528.  consistent manner), that routine's address must first be sent to BULLET using 
  2529.  this routine.  Thereafter, that routine should always be ready (in a callable 
  2530.  state) since it may be required again.  See Custom Build-Key Routine for 
  2531.  creating a custom build-key routine and Custom Expression Parser Routine for 
  2532.  creating a custom key expression parser. 
  2533.  
  2534.  To set the BULLET system variables' values, use: 
  2535.  
  2536.     QSP.item             Value To
  2537.    LOCK_TIMEOUT          Lock file bytes timeout, in milliseconds (default=0)
  2538.    MUTEX_SEM_TIMEOUT     Mutex semaphore request timeout, in milliseconds (default=0)
  2539.    PACK_BUFFER_SIZE      Pack buffer size, in bytes (default=0: autosize)
  2540.    REINDEX_BUFFER_SIZE   Reindex buffer size, in bytes (default=0: autosize)
  2541.    REINDEX_PACK_PCT      Reindex node pack percentage, 50-100% (default=100)
  2542.    TMP_PATH_PTR          Temporary file path pointer (default=NULL, where TMP= used, then .\)
  2543.    REINDEX_SKIP_TAG      Reindex tag field character to skip (default=0, no skip)
  2544.    COMMIT_AT_EACH        Commit each individual file during INSERT/UPDATE_XB (default=0, defer until flush)
  2545.    MEMO_BLOCKSIZE        Memo file block size (default=512 bytes; minimum is 24 bytes)
  2546.    MEMO_EXTENSION        Memo file extension (default is "DBT\0")
  2547.    MAX_DATAFILE_SIZE     Max data file size-1 (default=2047MB, absolute max is 4095MB)
  2548.    MAX_INDEXFILE_SIZE    Max index file size-1 (default=2047MB, absolute max is 4095MB)
  2549.    ATOMIC_MODE           Atomic mode (bit0=1 then atomic Next and Prev access, default=0)
  2550.    CALLBACK_PTR          Callback routine at reindex/pack (def=0, none)
  2551.  
  2552.  The timeout values determine if the kernel should wait for a pre-determined 
  2553.  time before returning an error if the resource cannot be obtained.  The lock 
  2554.  timeout specifies how long to wait for a lock to be obtained in case some 
  2555.  other process has a lock on the same resource.  The mutex timeout specifies 
  2556.  how long to wait for access to BULLET in case some other thread in this 
  2557.  process is in BULLET.  Multiple processes can access BULLET at the same time, 
  2558.  but only one thread in each process can be inside BULLET at any one time. 
  2559.  
  2560.  The buffer sizes, when 0, default to a minimum reasonable size.  Performance 
  2561.  is acceptable at these sizes.  For best performance, provide as much real 
  2562.  memory as possible, up to 512KB.  Larger buffers can be used. 
  2563.  
  2564.  The reindex node pack percentage determines how many keys are packed on a 
  2565.  node.  100% forces as many keys as possible, minus 1. 
  2566.  
  2567.  If the temporary file path pointer is NULL (the default), then the TMP= 
  2568.  environment variable is used to locate any temporary files created by BULLET, 
  2569.  or if that is not found, then the current directory is used.  The pointer 
  2570.  supplied, if any, should be to a string containing an existing path (drive 
  2571.  should be included; a trailing '\' is optional, but recommended).  See 
  2572.  REINDEX_XB for size requirements. 
  2573.  
  2574.  The reindex skip tag character, if encountered in the DBF record's tag field 
  2575.  (the first byte of each record), causes the reindex routine to not place that 
  2576.  record's key value into the index file.  Also, BUILD_KEY_XB returns a warning 
  2577.  if the record supplied has a matching tag character. To disable skip tag 
  2578.  processing, set it to 0. 
  2579.  
  2580.  Inserts and Updates, by default, do not commit each file when that pack is 
  2581.  processed.  Instead, it is left to the programmer to issue a FLUSH_XB to 
  2582.  commit.  To force a commit after each pack file is processed, set CommitAtEach 
  2583.  to 1.  This is not one single commit, but a commit for each file in the pack, 
  2584.  after that file has been processed, but before the next file in the pack is. 
  2585.  This will not prevent a roll-back should it be needed. 
  2586.  
  2587.  A memo file can have at most 589,822 blocks.  At the default 512 bytes per 
  2588.  block, that equates to about 288MB.  If you need more memo space, increase the 
  2589.  block size.  The memo extension default is "DBT\0".  Generally, it's a good 
  2590.  idea to leave it at this. 
  2591.  
  2592.  The maximum file sizes are enforced when adding to or reading from DBF files, 
  2593.  and when inserting into or reading from index files.  The default is 2047 MB 
  2594.  (0x7FEFFFFF).  If your file system permits 4GB files, set the values to 4095 
  2595.  MB (0xFFEFFFFF). 
  2596.  
  2597.  The Atomic mode flag determines how key access is handled.  When bit0=0, the 
  2598.  default, the key routines, NEXT_KEY_XB, PREV_KEY_XB, and GET_NEXT_XB, 
  2599.  GET_PREV_XB, use the internal position of the last gotten key as their 
  2600.  starting point.  In multi-threaded code, it's possible that another thread has 
  2601.  since accessed the same file handle and altered the last gotten key.  By 
  2602.  setting bit0=1, key access (next or previous) can now specify a starting point 
  2603.  (typically already set up in AP.keyPtr), rather than starting at the last 
  2604.  accessed key for that handle (which may have been changed by another thread). 
  2605.  
  2606.  The Callback routine receives a pointer to a CALLBACK structure on the stack. 
  2607.  The callback routine may clean the stack (e.g., a _syscall routine).  It may 
  2608.  also leave it for the caller to clean (e.g., a _stdcall or __cdecl routine). 
  2609.  See bd_rix.c on the distribution disk for an example.  When the CALLBACK_PTR 
  2610.  == NULL (default), no callback is made.  Currently, the callback is made 
  2611.  during REINDEX_XB and PACK_RECORDS calls, at a rate dependent on the 
  2612.  *_BUFFER_SIZE. 
  2613.  
  2614.  Note:  Issuing INIT_XB restores all system variables (those setable via this 
  2615.  routine) and function pointers, but not vectors, to their default values. 
  2616.  This is done even if INIT_XB returns an error that BULLET has already been 
  2617.  initialized. 
  2618.  
  2619.  
  2620. ΓòÉΓòÉΓòÉ 9.10. SET_DVMON_XB ΓòÉΓòÉΓòÉ
  2621.  
  2622. This routine is not currently used. 
  2623.  
  2624.  
  2625. ΓòÉΓòÉΓòÉ 9.11. QUERY_VECTORS_XB ΓòÉΓòÉΓòÉ
  2626.  
  2627. Pack: QUERYSETPACK             Source Example 
  2628.  
  2629.      IN               OUT
  2630.    QSP.func         QSP.stat
  2631.    QSP.item         QSP.itemValue
  2632.  
  2633.  Query a BULLET OS API vector. 
  2634.  
  2635.  To get the vectors that Bullet makes to access OS API calls, set QSP.item to 
  2636.  the desired VECTOR_* constant below.  On return, QSP.itemValue has the 
  2637.  function pointer for that item. 
  2638.  
  2639.        QSP.item
  2640.    VECTOR_CLOSE_FILE
  2641.    VECTOR_CREATE_DIR
  2642.    VECTOR_CREATE_FILE
  2643.    VECTOR_CREATE_UNIQUE_FILE
  2644.    VECTOR_DELETE_FILE
  2645.    VECTOR_LENGTH_FILE
  2646.    VECTOR_MOVE_FILE
  2647.    VECTOR_OPEN_FILE
  2648.    VECTOR_READ_FILE
  2649.    VECTOR_SEEK_FILE
  2650.    VECTOR_UPDATE_DIR_ENTRY
  2651.    VECTOR_WRITE_FILE
  2652.    VECTOR_LOCK_FILE
  2653.    VECTOR_IS_DRIVE_REMOTE
  2654.    VECTOR_IS_FILE_REMOTE
  2655.    VECTOR_EXITLIST
  2656.    VECTOR_REMOVE_EXITLIST
  2657.    VECTOR_FREE
  2658.    VECTOR_GET_SORT_TABLE
  2659.    VECTOR_GET_COUNTRY_INFO
  2660.    VECTOR_GET_ERROR_CLASS
  2661.    VECTOR_GET_MEMORY
  2662.    VECTOR_GET_TMP_DIR
  2663.    VECTOR_GET_VERSION
  2664.    VECTOR_MALLOC
  2665.    VECTOR_SET_HANDLE_COUNT
  2666.    VECTOR_GET_TIME_INFO
  2667.    VECTOR_UPPERCASE
  2668.    VECTOR_CLOSE_MUTEX_SEM
  2669.    VECTOR_CREATE_MUTEX_SEM
  2670.    VECTOR_RELEASE_MUTEX_SEM
  2671.    VECTOR_REQUEST_MUTEX_SEM
  2672.  
  2673.  If QSP.itemValue is returned NULL, the default Bullet OS API call is being 
  2674.  used. 
  2675.  
  2676.  Note:  This routine is not mutex-protected. 
  2677.  
  2678.  
  2679. ΓòÉΓòÉΓòÉ 9.12. SET_VECTORS_XB ΓòÉΓòÉΓòÉ
  2680.  
  2681. Pack: QUERYSETPACK             Source Example 
  2682.  
  2683.      IN               OUT
  2684.    QSP.func         QSP.stat
  2685.    QSP.item         QSP.itemValue
  2686.    QSP.itemValue
  2687.  
  2688.  Set a BULLET OS API vector. 
  2689.  
  2690.  To set the vectors that Bullet makes to access OS API calls, set QSP.item to 
  2691.  the desired VECTOR_* constant below, and QSP.itemValue to its replacement's 
  2692.  address.  On return, QSP.itemValue has the previous function pointer for that 
  2693.  item. 
  2694.  
  2695.        QSP.item
  2696.    VECTOR_CLOSE_FILE
  2697.    VECTOR_CREATE_DIR
  2698.    VECTOR_CREATE_FILE
  2699.    VECTOR_CREATE_UNIQUE_FILE
  2700.    VECTOR_DELETE_FILE
  2701.    VECTOR_LENGTH_FILE
  2702.    VECTOR_MOVE_FILE
  2703.    VECTOR_OPEN_FILE
  2704.    VECTOR_READ_FILE
  2705.    VECTOR_SEEK_FILE
  2706.    VECTOR_UPDATE_DIR_ENTRY
  2707.    VECTOR_WRITE_FILE
  2708.    VECTOR_LOCK_FILE
  2709.    VECTOR_IS_DRIVE_REMOTE
  2710.    VECTOR_IS_FILE_REMOTE
  2711.    VECTOR_EXITLIST
  2712.    VECTOR_REMOVE_EXITLIST
  2713.    VECTOR_FREE
  2714.    VECTOR_GET_SORT_TABLE
  2715.    VECTOR_GET_COUNTRY_INFO
  2716.    VECTOR_GET_ERROR_CLASS
  2717.    VECTOR_GET_MEMORY
  2718.    VECTOR_GET_TMP_DIR
  2719.    VECTOR_GET_VERSION
  2720.    VECTOR_MALLOC
  2721.    VECTOR_SET_HANDLE_COUNT
  2722.    VECTOR_GET_TIME_INFO
  2723.    VECTOR_UPPERCASE
  2724.    VECTOR_CLOSE_MUTEX_SEM
  2725.    VECTOR_CREATE_MUTEX_SEM
  2726.    VECTOR_RELEASE_MUTEX_SEM
  2727.    VECTOR_REQUEST_MUTEX_SEM
  2728.  
  2729.  Example replacement routines are in ccdosfn.c.  Many of the routines in 
  2730.  ccdosfn.c are standard C, but some are OS-specific and must be updated for the 
  2731.  OS being used. 
  2732.  
  2733.  If QSP.itemValue is set to NULL, the default Bullet OS API call is used. 
  2734.  
  2735.  On return from a successful call, QSP.itemValue is the value of the previous 
  2736.  function pointer for that item, which may be returned NULL, indicating that 
  2737.  the default Bullet OS API call was being used. 
  2738.  
  2739.  
  2740. ΓòÉΓòÉΓòÉ 9.13. CREATE_DATA_XB ΓòÉΓòÉΓòÉ
  2741.  
  2742. Pack: CREATEDATAPACK           Source Example 
  2743.  
  2744.      IN               OUT
  2745.    CDP.func         CDP.stat
  2746.    CDP.filenamePtr
  2747.    CDP.noFields
  2748.    CDP.fieldListPtr
  2749.    CDP.fileID
  2750.  
  2751.  Create a new BULLET DBF data file with the name at CDP.filenamePtr, and an 
  2752.  optional DBT memo file. 
  2753.  
  2754.  Before using this routine, allocate an array of field descriptors of type 
  2755.  FIELDDESCTYPE, one for each field in the record (number of fields as set in 
  2756.  CDP.noFields). It is recommended  that this allocation be zeroed before use 
  2757.  since fieldnames and reserved entries must be 0-filled: 
  2758.  
  2759.      FIELDDESCTYPE fieldList[12];  // 12 fields used in data record
  2760.        :
  2761.      memset(fieldList,0,sizeof(fieldList)); // init unused bytes to 0 (required)
  2762.  
  2763.  Filename 
  2764.  
  2765.  The drive and path must exist if used as part of the filename. Long filenames 
  2766.  may be used if supported by the file system in use. As with all text strings 
  2767.  used by Bullet, the filename must end in a '\0'. 
  2768.  
  2769.  Number of Fields 
  2770.  
  2771.  The number of descriptors in the array, described next.  Each field has a 
  2772.  descriptor.  The tag field is not a formal field, and so has no descriptor, 
  2773.  and is not counted in the number of fields.  The maximum number of fields is 
  2774.  254 according to the DBF standard.  Bullet allows 1024, but 254 should be used 
  2775.  if creating a standard DBF III Plus file. 
  2776.  
  2777.  Field Descriptors 
  2778.  
  2779.  For each field, a descriptor is used to identify and type it.  These 
  2780.  descriptors are assigned to an array; the pointer to that array is assigned to 
  2781.  CDP.fieldListPtr.  The format of the descriptor follows, with a physical 
  2782.  format listed in DBF File Format. 
  2783.  
  2784.  Γûá Fieldname 
  2785.  
  2786.  10 characters plus null byte terminator.  Valid fieldname characters are ASCII 
  2787.  A-Z (upper-case) and the underscore (ASCII 95).  All bytes after the fieldname 
  2788.  must be null bytes.  E.g., if the fieldname is "LNAME", five characters, the 
  2789.  following six bytes (including the 11th byte) are set to 0. The eleventh byte 
  2790.  is always a null byte since 10 characters is the maximum fieldname length. 
  2791.  Extended ASCII characters (above 127) should not be used. 
  2792.  
  2793.   fieldList[0].fieldname = "ANYNAME";   // see memset() above
  2794.  
  2795.  Γûá Field type and size 
  2796.  
  2797.  Standard Xbase field types are C, D, L, M, and N: 
  2798.  
  2799.  Type   Description 
  2800.    C    Character field, any code page character, 1 to 255 characters. 
  2801.         Null bytes are not desirable except as a string terminator.  There is 
  2802.         no requirement that field data be terminated with a '\0'.  The field 
  2803.         data should be left-justified within the field, but this is not 
  2804.         required (in which case use leading spaces, not 0 bytes). 
  2805.  
  2806.                        fieldList[0].fieldType = 'C';
  2807.                        fieldList[0].fieldLen = 25;
  2808.                        fieldList[0].fieldDC = 0;
  2809.  
  2810.    D    Date field, valid ASCII digits for date, 8 characters. 
  2811.         The physical format is YYYYMMDD, where YYYY is the year (1999), MM is 
  2812.         the month (1-12), and DD the day (1-31).  The date field is always 8 
  2813.         bytes long, and is in ASCII digits ('19991231').  If no date, set to 
  2814.         all spaces. 
  2815.  
  2816.                        fieldList[0].fieldType = 'D';
  2817.                        fieldList[0].fieldLen = 8;
  2818.                        fieldList[0].fieldDC = 0;
  2819.  
  2820.    L    Logical field, < SPACE> Y N T F y n t f, 1 character. 
  2821.         A single-byte field.  When not yet initialized the value will be a 
  2822.         <SPACE> (ASCII 32).  This is typically displayed as a '?' to the user, 
  2823.         indicating that the field has not been initialized.  Initialized values 
  2824.         are variations of yes, no, true, false ('Y', 'y', etc.). 
  2825.  
  2826.                        fieldList[0].fieldType = 'L';
  2827.                        fieldList[0].fieldLen = 1;
  2828.                        fieldList[0].fieldDC = 0;
  2829.  
  2830.    M    Memo field, 10 ASCII digits, 10 characters. 
  2831.         Field data is used as the block number in the corresponding DBT memo 
  2832.         file.  Each block is typically 512 bytes, with the first block (block 
  2833.         #0) used as the memo file header.  If no block is used in the .DBT by 
  2834.         this record, the field is set to <SPACES>.  The first memo block is 
  2835.         stored as "0000000001".  (This description is valid for dBASE IV and 
  2836.         later memo files, as created and used by BULLET.) Some Xbase versions 
  2837.         use field types B and G as variations of memo files.  They are as M, 
  2838.         but contain general data (as in anything), while memo files contain 
  2839.         only text. BULLET supports any type data in its memo files, and you may 
  2840.         use the CDP.fieldType of 'B' or 'G'. 
  2841.  
  2842.         More than one memo field per record is permitted.  For example, you may 
  2843.         need a memo for the printable address, where the address is free-form 
  2844.         rather than in separate fields (i.e., you have both forms), and another 
  2845.         memo for general notes, and yet a third for problem reports, and so on. 
  2846.         All these, and all memos for the rest of the DBF file, are stored in 
  2847.         the same DBT memo file. 
  2848.  
  2849.         Note:  BULLET does not use the fieldType with regard to identifying 
  2850.         memo field type; it is the programmer's responsibility to check the 
  2851.         fieldType and act on it accordingly, such as adding memo numbers. 
  2852.  
  2853.                        fieldList[0].fieldType = 'M';
  2854.                        fieldList[0].fieldLen = 10;
  2855.                        fieldList[0].fieldDC = 0;
  2856.  
  2857.    N    Numeric field, ASCII digits, 19 digits maximum (see below). 
  2858.         All standard Xbase data is stored in ASCII form (for universal 
  2859.         exchange).  Numeric fields are to be right-justified, with leading 
  2860.         spaces, and an aligned decimal point, if any (relative this field in 
  2861.         other records).  Do not end the field with a null byte. 
  2862.  
  2863.         The total size of the numeric field is specified in .fieldLen, which 
  2864.         includes any leading sign, the decimal point, and decimal digits to the 
  2865.         right of the decimal point (if any decimal point). The maximum total 
  2866.         size is 19 places.  If a decimal point, then the number of digits to 
  2867.         the right may be from 1 to 15 digits, but must be no more than the 
  2868.         total-2. 
  2869.  
  2870.                    FieldLen.FieldDC    Example
  2871.                            8.2          " 2345.78"
  2872.                            8.2          "12345.78"
  2873.                            8.2          "-2345.78"
  2874.                            8.1          "123456.8"
  2875.                            8.0          "12345678"
  2876.                            5.3          "2.235"
  2877.                            5.4          (not valid)
  2878.  
  2879.                        fieldList[0].fieldType = 'N';
  2880.                        fieldList[0].fieldLen = 8;
  2881.                        fieldList[0].fieldDC = 2;
  2882.  
  2883.  Although not dBASE compatible, you may use binary fields in your data records. 
  2884.  The Xbase standard always has ASCII data in the data fields, even if the field 
  2885.  is numeric.  For example, an 'N' type field of 8.2 (total 
  2886.  length.decimal-count) is stored as an ASCII text string in the data record, 
  2887.  say, a string like " 1100.55".  If you want dBASE compatibility your field 
  2888.  data must also be ASCII.  However, if you can forgo this requirement, you can 
  2889.  use binary values in the fields. 
  2890.  
  2891.  To do this you must specify a field type of 'Y' (actually, anything but an 
  2892.  'N') and, if it is to be used as a key field, also set the sort function to 
  2893.  the appropriate type (S16_SORT, etc.).  The field length 
  2894.  (fieldList[x].fieldLen) for a 'Y' field type is 2 if 16-bit, and 4 if 32-bit. 
  2895.  Also possible is floating-point (with a custom sort-compare function).  A 
  2896.  likely field type marker for this would be 'F'.  Note that both 'Y' and 'F' 
  2897.  are completely non-standard Xbase types, and only your programs will 
  2898.  understand them. 
  2899.  
  2900.  Note:  'B' should not be used as a binary field type marker since dBASE V uses 
  2901.  'B' to signify a binary-data memo file field.  Bullet makes no distinction in 
  2902.  its memo file data; anything can be placed in them.  Typically, your memo 
  2903.  fields are marked as 'M' in Bullet, but could also be 'B' or 'G'. 
  2904.  
  2905.  File ID 
  2906.  
  2907.  Conventional dBASE DBF files have a CDP.fileID=3.  To create a memo file (DBT, 
  2908.  dBASE IV compatible), set CDP.fileID=x8B.  For the DBT to be created, both 
  2909.  bits 3 and 7 (0x88) must be set.  The other bits may be anything, and are not 
  2910.  checked.  In creating your DBF files, specify CDP.fileID=3 to ensure 
  2911.  compatibility across Xbase versions, and limit record length to 4000 
  2912.  characters.  If creating a non-standard DBF (e.g., non-standard field types, 
  2913.  extended field lengths, etc.) it's recommended to use CDP.fileID=0 or 
  2914.  CDP.fileID=1.  For a standard DBF file with a memo file (dBASE IV or later), 
  2915.  use CDP.fileID=0x8B (eight-bee). 
  2916.  
  2917.  Generally, field data is space-filled.  String terminators are allowed in 
  2918.  C-haracter field types, but should not be used in other fields. 
  2919.  
  2920.  Memo File Creation 
  2921.  
  2922.  If bits 3 and 7 are set in CDP.fileID, a memo file is created for the DBF. The 
  2923.  memo filename will be the same as the DBF name except the extension. The memo 
  2924.  file is created after the DBF, with a block size of 512 bytes, and filename 
  2925.  extension of ".DBT".  The default block size and extension can be overridden 
  2926.  (see SET_SYSVARS_XB) prior to calling this routine. 
  2927.  
  2928.  Note:  A simple way to check that your record description in the field list 
  2929.  matches your source code structure is to compare the number of bytes used by 
  2930.  all fields in the field list (+1 for the delete tag byte) with the size of 
  2931.  your program's structure.  They must equal.  Also verify each field's size to 
  2932.  make sure they match.  By doing this you prevent the problem where data on 
  2933.  disk does not match the data in your record structure. 
  2934.  
  2935.  
  2936. ΓòÉΓòÉΓòÉ 9.14. OPEN_DATA_XB ΓòÉΓòÉΓòÉ
  2937.  
  2938. Pack: OPENPACK                 Source Example 
  2939.  
  2940.      IN               OUT
  2941.    OP.func          OP.stat
  2942.    OP.filenamePtr   OP.handle
  2943.    OP.asMode
  2944.  
  2945.  Open an existing DBF data file for use.  For DBF opens, two parameters are 
  2946.  specified:  the filename and the access-sharing mode.  The OP.xbLink parameter 
  2947.  is used only for index opens, and so is not used here. 
  2948.  
  2949.  The OP.asMode has optional cache mode settings.  The caching modes cover 
  2950.  locality, write-through, and skip cache.  Locality is typically mostly random 
  2951.  (RND_LOCALITY), but may be mostly sequential if the data file has been sorted 
  2952.  and the index file recently reindexed and processing is mostly in-order (first 
  2953.  to last, rather than random).  Locality is used to tune the cache.  Also, 
  2954.  normally, data is written to the cache with control returning immediately to 
  2955.  the program before the disk is written (an asynchronous write).  To force the 
  2956.  write to take place before control is returned (a synchronous write), use the 
  2957.  WRITE_THROUGH mode.  To skip the cache completely, use the SKIP_CACHE mode. 
  2958.  This, as all OP.asMode settings, affects this file handle only. 
  2959.  
  2960.  On a successful open, the file handle is returned.  Use this handle for all 
  2961.  further access to this file.  If the DBF was created with a compatible memo 
  2962.  file, it is also opened.  The handle of the memo file is available via 
  2963.  STAT_DATA_XB, but all access to the memo file is made with the handle of the 
  2964.  memo file's master DBF (the handle returned by this routine in OP.handle). 
  2965.  The memo file is opened using the same OP.asMode. 
  2966.  
  2967.  Note:  FoxPro DBF files with Fox memo files (FPT) use an ID of 0xFF.  Bullet 
  2968.  does not support FoxPro memo files, and so opening a FoxPro DBF with a Fox 
  2969.  memo file returns the warning message, WRN_CANNOT_OPEN_MEMO.  The DBF file is 
  2970.  opened, and the warning can be ignored. 
  2971.  
  2972.  Once open, you can get information on the data file by using STAT_DATA_XB. 
  2973.  
  2974.  Each DBF data file opened allocates and commits at least 4K bytes for internal 
  2975.  use: 
  2976.  
  2977.    Number of Fields     Memory
  2978.         1 to 121            4KB
  2979.       122 to 249            8KB
  2980.       each 128 fields       4KB more
  2981.  
  2982.  This memory is released when you close the file with CLOSE_DATA_XB. or issue 
  2983.  EXIT_XB. 
  2984.  
  2985.  Note:  You must open the data file before you can open or create any of its 
  2986.  index files. 
  2987.  
  2988.  When BULLET creates a DBF, it forces all fieldnames to upper-case (it's a DBF 
  2989.  requirement) and 0-fills them as well.  On data file opens (OPEN_DATA_XB), it 
  2990.  also does this, and so any header copy (COPY_DATA_HEADER_XB) will have 
  2991.  upper-cased fieldnames (the original file is not changed).  To prevent BULLET 
  2992.  from mapping the fieldnames to upper-case (NLS mapping, though fieldnames 
  2993.  should be standard ASCII characters only), set bit31 of OP.asMode to 1 
  2994.  (0x80000042, for example).  This skips the case mapping.  Zero-filling always 
  2995.  takes place, and starts after the first '\0' byte in the fieldname. 
  2996.  
  2997.  
  2998. ΓòÉΓòÉΓòÉ 9.15. CLOSE_DATA_XB ΓòÉΓòÉΓòÉ
  2999.  
  3000. Pack: HANDLEPACK               Source Example 
  3001.  
  3002.      IN               OUT
  3003.    HP.func          HP.stat
  3004.    HP.handle
  3005.  
  3006.  Close an existing data file. 
  3007.  
  3008.  Closing the file updates the file header and releases the memory used by the 
  3009.  file.  Any associated memo file is closed, too.  Any outstanding locks should 
  3010.  be unlocked before calling this routine. 
  3011.  
  3012.  Note:  Remaining locks belonging to this handle are released by the OS upon 
  3013.  the successful close. 
  3014.  
  3015.  
  3016. ΓòÉΓòÉΓòÉ 9.16. STAT_DATA_XB ΓòÉΓòÉΓòÉ
  3017.  
  3018. Pack: STATDATAPACK             Source Example 
  3019.  
  3020.      IN               OUT
  3021.    SDP.func         SDP.stat         SDP.recordLength
  3022.    SDP.handle       SDP.fileType     SDP.xactionFlag
  3023.                     SDP.flags        SDP.encryptFlag
  3024.                     SDP.progress     SDP.herePtr
  3025.                     SDP.morePtr      SDP.memoHandle
  3026.                     SDP.fields       SDP.memoBlockSize
  3027.                     SDP.asMode       SDP.memoFlags
  3028.                     SDP.filenamePtr  SDP.memoLastRecord
  3029.                     SDP.fileID       SDP.memoLastSize
  3030.                     SDP.lastUpdate   SDP.lockCount
  3031.                     SDP.records
  3032.  
  3033.  Return information BULLET has on the DBF data file specified by SDP.handle. 
  3034.  
  3035.    Item             Description 
  3036.  stat               Return code of operation 
  3037.  fileType           1 for DBF 
  3038.  flags              Bit0=1 if file has changed since last flush (dirty) 
  3039.                     Bit1=1 if the file has its entire region locked (full lock) 
  3040.                     Bit2=1 if the file has a shared lock in use (cannot write 
  3041.                     to it if so) 
  3042.  progress           Percentage of pack operation completed, 1-99, or 0 if done 
  3043.  morePtr            Always 0 
  3044.  fields             Number of fields per record (does not included implicit tag 
  3045.                     field) 
  3046.  asMode             Access-sharing-cache mode as specified at open (excludes 
  3047.                     NoCaseMap bit31) 
  3048.  filenamePtr        Pointer to the filename as used in OPEN_DATA_XB 
  3049.  fileID             ID byte used when the DBF was created (the first byte of 
  3050.                     the file) 
  3051.  lastUpdate         Date of last change (binary: high word=year (1999), low 
  3052.                     byte=day, high byte=month) 
  3053.  records            Number of records in the DBF (includes any delete-tagged 
  3054.                     records) 
  3055.  recordLength       Total length of a data record, including tag field 
  3056.  xactionFlag        Not currently used 
  3057.  encryptFlag        Not currently used 
  3058.  herePtr            Pointer to the internal data control area for this file 
  3059.                     handle 
  3060.  memoHandle         Handle of open memo file (0 if none) 
  3061.  memoBlockSize      Memo file block size (512 is typical, 24 is minimum) 
  3062.  memoFlags          Bit0=1 dirty 
  3063.  memoLastRecord     Last accessed memo record (0 if none; same as 'block 
  3064.                     number') 
  3065.  memoLastSize       Size of last accessed memo record (in bytes, including 8 
  3066.                     bytes overhead) 
  3067.  lockCount          Number of full-locks in force (locked on first, unlocked on 
  3068.                     last) 
  3069.  
  3070.  Typically, your program tracks whether a particular handle belongs to an index 
  3071.  file or data file.  In cases where this is not possible, call the 
  3072.  STAT_HANDLE_XB. routine to determine what file type a handle is. 
  3073.  
  3074.  Note:  In network environments, you should have an exclusive lock on the data 
  3075.  file (and implicitly, therefore, the memo file, if any) before using this 
  3076.  routine to ensure that the information is current.  This also applies to 
  3077.  multi-process environments on a single machine.  This routine is not 
  3078.  mutex-protected.  During the call, the file handle must not be closed by 
  3079.  another thread. 
  3080.  
  3081.  
  3082. ΓòÉΓòÉΓòÉ 9.17. READ_DATA_HEADER_XB ΓòÉΓòÉΓòÉ
  3083.  
  3084. Pack: HANDLEPACK               Source Example 
  3085.  
  3086.      IN               OUT
  3087.    HP.func          HP.stat
  3088.    HP.handle
  3089.  
  3090.  Reload the disk copy of the data header for the opened DBF data file handle, 
  3091.  refreshing the in-memory copy.  Any associated memo file is refreshed, too. 
  3092.  
  3093.  Normally, this routine is not called directly but rather is done automatically 
  3094.  when you full-lock the file (LOCK_XB).  This routine does not refresh the 
  3095.  header if the current state is dirty (SDP.flags, bit0=1); it returns an error 
  3096.  if tried. Since it is recommended that a full-lock be in force before using 
  3097.  this routine (shared or exclusive), and since a full-lock always reloads the 
  3098.  header anyway, calling this routine should never be required.  If ever there 
  3099.  is a reason to use this routine without having a full-lock in force, then, of 
  3100.  course, you may need to.  However, it is not wise to reload the header without 
  3101.  a full-lock (which locks the header).  If you are using your own lock 
  3102.  routines, this call will be very useful. 
  3103.  
  3104.  In single-user, single-tasking systems this routine is not needed.  However, 
  3105.  in a multi-user or multi-tasking system it's possible, and desirable, for two 
  3106.  or more programs to use the same data file.  Consider this scenario: A data 
  3107.  file has 100 records.  Two programs access this data file, both opening it. 
  3108.  Program 1 locks the file, adds a new record, then flushes and unlocks the 
  3109.  file.  Program 1 knows that there are now 101 records in the file.  However, 
  3110.  Program 2 is not aware of the changes that Program 1 made--it thinks that 
  3111.  there are still 100 records in the file.  This out-of-sync situation is easily 
  3112.  remedied by having Program 2 reload the data header from the file on disk. 
  3113.  
  3114.  How does Program 2 know that it needs to reload the header? It doesn't. 
  3115.  Instead, BULLET uses a simple, yet effective, approach when dealing with this. 
  3116.  When BULLET full-locks a file, BULLET automatically reloads the header by 
  3117.  using this routine.  When removing the full-lock, BULLET automatically flushes 
  3118.  the header using FLUSH_DATA_HEADER_XB (unless the current lock is a shared 
  3119.  lock (SDP.flags bit2=1)). 
  3120.  
  3121.  
  3122. ΓòÉΓòÉΓòÉ 9.18. FLUSH_DATA_HEADER_XB ΓòÉΓòÉΓòÉ
  3123.  
  3124. Pack: HANDLEPACK               Source Example 
  3125.  
  3126.      IN               OUT
  3127.    HP.func          HP.stat
  3128.    HP.handle
  3129.  
  3130.  Write the in-memory copy of the data header for the opened DBF data file 
  3131.  handle to disk.  The actual write occurs only if the header has been changed 
  3132.  (the dirty bit is set).  Any associated memo file is flushed, too.  This 
  3133.  routine ensures that the data header on disk matches exactly the data header 
  3134.  that is being maintained by BULLET. 
  3135.  
  3136.  Normally, this routine is not called directly but rather is done automatically 
  3137.  when you unlock the file (UNLOCK_XB).  This routine does not write out the 
  3138.  header if the current lock state is shared (SDP.flags, bit2=1); it returns an 
  3139.  error if tried.  Unlocking a full-lock performs a flush automatically, and so 
  3140.  you may never need to explicitly call this routine.  Also, when relocking from 
  3141.  an exclusive full-lock to a shared full-lock, an automatic flush is performed. 
  3142.  
  3143.  Assume the following: A data file with 100 records.  Your program opens the 
  3144.  data file and adds 1 record.  Physically, there are 101 records on disk. 
  3145.  However, the header image of the data file on disk still reads 100 records. 
  3146.  This isn't a problem, BULLET uses its internal copy of the data header and the 
  3147.  internal copy does read 101 records.  But, if there were a system failure now, 
  3148.  the image of the header would not get updated since the disk image is written 
  3149.  only on a CLOSE_ or FLUSH_DATA_XB, or on EXIT_XB (and also prior to 
  3150.  PACK_RECORDS_XB).  After the system restarts, BULLET opens the file, reads the 
  3151.  header and thinks that there are 100 records.  You lost a record.  Now, if 
  3152.  after that record add your program issues FLUSH_DATA_HEADER_XB, the header on 
  3153.  disk is refreshed with the in-memory copy, keeping the two in sync.  This 
  3154.  routine also updates the directory entry for the file, keeping things neat 
  3155.  there (file size).  Still, it doesn't come without cost: flushing takes 
  3156.  additional time, therefore, you may elect to flush periodically, or whenever 
  3157.  the system is idle. 
  3158.  
  3159.  Note:  You should have a full-lock on the file before using this routine. 
  3160.  
  3161.  
  3162. ΓòÉΓòÉΓòÉ 9.19. COPY_DATA_HEADER_XB ΓòÉΓòÉΓòÉ
  3163.  
  3164. Pack: COPYPACK                 Source Example 
  3165.  
  3166.      IN               OUT
  3167.    CP.func          CP.stat
  3168.    CP.handle
  3169.    CP.filenamePtr
  3170.  
  3171.  Copy the DBF file structure of an open data file to a new file. 
  3172.  
  3173.  This routine makes it easy for you to duplicate the structure of an existing 
  3174.  DBF file without having to specify all the information needed by 
  3175.  CREATE_DATA_XB. The resultant DBF will be exactly like the source, including 
  3176.  number of fields and field descriptions, and an empty memo file, if 
  3177.  applicable. It contains 0 records.  It may be opened as a regular Bullet data 
  3178.  file. 
  3179.  
  3180.  A typical use for this is to create a work file, where only a subset of 
  3181.  records is required.  For example:  You want to process all records of those 
  3182.  whose last name starts with A.  Copy the header to a work file, use GET_XB 
  3183.  routines to get records meeting the criterion, writing those that fit the 
  3184.  criterion to the work file (using either Add/Reindex, or Insert).  A new index 
  3185.  can be specified, or an existing index can be copied using 
  3186.  COPY_INDEX_HEADER_XB. 
  3187.  
  3188.  
  3189. ΓòÉΓòÉΓòÉ 9.20. ZAP_DATA_HEADER_XB ΓòÉΓòÉΓòÉ
  3190.  
  3191. Pack: HANDLEPACK               Source Example 
  3192.  
  3193.      IN               OUT
  3194.    HP.func          HP.stat
  3195.    HP.handle
  3196.  
  3197.  Delete all records in a DBF data file. 
  3198.  
  3199.  This routine is similar to COPY_DATA_HEADER_XB except for one major 
  3200.  difference: All data records in the source file are physically deleted.  No 
  3201.  action is performed on the DBF's memo file, if any. 
  3202.  
  3203.  If you have a DBF file with 100 records and use ZAP_DATA_HEADER_XB on it, all 
  3204.  100 records will be physically deleted and the file truncated as if no records 
  3205.  were ever in the file.  All data records are lost forever. 
  3206.  
  3207.  
  3208. ΓòÉΓòÉΓòÉ 9.21. CREATE_INDEX_XB ΓòÉΓòÉΓòÉ
  3209.  
  3210. Pack: CREATEINDEXPACK          Source Example 
  3211.  
  3212.      IN               OUT
  3213.    CIP.func         CIP.stat
  3214.    CIP.filenamePtr
  3215.    CIP.keyExpPtr
  3216.    CIP.xbLink
  3217.    CIP.sortFunction
  3218.    CIP.codePage
  3219.    CIP.countryCode
  3220.    CIP.collatePtr
  3221.    CIP.nodeSize
  3222.  
  3223.  Create a new BULLET index file. 
  3224.  
  3225.  Before you can create an index file, you must first have opened (and have 
  3226.  created if necessary) the BULLET DBF data file that it is to index. To open 
  3227.  the data file, use OPEN_DATA_XB.  To create the index file, you need to 
  3228.  provide the name to use, the key expression, the DBF file link handle 
  3229.  (obtained from the OPEN_DATA_XB call), sort function/flags, and optionally, 
  3230.  the code page, country code, and collate table.  There's also a node size 
  3231.  parameter.  Select 512, 1024, or 2048 bytes. 
  3232.  
  3233.  Note:  BULLET has an optional external data mode where only indexing is done 
  3234.  -- no data file link is used.  In this mode, BULLET manages the index files of 
  3235.  the key and key data you provide (key data is any 32-bit item, e.g., a record 
  3236.  number, offset, etc.).  This would be useful for indexing non-DBF files, even 
  3237.  files with variable-length records. 
  3238.  
  3239.  Filename 
  3240.  
  3241.  The drive and path must exist if used as part of the filename. Long filenames 
  3242.  may be used if supported by the file system in use. 
  3243.  
  3244.  Key Expression 
  3245.  
  3246.  The key expression is an ASCIIZ string composed of the elements that are to 
  3247.  make up this index file's key.  The key can be composed of any or all of the 
  3248.  fields in the DBF data record, or sub-strings within any of those fields. Up 
  3249.  to 16 component parts can be used in the expression. 
  3250.  
  3251.  Two functions are supported in evaluating a key expression. These are SUBSTR() 
  3252.  and UPPER(): 
  3253.  
  3254.  SUBSTR() extracts part of a field's data starting at a particular position for 
  3255.  x number of characters.  The first position is 1. 
  3256.  
  3257.  UPPER() converts all lower-case letters to their upper-case equivalent.  Since 
  3258.  BULLET supports NLS, UPPER() conversion is not required for proper sorting of 
  3259.  mixed-case text strings. 
  3260.  
  3261.  Any name used in the key expression must be a valid field name in the DBF data 
  3262.  file.  Below are a few sample key expressions for the given data file 
  3263.  structure: 
  3264.  
  3265.      Name  Type Len DC
  3266.     FNAME    C   25  0
  3267.     LNAME    C   25  0
  3268.     SSN      C    9  0
  3269.     DEPT     N    5  0
  3270.  
  3271.  A few example key expression strings for this structure: 
  3272.  
  3273.     keyExpression[]="LNAME";
  3274.     keyExpression[]="LNAME+FNAME";
  3275.     keyExpression[]="SUBSTR(LNAME,1,4)+SUBSTR(FNAME,1,1)+SUBSTR(SSN,6,4)";
  3276.     keyExpression[]="UPPER(LNAME+FNAME)";  // for ASCII sort function only
  3277.     keyExpression[]="DEPT+SSN";
  3278.  
  3279.  In the last example above, even though DEPT is a numeric field type (N), it 
  3280.  can still be used as a component of a multi-part character key with SSN (whose 
  3281.  type is set to character).  This because numeric fields in dBASE DBF data 
  3282.  files are ASCII digits, not binary values, and are sorted according to the 
  3283.  ASCII value or NLS weight. 
  3284.  
  3285.  The key expression is parsed when the index file is created (this routine) and 
  3286.  also when reindexed (REINDEX_XB.). The parser() function, which parses the key 
  3287.  expression, may be replaced by a programmer-supplied function if additional 
  3288.  functionality is needed.  See Custom Expression Parser Routine for details. 
  3289.  
  3290.  DBF File Link Handle (xbLink) 
  3291.  
  3292.  Since BULLET evaluates the key expression when the file is created (this 
  3293.  routine) or during reindex, it must have access to the DBF file to verify that 
  3294.  the key expression is valid.  You must, therefore, supply the OS file handle 
  3295.  of the opened DBF data file.  If you later change the structure of the DBF 
  3296.  data file (add new fields, remove others, etc.), you must use the reindex 
  3297.  routine to re-evaluate the key expression.  If the key expression is no longer 
  3298.  valid after the data file changes (key field has changed names, etc.), then 
  3299.  you must create a brand new index file with this routine, supplying the new 
  3300.  key expression, rather than reindexing. 
  3301.  
  3302.  Note:  Handles 0-2 are reserved handles and should never be used for any 
  3303.  BULLET routine.  Also, .xbLink of -1 is reserved by BULLET to indicate an 
  3304.  external data index for index create and open routines. 
  3305.  
  3306.  Sort Function 
  3307.  
  3308.  The sort function specifies the sort method for the index file. Essentially, 
  3309.  this defines the compare function used by the access methods employed by 
  3310.  BULLET when doing any type of key access (reading and writing).  There are six 
  3311.  intrinsic sort compare functions available, with an additional 10 sort compare 
  3312.  functions that can be specified by the programmer (see Custom Sort-Compare 
  3313.  Functions). 
  3314.  
  3315.  While not recommended, duplicate key values are supported and managed by 
  3316.  BULLET.  The flag DUPS_ALLOWED is OR'ed with the sort function value to 
  3317.  specify this.  Generally, it is not acceptable to allow duplicate keys for an 
  3318.  index; there should be one key identifying one record without any further 
  3319.  investigation needed to determine if the key is indeed for that record.  This 
  3320.  is not possible, not consistently so, when duplicate keys exist.  It is much 
  3321.  simpler to define your key so that duplicates are not generated, than it is to 
  3322.  deal with duplicate keys once you have them.  If an attempt to insert a key 
  3323.  that already exists in the index file is made, and DUPS_ALLOWED was not 
  3324.  specified when the index file was created, the insert fails (either a 
  3325.  STORE_KEY_XB, an INSERT_XB, or a REINDEX_XB operation), and error 
  3326.  EXB_KEY_EXISTS is returned. 
  3327.  
  3328.  For Windows, the sort function flag, USE_ANSI_CHARSET may be specified. This 
  3329.  instructs Bullet to use the ANSI character set (i.e., Windows character set) 
  3330.  for the current system code page.  The default is USE_OEM_CHARSET, which is 
  3331.  used by MS-DOS and OS/2. 
  3332.  
  3333.  Only data contained within a record should be used to build a key. The 
  3334.  physical record number is not part of the data of a record since it can change 
  3335.  at any time without you knowing about it (during a pack, for example).  Do not 
  3336.  use the record number in an attempt to generate unique keys.  Only use what is 
  3337.  available in the data record itself, so that the key can be built, or rebuilt, 
  3338.  at any time. 
  3339.  
  3340.  The intrinsic sort compare functions of BULLET are: 
  3341.  
  3342.  ASCII_SORT    1 - ASCII  (up to 16 key components) 
  3343.  NLS_SORT      2 - NLS   (up to 16 key components) 
  3344.  S16_SORT      3 - 16-bit signed integer (single component) 
  3345.  U16_SORT      4 - 16-bit unsigned integer (single component) 
  3346.  S32_SORT      5 - 32-bit signed integer (single component) 
  3347.  U32_SORT      6 - 32-bit unsigned integer (single component) 
  3348.  
  3349.  To expand on the basic functionality provided by BULLET, you can supply your 
  3350.  own parser, build, and sort compare routines, and have BULLET use them 
  3351.  instead.  With your own routines in place, you can have BULLET do just about 
  3352.  anything with regard to the index file, including evaluating the key 
  3353.  expression dynamically; using more components; allowing multi-part binary 
  3354.  keys; and more. 
  3355.  
  3356.  Generally, character data (type C) is left-justified, and unused space is 
  3357.  padded with the SPACE character (ASCII 32).  It is permissible to use C-type 
  3358.  strings, or to 0-fill unused space. 
  3359.  
  3360.  Numeric data (type N) is right-justified, with leading space to be padded with 
  3361.  the SPACE character.  It is not permissible to use 0-fill leading bytes 
  3362.  (literal '0' can used, however).  Since the field is right-justified, it is 
  3363.  not generally desirable to terminate the field with a 0 byte, either.  If a 
  3364.  decimal count is specified (not 0),the decimal point location is to be the 
  3365.  same for all entries in this field.  The field description must match the 
  3366.  actual data:  If the field length and field decimal count was specified as 
  3367.  10.2 (10 total bytes, 2 digits to the right of the decimal, then the data is 
  3368.  to be formatted so that '-234567.90' is the longest data that is to be entered 
  3369.  in that field.  All entries in all records for this field must be of the same 
  3370.  format.  For example, " 987654.21", or "   23.01", or "   -1.99" (note the 
  3371.  leading spaces).  Numeric data is indexed as ASCII values (i.e., the key 
  3372.  remains character digits) unless a binary sort function is specified. 
  3373.  
  3374.  Using one of the binary integer sort compare functions requires the following: 
  3375.  
  3376.  1.  Single component expression. 
  3377.  2.  Field type must be N if the field has ASCII digits, or if the data is 
  3378.      binary, then the field type must be Y (actually, anything but N). 
  3379.  3.  If ASCII digits, the value must fit into the function size (-32768 to 
  3380.      32767 or 0-65535 for signed/unsigned 16-bit; 2,147,483,647 to 
  3381.      -2,147,483,648 or 0-4,294,967,295 for 32-bit signed/unsigned values). 
  3382.  
  3383.  Although not dBASE compatible, you may use binary fields in your data records. 
  3384.  The Xbase standard always has ASCII data in the data fields, even if the field 
  3385.  is numeric.  For example, an 'N' type field of 8.2 (total 
  3386.  length.decimal-count) is stored as an ASCII text string in the data record, 
  3387.  say, a string like " 1100.55" (there is no \0 string terminator).  If you want 
  3388.  dBASE compatibility, your field data must be ASCII.  However, if you can forgo 
  3389.  this requirement, you can use binary values in the fields. 
  3390.  
  3391.  To do this you must specify a field type of 'Y' (actually, anything but an 
  3392.  'N') and, if it is to be used as a key field, also set the sort function to 
  3393.  the appropriate type (S16_SORT, etc.).  The field length 
  3394.  (fieldList[x].fieldLen) for a 'Y' field type is 2 if 16-bit, and 4 if 32-bit. 
  3395.  For 64-bit integers, a custom sort-copmare function is required since there is 
  3396.  no intrinsic 64-bit function available. 
  3397.  
  3398.  Note:  'B' should not be used as a binary field type marker since dBASE V uses 
  3399.  'B' to signify a binary-data memo file field.  Bullet makes no distinction in 
  3400.  its memo file data; anything can be place in them.  Typically, your memo 
  3401.  fields are marked as 'M' in Bullet, but could also be 'B' or 'G'. 
  3402.  
  3403.  The key expression string you specify may be up to 159 characters, and 
  3404.  evaluate out to 64 bytes (62 bytes if DUPS_ALLOWED is specified).  The 
  3405.  expression string must be 0-terminated, as are all strings used by BULLET 
  3406.  itself (filenames, etc.). 
  3407.  
  3408.  National Language Support (NLS) 
  3409.  
  3410.  National Language Support is available to properly sort most languages' 
  3411.  alphabets.  BULLET uses NLS to build the collate sequence table (sort table) 
  3412.  that it uses to ensure proper sorting of mixed-case keys as well as the 
  3413.  sorting of foreign language alphabets which use extended-ASCII.  In order for 
  3414.  BULLET to use the proper collate table, it must know what code page and 
  3415.  country code to use.  If not supplied, Bullet gets this information directly 
  3416.  from the OS, which provides the cc/cp for the current process.  If you supply 
  3417.  cc/cp, the code page must be loaded or an error is returned (see OS/2's CHCP 
  3418.  command).  The collate table generated is made part of the index file so that 
  3419.  all subsequent access to the index file maintains the original sort order, 
  3420.  even if, say, the MIS shop is moved to another location/computer system using 
  3421.  another country code/code page.  These three items are discussed below. 
  3422.  
  3423.  Code Page 
  3424.  
  3425.  To use the default code page of the current process, specify a code page of 0. 
  3426.  The OS is queried for the current code page and this code page is then used. 
  3427.  Any valid and available code page can be specified. This is used only if a 
  3428.  custom sort-compare or NLS sort is specified. 
  3429.  
  3430.  Country Code 
  3431.  
  3432.  To use the default country code of the current process, specify a country code 
  3433.  of 0.  The OS is queried for the current country code and this code is then 
  3434.  used.  Any valid country code can be specified.  This is used only if a custom 
  3435.  sort-compare or NLS sort is specified. 
  3436.  
  3437.  Custom Collate Table 
  3438.  
  3439.  If a null-pointer is specified, and a custom sort-compare or NLS sort is 
  3440.  specified, BULLET queries the OS for the collate sequence table to use based 
  3441.  on the code page and country code specified.  Otherwise, the supplied table is 
  3442.  used.  Intrinsic sorts other than NLS use no collate table, and the country 
  3443.  code or code page are not used, either. 
  3444.  
  3445.  To use a sort weight table of your own choosing, supply a non-NULL pointer to 
  3446.  this parameter.  If non-NULL, the passed table is used for sort compares.  The 
  3447.  table is composed of 256 weight values, one per character.  For example, table 
  3448.  position 65 ('A') and table position 97 ('a') could both be weighted 65, so 
  3449.  that that each are considered equal when sorted.  If a custom sort-compare 
  3450.  function was specified, this sort table may, or may not, be used -- it depends 
  3451.  on whether the sort compare function uses the table (it's all up to the custom 
  3452.  sort-compare function's logic). 
  3453.  
  3454.  Typically, you set both the code page and country code = 0, and the collate 
  3455.  table pointer to NULL. 
  3456.  
  3457.  Node Size 
  3458.  
  3459.  The index file is read and written in node-size chunks.  The larger the node 
  3460.  size, the more keys are read or written per chunk.  Generally, a smaller node 
  3461.  size offers better random key access, while a larger node size offers better 
  3462.  sequential key access. 
  3463.  
  3464.  Typically, an average node utilizes 66% of the node space for keys (a very 
  3465.  small number may contain only a few keys, while some may be filled 
  3466.  completely).  In a 512-byte node file, for a key length of 8, there is room 
  3467.  for (512-5)/(keylength+8) nodes, or 31 keys.  Since a typical node is filled 
  3468.  to 66%, that means about 20 keys per node.  For a 2048-byte node file, same 
  3469.  parameters, there is room for (2048-5)/(keylength+8), or 127 keys.  At the 
  3470.  standard 66% load, there are typically 83 keys per 2K node.  That's 3 more 
  3471.  keys per 2K of disk than the 512-byte node gives for 4 nodes (20 keys*4), The 
  3472.  trade-off is that each node is 4 times as large, and so requires 4 times more 
  3473.  searching.  Actual performance differences may be minimal, or may be great. 
  3474.  Run tests on expected data to determine the best for the data and access used. 
  3475.  
  3476.  
  3477. ΓòÉΓòÉΓòÉ 9.22. OPEN_INDEX_XB ΓòÉΓòÉΓòÉ
  3478.  
  3479. Pack: OPENPACK                 Source Example 
  3480.  
  3481.      IN               OUT
  3482.    OP.func          OP.stat
  3483.    OP.filenamePtr   OP.handle
  3484.    OP.asMode
  3485.    OP.xbLink
  3486.  
  3487.  Open an existing index file for use.  For index opens, three parameters are 
  3488.  specified:  the filename, the access-sharing mode, and the handle of the open 
  3489.  DBF file that this file indexes.  It is required to open the data file before 
  3490.  you can open its related index file. 
  3491.  
  3492.  Note:  Handles 0-2 are reserved handles and should never be used for any 
  3493.  BULLET routine.  Also, .xbLink of -1 is reserved by BULLET to indicate an 
  3494.  external data index for index create and open routines. 
  3495.  
  3496.  On a successful open, the file handle is returned.  Use this handle for all 
  3497.  further access to this file. 
  3498.  
  3499.  Once open, you can get information on the index file by using STAT_INDEX_XB. 
  3500.  
  3501.  Each index file that you open allocates and commits 4K bytes for internal use 
  3502.  (this will vary if SET_VECTORS_XB with VECTOR_MALLOC is used).  This memory is 
  3503.  released when you close the file with CLOSE_INDEX_XB or issue EXIT_XB, or your 
  3504.  program terminates. 
  3505.  
  3506.  The OP.asMode has optional cache mode settings.  The caching modes cover 
  3507.  locality, write-through, and skip cache.  Locality is typically mostly random 
  3508.  (RND_LOCALITY), but may be mostly sequential if the data file has been sorted 
  3509.  and the index file recently reindexed and processing is mostly in-order (first 
  3510.  to last, rather than random).  Locality is used to tune the cache.  Also, 
  3511.  normally, data is written to the cache with control returning immediately to 
  3512.  the program before the disk is written (an asynchronous write).  To force the 
  3513.  write to take place before control is returned (a synchronous write), use the 
  3514.  WRITE_THROUGH mode.  To skip the cache completely, use the SKIP_CACHE mode. 
  3515.  This, as all OP.asMode settings, affects this file handle only. 
  3516.  
  3517.  BULLET has an optional external data mode where only indexing is done -- no 
  3518.  data file link is used.  In this mode, BULLET manages the index files of the 
  3519.  key and key data you provide (key data is any 32-bit item, e.g., a record 
  3520.  number, offset, etc.).  This would be useful for indexing non-DBF files, even 
  3521.  files with variable-length records.  Only those routines that do not access 
  3522.  the data file may be used (any routine using AP.recPtr, for example INSERT_XB, 
  3523.  could not be used, but NEXT_KEY_XB, STORE_KEY, etc., may). 
  3524.  
  3525.  
  3526. ΓòÉΓòÉΓòÉ 9.23. CLOSE_INDEX_XB ΓòÉΓòÉΓòÉ
  3527.  
  3528. Pack: HANDLEPACK               Source Example 
  3529.  
  3530.      IN               OUT
  3531.    HP.func          HP.stat
  3532.    HP.handle
  3533.  
  3534.  Close an open index file. 
  3535.  
  3536.  Closing the file updates the file header and releases the memory used by the 
  3537.  file.  Any outstanding locks should be unlocked before calling this routine. 
  3538.  
  3539.  Note:  Remaining locks belonging to this handle are released by the OS upon 
  3540.  the successful close. 
  3541.  
  3542.  
  3543. ΓòÉΓòÉΓòÉ 9.24. STAT_INDEX_XB ΓòÉΓòÉΓòÉ
  3544.  
  3545. Pack: STATINDEXPACK            Source Example 
  3546.  
  3547.      IN               OUT
  3548.    SIP.func         SIP.stat         SIP.keyLength
  3549.    SIP.handle       SIP.fileType     SIP.keyRecNo
  3550.                     SIP.flags        SIP.keyPtr
  3551.                     SIP.progress     SIP.herePtr
  3552.                     SIP.morePtr      SIP.codePage
  3553.                     SIP.xbLink       SIP.countryCode
  3554.                     SIP.asMode       SIP.CTptr
  3555.                     SIP.filenamePtr  SIP.nodeSize
  3556.                     SIP.fileID       SIP.sortFunction
  3557.                     SIP.keyExpPtr    SIP.lockCount
  3558.                     SIP.keys
  3559.  
  3560.  Return information BULLET has on the index file specified by SIP.handle. 
  3561.  
  3562.    Item             Description 
  3563.  stat               Return code of operation 
  3564.  fileType           0 for index, IX3 
  3565.  flags              Bit0=1 if file has changed since last flush (dirty) 
  3566.                     Bit1=1 if the file has its entire region locked (full lock) 
  3567.                     Bit2=1 if the file has a shared full-lock in use (cannot 
  3568.                     write to it if so) 
  3569.  progress           Percentage of reindex operation completed, 1-99, or 0 if 
  3570.                     done 
  3571.  morePtr            Always 0 
  3572.  xbLink             handle of the open DBF file this file indexes 
  3573.  asMode             Access-sharing-cache mode as specified at open 
  3574.  filenamePtr        Pointer to the filename as used in OPEN_INDEX_XB 
  3575.  fileID             '31ch' (the first four bytes of the file) 
  3576.  keyExpPtr          Pointer to the key expression used when the index was 
  3577.                     created 
  3578.  keys               Number of keys in the index file 
  3579.  keyLength          Length of the key, including 2-byte enumerator if 
  3580.                     DUPS_ALLOWED 
  3581.  keyRecNo           The DBF record number that the last accessed key indexes 
  3582.  keyPtr             Pointer to the last accessed key (valid for keyLength 
  3583.                     bytes) 
  3584.  herePtr            Pointer to the internal data control for this file 
  3585.  codePage           Code page used when the index file was created (the actual 
  3586.                     code page) 
  3587.  countryCode        Country code used when the index file was created (the 
  3588.                     actual country code) 
  3589.  CTptr              Pointer to the collate sequence table used for NLS sorting 
  3590.                     (each index file has its own sequence table) or NULL if not 
  3591.                     an NLS index 
  3592.  nodeSize           Size of an index node, 512, 1024, or 2048 bytes, as 
  3593.                     specified during create 
  3594.  sortFunction       The index sort-compare method (low word) and the sort flags 
  3595.                     (high word), with sort-compare values 1-9 being intrinsic, 
  3596.                     and 10-19 being custom functions; the DUPS_ALLOWED flag is 
  3597.                     bit0 of the high word (allowed if set) 
  3598.  lockCount          Number of full-locks in force (locked on first, unlocked on 
  3599.                     last) 
  3600.  
  3601.  Typically, your program tracks whether a particular handle belongs to an index 
  3602.  file or a data file.  In cases where this is not possible, call the 
  3603.  STAT_HANDLE_XB routine to determine what file type a handle is. 
  3604.  
  3605.  Note:  In network environments, you should have an exclusive lock on the index 
  3606.  file before using this routine to ensure that the information is current. 
  3607.  This routine is not mutex-protected.  During the call, the file handle must 
  3608.  not be closed by another thread. 
  3609.  
  3610.  
  3611. ΓòÉΓòÉΓòÉ 9.25. READ_INDEX_HEADER_XB ΓòÉΓòÉΓòÉ
  3612.  
  3613. Pack: HANDLEPACK               Source Example 
  3614.  
  3615.      IN               OUT
  3616.    HP.func          HP.stat
  3617.    HP.handle
  3618.  
  3619.  Reload the disk copy of the index header for the opened index file handle, 
  3620.  refreshing the in-memory copy. 
  3621.  
  3622.  Normally, this routine is not called directly but rather is done automatically 
  3623.  when you full-lock the file (LOCK_XB).  This routine does not refresh the 
  3624.  header if the current state is dirty (SIP.flags, bit0=1); it returns an error 
  3625.  if tried. Since it is recommended that a full-lock be in force before using 
  3626.  this routine (shared or exclusive), and since a full-lock always reloads the 
  3627.  header anyway, calling this routine should never be required.  If ever there 
  3628.  is a reason to use this routine without having a full-lock in force, then, of 
  3629.  course, you may need to.  However, it is not wise to reload the header without 
  3630.  a full-lock (which locks the header).  If you are using your own lock 
  3631.  routines, this call will be very useful. 
  3632.  
  3633.  In single-user, single-tasking systems this routine is not needed.  However, 
  3634.  in a multi-user or multi-tasking system it's possible, and desirable, for two 
  3635.  or more programs to use the same data file.  Consider this scenario: An index 
  3636.  file has 100 keys.  Two programs access this index file, both opening it. 
  3637.  Program 1 locks the file, adds a new key, then flushes and unlocks the file. 
  3638.  Program 1 knows that there are now 101 keys in the file.  However, Program 2 
  3639.  is not aware of the changes that Program 1 made--it thinks that there are 
  3640.  still 100 keys in the file.  This out-of-sync situation is easily remedied by 
  3641.  having Program 2 reload the index header from the file on disk. 
  3642.  
  3643.  How does Program 2 know that it needs to reload the header? It doesn't. 
  3644.  Instead, BULLET uses a simple, yet effective, approach when dealing with this. 
  3645.  When BULLET full-locks a file, it automatically reloads the header using this 
  3646.  routine.  When removing the full-lock, BULLET automatically flushes the header 
  3647.  using FLUSH_INDEX_HEADER_XB (unless the current lock is a shared lock 
  3648.  (SIP.flags bit2=1)). 
  3649.  
  3650.  
  3651. ΓòÉΓòÉΓòÉ 9.26. FLUSH_INDEX_HEADER_XB ΓòÉΓòÉΓòÉ
  3652.  
  3653. Pack: HANDLEPACK               Source Example 
  3654.  
  3655.      IN               OUT
  3656.    HP.func          HP.stat
  3657.    HP.handle
  3658.  
  3659.  Write the in-memory copy of the index header for the opened index file handle 
  3660.  to disk.  The actual write occurs only if the header has been changed. This 
  3661.  ensures that the index header on disk matches exactly the index header that is 
  3662.  being maintained by BULLET. 
  3663.  
  3664.  Normally, this routine is not called directly but rather is done automatically 
  3665.  when you unlock the file (UNLOCK_XB).  This routine does not write out the 
  3666.  header if the current lock state is shared (SIP.flags, bit2=1); it returns an 
  3667.  error if tried.  Unlocking a full-lock performs a flush automatically, and so 
  3668.  you may never need to explicitly call this routine.  Also, when relocking from 
  3669.  an exclusive full-lock to a shared full-lock, an automatic flush is performed. 
  3670.  
  3671.  Assume the following: An index file with 100 keys.  Your program opens the 
  3672.  index file and adds 1 key.  Physically, there are 101 keys on disk.  However, 
  3673.  the header image of the index file on disk still reads 100 keys.  This isn't a 
  3674.  problem; BULLET uses its in-memory copy of the index header and the in-memory 
  3675.  copy does read 101 keys.  But, if there were a system failure after the key 
  3676.  add, the disk image of the header would not get updated since the disk image 
  3677.  is written only on a CLOSE_ or FLUSH_INDEX_XB, or on EXIT_XB (and also prior 
  3678.  to REINDEX_XB).  After the system restarts, BULLET opens the file, reads the 
  3679.  header and thinks that there are 100 keys.  You lost a key.  Now, if after 
  3680.  that key was added, your program issues a FLUSH_INDEX_HEADER_XB, the header on 
  3681.  disk is refreshed with the in-memory copy, keeping the two in sync.  The 
  3682.  routine updates the directory entry, keeping things neat there as well (file 
  3683.  size).  Still, it doesn't come without cost: flushing will take additional 
  3684.  time, therefore, you may elect to flush periodically, or whenever the system 
  3685.  is idle. 
  3686.  
  3687.  Note:  You should have a full-lock on the file before using this routine. 
  3688.  
  3689.  
  3690. ΓòÉΓòÉΓòÉ 9.27. COPY_INDEX_HEADER_XB ΓòÉΓòÉΓòÉ
  3691.  
  3692. Pack: COPYPACK                 Source Example 
  3693.  
  3694.      IN               OUT
  3695.    CP.func          CP.stat
  3696.    CP.handle
  3697.    CP.filenamePtr
  3698.  
  3699.  Copy the index file structure of an open index file to another file. 
  3700.  
  3701.  This routine duplicates the structure of an existing index file without having 
  3702.  to re-specify the information needed by CREATE_INDEX_XB. The resultant index 
  3703.  file will be exactly like the source, including sort function and key 
  3704.  expression.  It contains 0 keys. 
  3705.  
  3706.  
  3707. ΓòÉΓòÉΓòÉ 9.28. ZAP_INDEX_HEADER_XB ΓòÉΓòÉΓòÉ
  3708.  
  3709. Pack: HANDLEPACK               Source Example 
  3710.  
  3711.      IN               OUT
  3712.    HP.func          HP.stat
  3713.    HP.handle
  3714.  
  3715.  Delete all keys from an index file. 
  3716.  
  3717.  This routine is similar to COPY_INDEX_HEADER_XB except for one major 
  3718.  difference: All keys in the source file are physically deleted. 
  3719.  
  3720.  If you have an index file with 100 keys and issue ZAP_INDEX_HEADER_XB, all 100 
  3721.  keys will be physically deleted and the file truncated to 0 keys. REINDEX_XB 
  3722.  can be used to rebuild the index file. 
  3723.  
  3724.  Note:  Since BULLET reindexes in place, the use of ZAP is not typically 
  3725.  needed. 
  3726.  
  3727.  
  3728. ΓòÉΓòÉΓòÉ 9.29. GET_DESCRIPTOR_XB ΓòÉΓòÉΓòÉ
  3729.  
  3730. Pack: DESCRIPTORPACK           Source Example 
  3731.  
  3732.      IN               OUT
  3733.    DP.func          DP.stat
  3734.    DP.handle        DP.fieldNumber
  3735.    DP.fieldNumber   DP.fieldOffset
  3736.         -or-        DP.FD.fieldName
  3737.    DP.FD.fieldName  DP.FD.fieldType
  3738.                     DP.FD.fieldLen
  3739.                     DP.FD.fieldDC
  3740.                     DP.FD.altFieldLength
  3741.  
  3742.  Get the field descriptor information for a field by fieldname or by field 
  3743.  position. 
  3744.  
  3745.  To get descriptor info by fieldname, set DP.fieldNumber=0 and set the 
  3746.  DP.FD.fieldname member to the fieldname string.  Fieldnames must be 
  3747.  0-terminated and 0-filled, and must be upper-case, with A-Z and _ valid 
  3748.  fieldname characters.  If the string matches a fieldname in the DBF descriptor 
  3749.  area, that field's descriptor info is returned in DP.FD, (FD is 
  3750.  FIELDDESCTYPE), and its position is returned in FD.fieldNumber and 
  3751.  FD.fieldOffset. 
  3752.  
  3753.  To get descriptor info by field position (i.e., field number), set 
  3754.  DP.fieldNumber to the field's position.  The first is field #1. The "delete 
  3755.  tag" field is not considered a field.  If the position is valid (i.e., greater 
  3756.  than 0 and not beyond the last field),that field's descriptor info is returned 
  3757.  in DP.FD. 
  3758.  
  3759.  This routine lets you work with unknown DBF files -- those created by another 
  3760.  program.  By reading each field descriptor, by number, from 1 to number of 
  3761.  fields (SDP.noFields), you can generate a run-time layout of the DBF file. 
  3762.  Alternatively, you can get input from your user for a fieldname, and locate 
  3763.  the descriptor by name. 
  3764.  
  3765.  Note:  If you need to add or delete a field, be sure to reindex all related 
  3766.  index files so that their key expressions can be re-evaluated. To do this, you 
  3767.  need to create a new data file and build it as you build any other new data 
  3768.  file.  Then, copy record-by-record from the old DBF to the new, using the old 
  3769.  record layout for reads, and the new record layout for writes.  After this, 
  3770.  reindex any index file related to the DBF file.  The old DBF file can then be 
  3771.  deleted. 
  3772.  
  3773.  If non-standard fields are used (i.e., non-char structure members to match 
  3774.  non-ASCII data fields in your non-standard DBF), then be aware that your 
  3775.  compiler more than likely will add padding to align on member-size boundaries. 
  3776.  This will result in a mis-match between your compiler structure and your DBF 
  3777.  structure (as described in fieldList[]).  To prevent this, place #pragma 
  3778.  pack(1) / #pragma pack() around your structures that BULLET uses.  Consult 
  3779.  your particular compiler for alternate methods if it does not support #pragma 
  3780.  pack. 
  3781.  
  3782.  
  3783. ΓòÉΓòÉΓòÉ 9.30. GET_RECORD_XB ΓòÉΓòÉΓòÉ
  3784.  
  3785. Pack: ACCESSPACK               Source Example 
  3786.  
  3787.      IN               OUT
  3788.    AP.func          AP.stat
  3789.    AP.handle        *AP.recPtr
  3790.    AP.recNo
  3791.    AP.recPtr
  3792.  
  3793.  Get the physical record from the data file into a data buffer. 
  3794.  
  3795.  The data buffer, pointed to by AP.recPtr, is typically a struct variable 
  3796.  defined as the DBF record itself is defined.  For example, if the DBF record 
  3797.  has 2 fields, LNAME and FNAME, each 25 characters, then then variable would be 
  3798.  typed as: 
  3799.  
  3800.   struct rectype {
  3801.    CHAR  tag;             /* The Xbase DBF delete tag (must be included) */
  3802.    CHAR  lastName[25];    /* same length as first field's descriptor fieldLen */
  3803.    CHAR  firstName[25];   /* same length as second field's descriptor fieldLen */
  3804.   }; /* 51 */
  3805.   struct rectype recbuff;
  3806.  
  3807.  The first record is at AP.recNo=1.  The last is SDP.records, determined by 
  3808.  STAT_DATA_XB.  The buffer must be at least as large as the record length 
  3809.  (SDP.recordLength). 
  3810.  
  3811.  This method of accessing the data file does not use any indexing.  Generally, 
  3812.  this access method is not used except for special purposes (sequential 
  3813.  processing where order is not required).  The preferred method to access the 
  3814.  data is by one of the keyed GET_XB routines. 
  3815.  
  3816.  If non-standard fields are used (i.e., non-char structure members to match 
  3817.  non-ASCII data fields in your non-standard DBF), then be aware that your 
  3818.  compiler more than likely will add padding to align on member-size boundaries. 
  3819.  This will result in a mis-match between your compiler structure (rectype 
  3820.  above) and your DBF structure (as described in fieldList[]).  To prevent this, 
  3821.  place #pragma pack(1) / #pragma pack() around your structures that BULLET 
  3822.  uses.  Consult your particular compiler for alternate methods if it does not 
  3823.  support #pragma pack. 
  3824.  
  3825.  
  3826. ΓòÉΓòÉΓòÉ 9.31. ADD_RECORD_XB ΓòÉΓòÉΓòÉ
  3827.  
  3828. Pack: ACCESSPACK               Source Example 
  3829.  
  3830.      IN               OUT
  3831.    AP.func          AP.stat
  3832.    AP.handle        AP.recNo
  3833.    AP.recPtr
  3834.  
  3835.  Append the data record in the data buffer to the end of the DBF file. 
  3836.  
  3837.  This method of adding a record involves no indexing.  It is typically used to 
  3838.  build a data file en masse.  Indexing is deferred until all records have been 
  3839.  added, and then quickly indexed using REINDEX_XB. 
  3840.  
  3841.  Since ADD_RECORD_XB is extremely fast, if you have several thousand data 
  3842.  records to be added at once, appending records with this routine and 
  3843.  reindexing when all have been added using REINDEX_XB is often faster than 
  3844.  using INSERT_XB for each record to add. 
  3845.  
  3846.  The record number assigned to the record appended is determined by BULLET, and 
  3847.  that record number is returned in AP.recNo. 
  3848.  
  3849.  If non-standard fields are used (i.e., non-char structure members to match 
  3850.  non-ASCII data fields in your non-standard DBF), then be aware that your 
  3851.  compiler more than likely will adding padding to align on member-size 
  3852.  boundaries.  This will result in a mis-match between your compiler structure 
  3853.  and your DBF structure (as described in fieldList[]).  To prevent this, place 
  3854.  #pragma pack(1) / #pragma pack() around your structures that BULLET uses. 
  3855.  Consult your particular compiler for alternate methods if it does not support 
  3856.  #pragma pack. 
  3857.  
  3858.  
  3859. ΓòÉΓòÉΓòÉ 9.32. UPDATE_RECORD_XB ΓòÉΓòÉΓòÉ
  3860.  
  3861. Pack: ACCESSPACK               Source Example 
  3862.  
  3863.      IN               OUT
  3864.    AP.func          AP.stat
  3865.    AP.handle
  3866.    AP.recNo
  3867.    AP.recPtr
  3868.  
  3869.  Write the updated data record to the physical record number. 
  3870.  
  3871.  This method of updating a data record must not be used if any field being used 
  3872.  as a key field (i.e., part of the key expression) is changed. 
  3873.  
  3874.  This method of updating a record is very fast if you know that that update is 
  3875.  not going to alter any field used as a key in any index file that uses it. You 
  3876.  must, of course, first get the data record into the record buffer.  You can 
  3877.  then change it, and write the update out to disk using this routine. 
  3878.  
  3879.  If you need to change a field that is used as a key field, or part of one 
  3880.  (e.g., SUBSTR()), use the UPDATE_XB routine. 
  3881.  
  3882.  If you plan on reindexing with REINDEX_XB immediately after using this 
  3883.  routine, you may elect to update the data file using this method even if 
  3884.  changing any field used as a key, rather than UPDATE_XB.  This since UPDATE_XB 
  3885.  is very disk intensive.  However, if transaction support is needed (i.e., 
  3886.  updates are dependent on other updates), then UPDATE_XB should be used. 
  3887.  
  3888.  
  3889. ΓòÉΓòÉΓòÉ 9.33. DELETE_RECORD_XB ΓòÉΓòÉΓòÉ
  3890.  
  3891. Pack: ACCESSPACK               Source Example 
  3892.  
  3893.      IN               OUT
  3894.    AP.func          AP.stat
  3895.    AP.handle
  3896.    AP.recNo
  3897.  
  3898.  Tag the record at the physical record number as being deleted. 
  3899.  
  3900.  This does not tag any in-memory copies of the record so be sure to mark any 
  3901.  such copies as being deleted yourself. 
  3902.  
  3903.  The first byte of every DBF record is reserved for the tag field.  This tag is 
  3904.  a space (ASCII 32) if the record is normal, or a * (ASCII 42) if it's marked 
  3905.  as being deleted.  This delete tag is a reserved field in the DBF record and 
  3906.  as such is not defined as a formal field with a descriptor.  Make sure that 
  3907.  you define your in-memory buffers to reserve the first byte for the delete 
  3908.  tag. 
  3909.  
  3910.  The Xbase DBF standard doesn't physically remove records marked as deleted 
  3911.  from the data file.  It doesn't mark them as available/reusable either.  To 
  3912.  physically remove records marked as deleted use PACK_RECORDS_XB 
  3913.  
  3914.  Records can be temporarily marked as deleted during processing and then 
  3915.  recalled to normal status when completed, useful for flagging a record as 
  3916.  having been processed (for example, mass updating using UPDATE_XB).  The 
  3917.  GET_XB routines return the record number associated with a key (in AP.recNo), 
  3918.  and that record number can be used for this routine. 
  3919.  
  3920.  While the DELETE_RECORD_XB and UNDELETE_RECORD_XB routines provided in BULLET 
  3921.  use the * and SPACE characters only, you can use whatever character you want 
  3922.  in the tag field when you fill your record buffer structure's data.  Normally, 
  3923.  you set the tag field to SPACE (x.tag = ' ';), but, for example, if you want 
  3924.  to implement your own, program-level locking you can use the tag field as a 
  3925.  marker to indicate the record is locked (by using an 'L' character, or ID with 
  3926.  bit7=1, or whatever you can think of) and use the very fast UPDATE_RECORD_XB 
  3927.  to set it.  Another possibility is set to aside a field to be used as this, 
  3928.  say, along with the user ID of the lock owner. 
  3929.  
  3930.  The SKIP_TAG_SELECT item in SET_SYSVARS_XB can be set to have the REINDEX_XB 
  3931.  routine not place a key value into the index file if a record has a matching 
  3932.  tag field.  This may be useful if you want to, say, generate an ad hoc index 
  3933.  for only undeleted records. 
  3934.  
  3935.  
  3936. ΓòÉΓòÉΓòÉ 9.34. UNDELETE_RECORD_XB ΓòÉΓòÉΓòÉ
  3937.  
  3938. Pack: ACCESSPACK               Source Example 
  3939.  
  3940.      IN               OUT
  3941.    AP.func          AP.stat
  3942.    AP.handle
  3943.    AP.recNo
  3944.  
  3945.  Tag the record at the physical record number as being normal (not deleted). 
  3946.  
  3947.  This does not tag any in-memory copies of the record so be sure to mark any 
  3948.  such copies as being normal. 
  3949.  
  3950.  This routine removes the * character, as put there by DELETE_RECORD_XB, in the 
  3951.  tag field and replaces it with a SPACE.  The tag field is always overwritten 
  3952.  with a SPACE, regardless of what it was. 
  3953.  
  3954.  
  3955. ΓòÉΓòÉΓòÉ 9.35. DEBUMP_RECORD_XB ΓòÉΓòÉΓòÉ
  3956.  
  3957. Pack: ACCESSPACK               Source Example 
  3958.  
  3959.      IN               OUT
  3960.    AP.func          AP.stat
  3961.    AP.handle
  3962.    AP.recNo
  3963.  
  3964.  Remove the record identified by AP.recNo from the data file if and only if the 
  3965.  record is the last in the file.  The file is automatically flushed before 
  3966.  debumping. 
  3967.  
  3968.  Unlike DELETE_RECORD_XB, this routine physically removes a data record from 
  3969.  the DBF file, provided that the record to delete is the last. STAT_DATA_XB can 
  3970.  be used to identify the last record number (SDP.records is the last).  This, 
  3971.  when used after deleting any and all keys in all index files referencing this 
  3972.  record (see DELETE_KEY_XB), is useful if you are managing a transaction log 
  3973.  and need to back out changes made, beyond what BULLET performs. 
  3974.  
  3975.  If the record is not the last, alternate methods must be used. The simplest, 
  3976.  and often equally as good as physically deleting the record, is to just mark 
  3977.  the record as deleted using DELETE_RECORD_XB and let it remain in the file 
  3978.  until the next PACK_RECORDS_XB.  Another option is to overwrite the record's 
  3979.  data with SPACES, or other appropriate field data (such as HIGH-VALUES, and 
  3980.  use UPDATE_XB), if necessary.  This routine is the only method available to 
  3981.  physically remove a record from the file, short of using PACK_RECORDS_XB. 
  3982.  Removing a record with active keys referencing that record will result in an 
  3983.  access error (ERR_UNEXPECTED_EOF) when accessing that key with GET_XB 
  3984.  routines, or will generate stale results.  Remove any keys that reference this 
  3985.  record before deleting it. 
  3986.  
  3987.  
  3988. ΓòÉΓòÉΓòÉ 9.36. PACK_RECORDS_XB ΓòÉΓòÉΓòÉ
  3989.  
  3990. Pack: ACCESSPACK               Source Example 
  3991.  
  3992.      IN               OUT
  3993.    AP.func          AP.stat
  3994.    AP.handle
  3995.  
  3996.  Rebuild the open DBF file by physically removing all records marked as 
  3997.  deleted. 
  3998.  
  3999.  Packing occurs in place using the existing file.  It is recommended that you 
  4000.  use BACKUP_FILE_XB to copy the current DBF file before using this routine in 
  4001.  case of a failure during the pack process. 
  4002.  
  4003.  The newly packed file is truncated to reflect the current, actual size.  All 
  4004.  records with the tag field set to * are removed from the file. 
  4005.  
  4006.  If there are index files for this DBF file, they must be reindexed after the 
  4007.  pack process by using REINDEX_XB. 
  4008.  
  4009.  Memo files are not affected by this routine.  Before packing, it is 
  4010.  recommended that you traverse the data file to be packed, and for records that 
  4011.  are to be deleted, check to see if there is a memo record. If there is, delete 
  4012.  the memo.  Do this for each such occurrence.  This way, orphaned memo records 
  4013.  will not take up permanent space in the memo file. 
  4014.  
  4015.  
  4016. ΓòÉΓòÉΓòÉ 9.37. GET_MEMO_SIZE_XB ΓòÉΓòÉΓòÉ
  4017.  
  4018. Pack: MEMODATAPACK             Source Example 
  4019.  
  4020.      IN               OUT
  4021.    MDP.func         MDP.stat
  4022.    MDP.dbfHandle    MDP.memoBytes
  4023.    MDP.memoNo
  4024.  
  4025.  Get the number of bytes used by the memo at MDP.memoNo. 
  4026.  
  4027.  Memo file allocation is made in blocks, typically of 512 bytes each. 
  4028.  Therefore, a memo of 10 bytes uses 1 allocation block, as would a 500-byte 
  4029.  memo.  This size is stored with each memo record, and can be retrieved. 
  4030.  Before accessing a memo record, it's a good idea to retrieve the current size 
  4031.  of the memo so you know how large a buffer you may need if you intend to read 
  4032.  it all in, at one time, or even to just know how much to read, in total, 
  4033.  reading parts of it at a time. 
  4034.  
  4035.  The first memo is at MDP.memoNo=1.  The last memo number cannot be easily 
  4036.  determined, but generally this does not need to be known.  The memo number 
  4037.  identifying the memo's location is stored in the memo field area of the DBF 
  4038.  record.  It is stored as a text string (e.g., "0000000001").  This is not a C 
  4039.  string; there is no zero terminator so sprintf() should be used.  This number 
  4040.  is the physical block number at which the memo starts.  Memos are always 
  4041.  stored in consecutive blocks, if more than a single block is needed.  For 
  4042.  example, a memo of 513 bytes uses two blocks, say, #1 and #2.  The next memo 
  4043.  added would use memo #3 (if #3 is available), rather than #2 since #2 was used 
  4044.  by the first memo.  Memo numbers may be reassigned (see UPDATE_MEMO_XB).  The 
  4045.  highest possible memo number is 589,822 (0x8FFFE).  With the standard 512-byte 
  4046.  block size, this allows a memo file to be up to 288MB.  If more memo data 
  4047.  space is needed, use a larger block size (e.g., 2KB block size allows over 1GB 
  4048.  per memo file). 
  4049.  
  4050.  Notice For All Memo Routines 
  4051.  
  4052.  In multitasking environments you should have a full-lock on the DBF file that 
  4053.  owns this memo file, or at least a record lock on the record that owns the 
  4054.  memo number.  In BULLET, locking is not performed on the memo file.  Instead, 
  4055.  the lock is implied when the lock is made on the DBF file.  This because a 
  4056.  memo file is for one DBF file alone, and so if you have a lock on the DBF 
  4057.  before accessing the memo file (for whatever reason), then no other process 
  4058.  may lock the DBF and also access the memo. 
  4059.  
  4060.  This works only if you restrict your access to the memo file if you have a 
  4061.  lock on the DBF master file (the DBF that this DBT memo file belongs to) or on 
  4062.  the DBF record.  For this routine, which only requires access to this memo 
  4063.  record, a record lock is sufficient since no writing is performed.  Further, a 
  4064.  shared lock is all that is required.  This because all that is required to 
  4065.  keep from stepping on other process's toes is that it be known that the 
  4066.  current memo header info (for this memo record), as known to this process, is 
  4067.  the current state of this memo.  In other words, it must be true that the memo 
  4068.  file state on disk exactly matches the memo file state in memory.  With a lock 
  4069.  in place, no other process may gain write access to change this memo, "out 
  4070.  from under you".  A shared lock does allow the other process to read this 
  4071.  memo, and that may be used if no writing is needed. 
  4072.  
  4073.  Each memo routine following states its lock requirements (exclusive full lock, 
  4074.  shared full lock, exclusive record lock, or shared record lock). 
  4075.  
  4076.  
  4077. ΓòÉΓòÉΓòÉ 9.38. GET_MEMO_XB ΓòÉΓòÉΓòÉ
  4078.  
  4079. Pack: MEMODATAPACK             Source Example 
  4080.  
  4081.      IN               OUT
  4082.    MDP.func         MDP.stat
  4083.    MDP.dbfHandle    *MDP.memoPtr
  4084.    MDP.memoNo       MDP.memoBytes
  4085.    MDP.memoPtr
  4086.    MDP.memoOffset
  4087.    MDP.memoBytes
  4088.  
  4089.  Read the specified number of bytes of the memo, starting at the offset, into 
  4090.  the buffer.  The actual number of bytes read is returned. 
  4091.  
  4092.  Use GET_MEMO_SIZE_XB to determine that total number of bytes you may need to 
  4093.  read.  With that, you can allocate a buffer of that size to read the entire 
  4094.  memo into.  Or, you can read chunks of the memo, a chunk at a time, up to the 
  4095.  number of bytes in the memo. 
  4096.  
  4097.  The number of bytes actually read (and stored starting at MDP.memoPtr) is 
  4098.  returned in MDP.memoBytes (overwriting the value you placed there).  If the 
  4099.  number of bytes requested is not the same as the number of bytes returned, you 
  4100.  attempted to read beyond the end of the memo.  BULLET does not return an error 
  4101.  if you try this, which is SOP for file reads, so check the two if you need to 
  4102.  verify this.  An error is returned, however, if you attempt to read at a 
  4103.  starting offset beyond the end of the actual memo data (i.e., MDP.memoOffset > 
  4104.  memo's data size).  The first byte of the memo data is at .memoOffset=0. 
  4105.  
  4106.  It's recommended that a lock be in force on either the DBF (full-lock) or on 
  4107.  the record that this memo belongs to.  A shared lock is okay since no writing 
  4108.  is done. 
  4109.  
  4110.  
  4111. ΓòÉΓòÉΓòÉ 9.39. ADD_MEMO_XB ΓòÉΓòÉΓòÉ
  4112.  
  4113. Pack: MEMODATAPACK             Source Example 
  4114.  
  4115.      IN               OUT
  4116.    MDP.func         MDP.stat
  4117.    MDP.dbfHandle    MDP.memoNo
  4118.    MDP.memoPtr
  4119.    MDP.memoBytes
  4120.  
  4121.  Add the data from the buffer for the specified bytes to a new memo.  The memo 
  4122.  number used is returned. 
  4123.  
  4124.  Any data can be stored in a memo.  The memo number returned can be any value; 
  4125.  it can even be less than the previous add's memo number.  The reason for this 
  4126.  is that an avail-list is kept for the memo file, and any deleted or otherwise 
  4127.  freed blocks become available for re-use.  The memo is stored in the first 
  4128.  contiguous group of free blocks large enough to satisfy the request.  For 
  4129.  example, if MDP.memoBytes is from 1 to (blockSize-8) bytes, the first 
  4130.  available block is used.  If the size needed is greater than 1 block, then the 
  4131.  avail-list is walked and the first contiguous group large enough to satisfy 
  4132.  the request is used.  If none of the avail-list groups is large enough, 
  4133.  ultimately, the new memo data is appended to the end of the file.  This is 
  4134.  also done if there are no avail-list items at all, such as in a memo file that 
  4135.  has never had deletes or updates. 
  4136.  
  4137.  The returned memo is a binary block number (ULONG).  This value should be 
  4138.  converted into an ASCII string (sprintf can be used) and stored in the DBF 
  4139.  data record, in the memo field.  The string should be of the form, 
  4140.  "0000000001" (for MDP.memoNo=1), with leading zeros, but no zero terminator 
  4141.  (exactly 10 bytes in size).  This data record should then be written to disk 
  4142.  using UPDATE_RECORD_XB. Since BULLET can be used in non-standard Xbase mode, 
  4143.  where binary field values can be used, you can omit the conversion from binary 
  4144.  to ASCII if a standard DBF is not required.  Likewise, when accessing a memo, 
  4145.  the conversion of the memo block number from ASCII to binary would not be 
  4146.  required. 
  4147.  
  4148.  It's recommended that a lock be in force on the DBF (full-lock).  A shared 
  4149.  lock may not be used since writing to the memo file, and the DBF record, is 
  4150.  required.  A full lock is required since the memo file header is read and 
  4151.  written. 
  4152.  
  4153.  
  4154. ΓòÉΓòÉΓòÉ 9.40. UPDATE_MEMO_XB ΓòÉΓòÉΓòÉ
  4155.  
  4156. Pack: MEMODATAPACK             Source Example 
  4157.  
  4158.      IN               OUT
  4159.    MDP.func         MDP.stat
  4160.    MDP.dbfHandle    MDP.memoNo
  4161.    MDP.memoNo
  4162.    MDP.memoPtr
  4163.    MDP.memoOffset
  4164.    MDP.memoBytes
  4165.  
  4166.  Update an existing memo.  The update can overwrite current data, append new 
  4167.  data extending the current size, or it can shrink the current size. 
  4168.  
  4169.  Appending data so that the memo is extended may result in a new memo number 
  4170.  returned.  The original memo blocks are made available for reuse (deleted). 
  4171.  Shrinking will not change the memo number, but unused blocks from the shrink 
  4172.  are made available for reuse. 
  4173.  
  4174.  If you want to change anything in the memo at MDP.memoNo, locate its position 
  4175.  within the memo with MDP.memoOffset and set the size in MDP.memoBytes. The 
  4176.  first data byte of a memo is located at MDP.offset=0.  There are 8 bytes of 
  4177.  overhead per memo record (any number of blocks still has only the 8 bytes of 
  4178.  overhead), but these are transparent to any memo access you do. The bytes at 
  4179.  MDP.memoPtr overwrite the current memo data at the position specified.  For 
  4180.  example, if you want to change the first 5 bytes of the first memo, set 
  4181.  MDP.memoNo=1, MDP.memoPtr=yourNewData, MDP.memoOffset=0, and MDP.memoBytes=5. 
  4182.  On return, MDP.memoNo is going to be the same as it was before the update, 
  4183.  since you are not extending the memo size in this example.  Nothing further 
  4184.  needs to be done; the memo is updated. 
  4185.  
  4186.  If you want to add new memo data to an existing memo at MDP.memoNo, such as 
  4187.  adding another line item, or problem report paragraph, etc., set 
  4188.  MDP.memoOffset=theCurrentMemoSize (this locates to the end of the current memo 
  4189.  data), MDP.memoBytes=bytesYouWantToAppend, and MDP.memoPtr=yourDataToAppend. 
  4190.  If the old data size plus your newly added data still fits inside the last 
  4191.  memo block previously used, MDP.memoNo is returned the same as it was on 
  4192.  entry.  However, if the new data requires that more blocks be allocated, the 
  4193.  entire memo is relocated to the next contiguous block group that is large 
  4194.  enough to store the data.  That new block number is returned in MDP.memoNo, 
  4195.  and the old block number and all its blocks are placed on the top of the 
  4196.  avail-list. 
  4197.  
  4198.  If you want to shrink the size as reported by GET_MEMO_SIZE_XB from an 
  4199.  existing memo at MDP.memoNo, set MDP.memoBytes=newSizeYouWant, and 
  4200.  MDP.memoPtr=NULL.  This means that you should have, before making this shrink 
  4201.  call, updated the memo data that occurs within this new size to be the data 
  4202.  size you want to be in the memo.  For example, if you have 10 line items, say, 
  4203.  each 60 bytes long, and want to remove line item #5, you could do it by 
  4204.  reading all 10 line items to memory, moving line items #6 to 10 down one (so 
  4205.  they are now line items #5 to 9, effectively removing old line item #5), and 
  4206.  update the memo (by using memoOffset=0 and memoBytes=9*60).  After this, 
  4207.  though, you still have 10*60 bytes as the memo size (old line item #10 is now 
  4208.  at #9 and still at #10).  Since you want the size to reflect the real data in 
  4209.  the memo, set MDP.memoBytes=90, MDP.memoPtr=NULL, and update this memo number. 
  4210.  Only the memo's size is affected by this particular update.  The size 
  4211.  specified must be smaller than the original size, or an error is returned. 
  4212.  
  4213.  It's recommended that a lock be in force on the DBF (full-lock).  A record 
  4214.  lock should not be used if the update may result in blocks being moved, or the 
  4215.  memo being shrunk by a full block or more.  A shared lock may not be used 
  4216.  since writing to the memo file, and to the DBF record if MDP.memoNo is new, is 
  4217.  required. 
  4218.  
  4219.  
  4220. ΓòÉΓòÉΓòÉ 9.41. DELETE_MEMO_XB ΓòÉΓòÉΓòÉ
  4221.  
  4222. Pack: MEMODATAPACK             Source Example 
  4223.  
  4224.      IN               OUT
  4225.    MDP.func         MDP.stat
  4226.    MDP.dbfHandle
  4227.    MDP.memoNo
  4228.  
  4229.  The memo and all its blocks are made available for reuse. 
  4230.  
  4231.  Before using PACK_RECORDS_XB, you should run through all DBF records and check 
  4232.  for those records that are deleted (record.tag='*') to be sure that any memo 
  4233.  belong to those records are deleted from the memo file.  If this is not done, 
  4234.  orphaned memo records -- those that do not have a DBF record memo field 
  4235.  pointing to it, may be left in the memo file (forever!). 
  4236.  
  4237.  After deleting a memo record, update the DBF record's memo field by writing 
  4238.  <SPACES> (ASCII 32) to the memo field member.  Update this to disk with 
  4239.  UPDATE_RECORD_XB as soon as possible (and before unlocking).  A memo field 
  4240.  with no current memo record is indicated by spaces ("0000000000" should not be 
  4241.  used). 
  4242.  
  4243.  It's recommended that a lock be in force on the DBF (full-lock).  Neither a 
  4244.  record lock nor a shared lock may be used since writing to the memo file 
  4245.  header and the DBF record is required. 
  4246.  
  4247.  
  4248. ΓòÉΓòÉΓòÉ 9.42. MEMO_BYPASS_XB ΓòÉΓòÉΓòÉ
  4249.  
  4250. Pack: MEMODATAPACK             Source Example 
  4251.  
  4252.      IN               OUT
  4253.    MDP.func         MDP.stat
  4254.    MDP.dbfHandle
  4255.    MDP.memoBypass
  4256.  
  4257.  Memo files are created, opened, closed, and flushed/reloaded by their 
  4258.  corresponding DBF data file action.  To perform these tasks asynchronously, 
  4259.  this routine is used.  Bypass routines are: 
  4260.  
  4261.      MDP.memoBypass      Value
  4262.    BYPASS_CREATE_MEMO        1
  4263.    BYPASS_OPEN_MEMO          2
  4264.    BYPASS_CLOSE_MEMO         3
  4265.    BYPASS_READ_MEMO_HEADER   4
  4266.    BYPASS_FLUSH_MEMO_HEADER  5
  4267.  
  4268.  All bypass routines require the handle of the DBF file that this memo is for. 
  4269.  Nothing is returned here, except the result code.  The memo handle from the 
  4270.  open is stored internally, but is available by using STAT_DATA_XB and checking 
  4271.  SDP.memoHandle.  However, none of the BULLET memo routines use the memo handle 
  4272.  directly; all access to the memo file is through the master DBF file handle. 
  4273.  
  4274.  No data is required for input other than the DBF handle and memo bypass 
  4275.  routine to perform (see table above).  All required info is obtained from the 
  4276.  DBF file's information.  You may use an alternate block size, as set via 
  4277.  SET_SYSVARS_XB. 
  4278.  
  4279.  Generally, there is no need to call these routines using this bypass. However, 
  4280.  if you need to create a memo file anew (say, after the initial DBF was 
  4281.  created), and then open it, using these routines is the easiest way to 
  4282.  proceed. 
  4283.  
  4284.  Note:  When creating a memo via the bypass method, the file ID is altered to 
  4285.  indicate that the DBF has a DBT memo file.  The file ID is the first byte of 
  4286.  the DBF file.  The ID is changed by OR'ing 0x88h with the current file ID 
  4287.  value.  The next flush or close updates the disk image of the DBF with the new 
  4288.  file ID.  The next DBF open, then, also opens the DBT memo file created here. 
  4289.  Be sure to always keep the DBT and DBF pairs in the same directory, if moved. 
  4290.  
  4291.  Since the DBF file is already open (and must be to use any of these routines), 
  4292.  you must use the open bypass routine to open the memo if you plan on using it. 
  4293.  Either that, or close the DBF after you've create the memo file, and simply 
  4294.  re-open the DBF, which also, now, opens the DBT memo file. 
  4295.  
  4296.  The other available bypass routines: close, read, and flush, typically will 
  4297.  not be used from this bypass routine.  These operations are done automatically 
  4298.  when their corresponding DBF action is performed, and have little 
  4299.  functionality used on their own. 
  4300.  
  4301.  Before using BYPASS_READ_MEMO_HEADER or BYPASS_FLUSH_MEMO_HEADER, it's 
  4302.  recommended that a lock be in force on the DBF (full-lock). A shared lock can 
  4303.  be used for BYPASS_READ_MEMO_HEADER, but it must be a full lock. 
  4304.  
  4305.  
  4306. ΓòÉΓòÉΓòÉ 9.43. FIRST_KEY_XB ΓòÉΓòÉΓòÉ
  4307.  
  4308. Pack: ACCESSPACK               Source Example 
  4309.  
  4310.      IN               OUT
  4311.    AP.func          AP.stat
  4312.    AP.handle        AP.recNo
  4313.    AP.keyPtr        *AP.keyPtr
  4314.  
  4315.  Retrieve the first key in index order from the index file. 
  4316.  
  4317.  This routine does not access the DBF file and so does not retrieve the data 
  4318.  record.  What it does do is locate the first logical key of the index file, 
  4319.  returning it, and also returning the record number within the DBF that the key 
  4320.  indexes. 
  4321.  
  4322.  To retrieve the data record you can use the GET_RECORD_XB routine.  The 
  4323.  preferred method, however, is to use GET_FIRST_XB, which combines these 
  4324.  operations. 
  4325.  
  4326.  The key returned includes an enumerator if the index file allows duplicate 
  4327.  keys. 
  4328.  
  4329.  This routine is typically used to position the index file to the first key so 
  4330.  as to allow forward in-order access to the keys by using NEXT_KEY_XB. 
  4331.  
  4332.  If an external data file was specified in CREATE_INDEX_XB, the record number 
  4333.  returned by this routine does not refer to a DBF record, but rather is the 
  4334.  value supplied when the key was stored.  This permits index access to your 
  4335.  data files (data files which are not maintained by BULLET, but by you). 
  4336.  
  4337.  
  4338. ΓòÉΓòÉΓòÉ 9.44. EQUAL_KEY_XB ΓòÉΓòÉΓòÉ
  4339.  
  4340. Pack: ACCESSPACK               Source Example 
  4341.  
  4342.      IN               OUT
  4343.    AP.func          AP.stat
  4344.    AP.handle        AP.recNo
  4345.    AP.keyPtr
  4346.  
  4347.  Search for the exact key in the index file. 
  4348.  
  4349.  This routine does not access the DBF file and so does not retrieve the data 
  4350.  record.  What it does do is search for the key in the index, and if found, 
  4351.  returns the record number within the DBF that the key indexes.  The key must 
  4352.  be an exact match, including the enumerator word if the index file is using 
  4353.  non-unique keys. 
  4354.  
  4355.  To retrieve the data record you can use the GET_RECORD_XB routine.  The 
  4356.  preferred method, however, is to use GET_EQUAL_XB, which combines these 
  4357.  operations. 
  4358.  
  4359.  This routine returns no key in *keyPtr since, by definition, you already have 
  4360.  the key in the key buffer if this routine succeeds. 
  4361.  
  4362.  This routine finds only an exact match to the specified key (including the 
  4363.  enumerator if applicable). 
  4364.  
  4365.  
  4366. ΓòÉΓòÉΓòÉ 9.45. EQUAL_OR_GREATER_KEY_XB ΓòÉΓòÉΓòÉ
  4367.  
  4368. Pack: ACCESSPACK               Source Example 
  4369.  
  4370.      IN               OUT
  4371.    AP.func          AP.stat
  4372.    AP.handle        AP.recNo
  4373.    AP.keyPtr        *AP.keyPtr
  4374.  
  4375.  Search for the exact key in the index file and, if not found, get the key that 
  4376.  would have followed it. 
  4377.  
  4378.  This routine is similar to EQUAL_KEY_XB except that this routine returns a key 
  4379.  in *keyPtr (either the same as on entry, or if that is not found, then the 
  4380.  next greater key). 
  4381.  
  4382.  The main benefit of this routine is that it is an atomic operation. It differs 
  4383.  from setting the atomic mode flag of SET_SYSVARS_XB in that this routine 
  4384.  allows a fuzzy starting point:  the key in AP.keyPtr, on entry (IN), need not 
  4385.  exist. 
  4386.  
  4387.  
  4388. ΓòÉΓòÉΓòÉ 9.46. EQUAL_OR_LESSER_KEY_XB ΓòÉΓòÉΓòÉ
  4389.  
  4390. Pack: ACCESSPACK               Source Example 
  4391.  
  4392.      IN               OUT
  4393.    AP.func          AP.stat
  4394.    AP.handle        AP.recNo
  4395.    AP.keyPtr        *AP.keyPtr
  4396.  
  4397.  Search for the exact key in the index file and, if not found, get the key that 
  4398.  would have come before it. 
  4399.  
  4400.  This routine is similar to EQUAL_KEY_XB except that this routine returns a key 
  4401.  in *keyPtr (either the same as on entry, or if that is not found, then the 
  4402.  previous, lesser key). 
  4403.  
  4404.  The main benefit of this routine is that it is an atomic operation. It differs 
  4405.  from setting the atomic mode flag of SET_SYSVARS_XB in that this routine 
  4406.  allows a fuzzy starting point:  the key in AP.keyPtr, on entry (IN), need not 
  4407.  exist. 
  4408.  
  4409.  
  4410. ΓòÉΓòÉΓòÉ 9.47. NEXT_KEY_XB ΓòÉΓòÉΓòÉ
  4411.  
  4412. Pack: ACCESSPACK               Source Example 
  4413.  
  4414.      IN               OUT
  4415.    AP.func          AP.stat
  4416.    AP.handle        AP.recNo
  4417.    AP.keyPtr        *AP.keyPtr
  4418.  
  4419.  Retrieve the next key in index order from the index file. 
  4420.  
  4421.  This routine does not access the DBF file and so does not retrieve the data 
  4422.  record.  What it does do is retrieve the next key of the index, returning it, 
  4423.  and also returning the record number within the DBF that the key indexes. 
  4424.  
  4425.  To retrieve the data record you can use the GET_RECORD_XB routine.  The 
  4426.  preferred method, however, is to use GET_NEXT_XB, which combines these 
  4427.  operations. 
  4428.  
  4429.  The key returned includes an enumerator if the index file allows duplicates. 
  4430.  
  4431.  This routine is typically called after the index file has first been 
  4432.  positioned to a known key using either FIRST_KEY_XB or EQUAL_KEY_XB, or after 
  4433.  a previous NEXT_KEY_XB or even PREV_KEY_XB.  What it basically does is get the 
  4434.  key following the current key, and then makes that key the new current key. ________________________________________________
  4435.  
  4436.  If bit0 of the atomic mode flag of SET_SYSVARS_XB is set to 1, key access is 
  4437.  based on a given starting point.  This simplifies index access in 
  4438.  multi-threaded code, where another thread may have altered the last key 
  4439.  accessed in the index file.  This mode lets you set a starting point for the 
  4440.  operation by supplying in AP.keyPtr the key value to start at. 
  4441.  
  4442.  For example, say you use GET_FIRST_XB.  On return, AP.keyPtr has the the very 
  4443.  first key.  Say elsewhere in your multi-threaded program, another operation 
  4444.  accesses that same index file handle, and performs some other access, where 
  4445.  the last accessed key is no longer the same (i.e., not the first key).  Your 
  4446.  first thread is expecting that a GET_NEXT_XB would get the second key, 
  4447.  however, it very likely won't since the second thread has altered the last 
  4448.  accessed key for that file handle.  By using the atomic mode for key access, 
  4449.  your first thread, which has the first key value in its AP.keyPtr, can do a 
  4450.  call to GET_NEXT_XB and get expected results, since the NEXT operation first 
  4451.  positions to the value in AP.keyPtr and then follows up with a GET_NEXT 
  4452.  operation.  This is performed within the Bullet kernel, and so won't be 
  4453.  interrupted by another thread (i.e., it is an atomic operation).  For this to 
  4454.  work, you must ensure that the AP.keyPtr value is set to the value of the last 
  4455.  accessed key.  This will always be the case unless uninitialized, or you are 
  4456.  using global variables for your threads' AP (AccessPack).  On return from the 
  4457.  operation, AP.keyPtr will once again be set up for another atomic operation. 
  4458.  
  4459.  Note:  You must supply a valid key value for this atomic access mode. 
  4460.  AP.keyPtr must be at least as large as the key length in all cases, and is to 
  4461.  have the starting point for the operation (i.e., the last accessed key).  You 
  4462.  may, alternatively, set the first byte of the key buffer to 0 (but not 
  4463.  AP.keyPtr itself to NULL).  This disables atomic mode for that access, and 
  4464.  reverts to the internally-stored last key accessed as the starting point. 
  4465.  
  4466.  
  4467. ΓòÉΓòÉΓòÉ 9.48. PREV_KEY_XB ΓòÉΓòÉΓòÉ
  4468.  
  4469. Pack: ACCESSPACK               Source Example 
  4470.  
  4471.      IN               OUT
  4472.    AP.func          AP.stat
  4473.    AP.handle        AP.recNo
  4474.    AP.keyPtr        *AP.keyPtr
  4475.  
  4476.  Retrieve the previous key in index order from the index file. 
  4477.  
  4478.  This routine does not access the DBF file and so does not retrieve the data 
  4479.  record.  What it does do is retrieve the previous key of the index, returning 
  4480.  it and also returning the record number within the DBF that the key indexes. 
  4481.  
  4482.  To retrieve the data record you can use the GET_RECORD_XB routine.  The 
  4483.  preferred method, however, is to use GET_PREV_XB, which combines these 
  4484.  operations. 
  4485.  
  4486.  The key returned includes an enumerator if the index file allows duplicates. 
  4487.  
  4488.  This routine is typically called after the index file has first been 
  4489.  positioned to a known key using either LAST_KEY_XB or EQUAL_KEY_XB, or after a 
  4490.  previous PREV_KEY_XB or even NEXT_KEY_XB.  What it basically does is to get 
  4491.  the key previous the current key, and then make that key the new current key. ________________________________________________
  4492.  
  4493.  If bit0 of the atomic mode flag of SET_SYSVARS_XB is set to 1, key access is 
  4494.  based on a given starting point.  This simplifies index access in 
  4495.  multi-threaded code, where another thread may have altered the last key 
  4496.  accessed in the index file.  This mode lets you set a starting point for the 
  4497.  operation by supplying in AP.keyPtr the key value to start at. 
  4498.  
  4499.  For example, say you use GET_FIRST_XB.  On return, AP.keyPtr has the the very 
  4500.  first key.  Say elsewhere in your multi-threaded program, another operation 
  4501.  accesses that same index file handle, and performs some other access, where 
  4502.  the last accessed key is no longer the same (i.e., not the first key).  Your 
  4503.  first thread is expecting that a GET_NEXT_XB would get the second key, 
  4504.  however, it very likely won't since the second thread has altered the last 
  4505.  accessed key for that file handle.  By using the atomic mode for key access, 
  4506.  your first thread, which has the first key value in its AP.keyPtr, can do a 
  4507.  call to GET_NEXT_XB and get expected results, since the NEXT operation first 
  4508.  positions to the value in AP.keyPtr and then follows up with a GET_NEXT 
  4509.  operation.  This is performed within the Bullet kernel, and so won't be 
  4510.  interrupted by another thread (i.e., it is an atomic operation).  For this to 
  4511.  work, you must ensure that the AP.keyPtr value is set to the value of the last 
  4512.  accessed key.  This will always be the case unless uninitialized, or you are 
  4513.  using global variables for your threads' AP (AccessPack).  On return from the 
  4514.  operation, AP.keyPtr will once again be set up for another atomic operation. 
  4515.  
  4516.  Note:  You must supply a valid key value for this atomic access mode. 
  4517.  AP.keyPtr must be at least as large as the key length in all cases, and is to 
  4518.  have the starting point for the operation (i.e., the last accessed key).  You 
  4519.  may, alternatively, set the first byte of the key buffer to 0 (but not 
  4520.  AP.keyPtr itself to NULL).  This disables atomic mode for that access, and 
  4521.  reverts to the internally-stored last key accessed as the starting point. 
  4522.  
  4523.  
  4524. ΓòÉΓòÉΓòÉ 9.49. LAST_KEY_XB ΓòÉΓòÉΓòÉ
  4525.  
  4526. Pack: ACCESSPACK               Source Example 
  4527.  
  4528.      IN               OUT
  4529.    AP.func          AP.stat
  4530.    AP.handle        AP.recNo
  4531.    AP.keyPtr        *AP.keyPtr
  4532.  
  4533.  Retrieve the last key in index order from the index file. 
  4534.  
  4535.  This routine does not access the DBF file and so does not retrieve the data 
  4536.  record.  What it does do is locate the last key of the index, returning it, 
  4537.  and also returning the record number within the DBF that the key indexes. 
  4538.  
  4539.  To retrieve the data record you can use the GET_RECORD_XB routine.  The 
  4540.  preferred method, however, is to use GET_LAST_XB, which combines these 
  4541.  operations. 
  4542.  
  4543.  The key returned includes an enumerator if the index file allows duplicates. 
  4544.  
  4545.  This routine is typically used to position the index file to the last key so 
  4546.  as to allow reverse in-order access to the keys by using PREV_KEY_XB. 
  4547.  
  4548.  
  4549. ΓòÉΓòÉΓòÉ 9.50. STORE_KEY_XB ΓòÉΓòÉΓòÉ
  4550.  
  4551. Pack: ACCESSPACK               Source Example 
  4552.  
  4553.      IN               OUT
  4554.    AP.func          AP.stat
  4555.    AP.handle
  4556.    AP.recNo
  4557.    AP.keyPtr
  4558.  
  4559.  Insert the key into the index file in proper key order. 
  4560.  
  4561.  This routine does not add the data record to the DBF file.  It only inserts 
  4562.  the key and record number into the index file.  Use INSERT_XB instead. 
  4563.  
  4564.  To do a complete data record and key insert, use ADD_RECORD_XB to add the data 
  4565.  record to the DBF, BUILD_KEY_XB to construct the key, then STORE_KEY_XB to 
  4566.  insert the key and record number information into the index file.  If that key 
  4567.  already exists and the file allows duplicate keys, attach the proper 
  4568.  enumerator word and retry STORE_KEY_XB.  INSERT_XB does this automatically. 
  4569.  
  4570.  
  4571. ΓòÉΓòÉΓòÉ 9.51. DELETE_KEY_XB ΓòÉΓòÉΓòÉ
  4572.  
  4573. Pack: ACCESSPACK               Source Example 
  4574.  
  4575.      IN               OUT
  4576.    AP.func          AP.stat
  4577.    AP.handle
  4578.    AP.keyPtr
  4579.  
  4580.  Physically remove the specified key from the index file. 
  4581.  
  4582.  This routine requires an exact key match for all bytes of the key, including 
  4583.  the enumerator word if duplicate keys are allowed. 
  4584.  
  4585.  Typically, this routine would seldom be used since deleted DBF data records 
  4586.  are only physically deleted during a PACK_RECORDS_XB operation, after which a 
  4587.  REINDEX_XB is done. It is useful if you are managing a transaction log and 
  4588.  need to back out changes made, beyond what BULLET performs.  Also see 
  4589.  DEBUMP_RECORD_XB. If you have non-unique keys (where DUPS_ALLOWED is true), 
  4590.  you may have several keys that match your criterion, and only differ in their 
  4591.  enumerator.  To identify which key, then, goes to a particular DBF record, 
  4592.  compare that key's AP.recNo with the number of your DBF record.  If they are 
  4593.  the same, then this key belongs to that record.  Use either the KEY_XB or the 
  4594.  GET_XB routines, then, before using this routine.  In other words, use this 
  4595.  routine only after you have identified exactly the key to delete, and for the 
  4596.  exact data record.  Once you have the record number, you can locate its key by 
  4597.  using GET_KEY_FOR_RECORD_XB. 
  4598.  
  4599.  
  4600. ΓòÉΓòÉΓòÉ 9.52. BUILD_KEY_XB ΓòÉΓòÉΓòÉ
  4601.  
  4602. Pack: ACCESSPACK               Source Example 
  4603.  
  4604.      IN               OUT
  4605.    AP.func          AP.stat
  4606.    AP.handle        *AP.keyPtr
  4607.    AP.recPtr
  4608.    AP.keyPtr
  4609.  
  4610.  Build the key for the specified data record based on the key expression for 
  4611.  the index file.  If the index file allows duplicate keys, a 0-value enumerator 
  4612.  is attached. 
  4613.  
  4614.  This routine, like most of the mid-level routines, typically would not be used 
  4615.  since the high-level access routines take care of this detail automatically. 
  4616.  If used, it normally would be used prior to STORE_KEY_XB. 
  4617.  
  4618.  This routine can be replaced.  See Custom Build-Key Routine. 
  4619.  
  4620.  Note:  If DUPS_ALLOWED, this routine always sets the enumerator to \0\0. 
  4621.  Enumerator management, which is used to guarantee a unique key, is performed 
  4622.  only when the INSERT_XB routine is used. 
  4623.  
  4624.  
  4625. ΓòÉΓòÉΓòÉ 9.53. GET_CURRENT_KEY_XB ΓòÉΓòÉΓòÉ
  4626.  
  4627. Pack: ACCESSPACK               Source Example 
  4628.  
  4629.      IN               OUT
  4630.    AP.func          AP.stat
  4631.    AP.handle        AP.recNo
  4632.    AP.keyPtr        *AP.keyPtr
  4633.  
  4634.  Retrieve the current key value for the specified index file handle and also 
  4635.  the data record number that it indexes. The key value includes the enumerator 
  4636.  if applicable. 
  4637.  
  4638.  This routine is useful in that it retrieves, on demand, the actual key value 
  4639.  of the last accessed key in the index file (and the data record number 
  4640.  associated with that key). STAT_INDEX_XB returns this information, too. 
  4641.  
  4642.  
  4643. ΓòÉΓòÉΓòÉ 9.54. GET_KEY_FOR_RECORD_XB ΓòÉΓòÉΓòÉ
  4644.  
  4645. Pack: ACCESSPACK               Source Example 
  4646.  
  4647.      IN               OUT
  4648.    AP.func          AP.stat
  4649.    AP.handle        *AP.keyPtr
  4650.    AP.recNo
  4651.    AP.recPtr
  4652.    AP.keyPtr
  4653.  
  4654.  Retrieve the key for the record/record number pair. 
  4655.  
  4656.  This routine would typically be used prior to using DELETE_KEY_XB and 
  4657.  DEBUMP_RECORD_XB.  The key returned includes the enumerator if applicable. 
  4658.  This routine sifts through any duplicate keys (if DUPS_ALLOWED) for the key 
  4659.  that matches the record/record number pair, and so requires both the actual 
  4660.  data record along with its physical record number (even if dups are not 
  4661.  allowed). 
  4662.  
  4663.  Typically this routine is extraneous; the key is available with a GET_XB 
  4664.  routine and so can be deleted from the information provided through normal 
  4665.  access. 
  4666.  
  4667.  This routine builds a key based on the supplied record at AP.recPtr and 
  4668.  searches the index for that key proper.  If found, and if DUPS_ALLOWED, each 
  4669.  key matching the key proper has its record number compared to the record 
  4670.  number in AP.recNo.  If that matches, too, then that is the exact key being 
  4671.  sought. 
  4672.  
  4673.  
  4674. ΓòÉΓòÉΓòÉ 9.55. GET_FIRST_XB ΓòÉΓòÉΓòÉ
  4675.  
  4676. Pack: ACCESSPACK               Source Example 
  4677.  
  4678.      IN               OUT
  4679.    AP.func          AP.stat
  4680.    AP.handle        AP.recNo
  4681.    AP.recPtr        *AP.recPtr
  4682.    AP.keyPtr        *AP.keyPtr
  4683.  
  4684.  Retrieve the first indexed key and its data record. 
  4685.  
  4686.  The key returned includes an enumerator if the index file uses non-unique keys 
  4687.  (DUPS_ALLOWED). 
  4688.  
  4689.  This routine is typically used to process a database in index order starting 
  4690.  at the first ordered key (and its data record).  After processing this first 
  4691.  entry, subsequent in-order access of the database is achieved by using 
  4692.  GET_NEXT_XB, until the end of the database is reached, at which point an error 
  4693.  is returned. 
  4694.  
  4695.  This routine, like all the high-level GET_XB routines, fills in the AP.recNo 
  4696.  of the record accessed.  In this case, it fills AP.recNo with the record 
  4697.  number pointed to by the first key. Since this is done upon each GET_XB 
  4698.  access, the AP pack is primed for an UPDATE_XB 
  4699.  
  4700.  
  4701. ΓòÉΓòÉΓòÉ 9.56. GET_EQUAL_XB ΓòÉΓòÉΓòÉ
  4702.  
  4703. Pack: ACCESSPACK               Source Example 
  4704.  
  4705.      IN               OUT
  4706.    AP.func          AP.stat
  4707.    AP.handle        AP.recNo
  4708.    AP.recPtr        *AP.recPtr
  4709.    AP.keyPtr
  4710.  
  4711.  Search for the exact key in the index file and return its data record. 
  4712.  
  4713.  This routine finds only an exact match to the specified key (including the 
  4714.  enumerator if applicable). 
  4715.  
  4716.  This routine, like all the high-level GET_XB routines, fills in the AP.recNo 
  4717.  of the record accessed.  In this case, it fills AP.recNo with the record 
  4718.  number pointed to by the matching key. Since this is done upon each GET_XB 
  4719.  access, the AP pack is primed for an UPDATE_XB 
  4720.  
  4721.  
  4722. ΓòÉΓòÉΓòÉ 9.57. GET_EQUAL_OR_GREATER_XB ΓòÉΓòÉΓòÉ
  4723.  
  4724. Pack: ACCESSPACK               Source Example 
  4725.  
  4726.      IN               OUT
  4727.    AP.func          AP.stat
  4728.    AP.handle        AP.recNo
  4729.    AP.recPtr        *AP.recPtr
  4730.    AP.keyPtr        *AP.keyPtr
  4731.  
  4732.  Search for the exact key in the index file and return its data record, or if 
  4733.  not found, get the key and record that would have followed it. 
  4734.  
  4735.  This routine is similar to GET_EQUAL_XB except that this routine returns a key 
  4736.  in *keyPtr (either the same as on entry, or if that is not found, then the 
  4737.  next greater key). 
  4738.  
  4739.  The main benefit of this routine is that it is an atomic operation. It differs 
  4740.  from setting the atomic mode flag of SET_SYSVARS_XB in that this routine 
  4741.  allows a fuzzy starting point:  the key in AP.keyPtr, on entry (IN), need not 
  4742.  exist. 
  4743.  
  4744.  
  4745. ΓòÉΓòÉΓòÉ 9.58. GET_EQUAL_OR_LESSER_XB ΓòÉΓòÉΓòÉ
  4746.  
  4747. Pack: ACCESSPACK               Source Example 
  4748.  
  4749.      IN               OUT
  4750.    AP.func          AP.stat
  4751.    AP.handle        AP.recNo
  4752.    AP.recPtr        *AP.recPtr
  4753.    AP.keyPtr        *AP.keyPtr
  4754.  
  4755.  Search for the exact key in the index file and return its data record, or if 
  4756.  not found, get the key and record that would have come before it. 
  4757.  
  4758.  This routine is similar to GET_EQUAL_XB except that this routine returns a key 
  4759.  in *keyPtr (either the same as on entry, or if that is not found, then the 
  4760.  previous, lesser key). 
  4761.  
  4762.  The main benefit of this routine is that it is an atomic operation. It differs 
  4763.  from setting the atomic mode flag of SET_SYSVARS_XB in that this routine 
  4764.  allows a fuzzy starting point:  the key in AP.keyPtr, on entry (IN), need not 
  4765.  exist. 
  4766.  
  4767.  
  4768. ΓòÉΓòÉΓòÉ 9.59. GET_NEXT_XB ΓòÉΓòÉΓòÉ
  4769.  
  4770. Pack: ACCESSPACK               Source Example 
  4771.  
  4772.      IN               OUT
  4773.    AP.func          AP.stat
  4774.    AP.handle        AP.recNo
  4775.    AP.recPtr        *AP.recPtr
  4776.    AP.keyPtr        *AP.keyPtr
  4777.  
  4778.  Retrieve the next indexed key and its data record. 
  4779.  
  4780.  The key returned includes an enumerator if the index file uses non-unique keys 
  4781.  (DUPS_ALLOWED). 
  4782.  
  4783.  This routine is typically called after the index file has first been 
  4784.  positioned to a known key using either GET_FIRST_XB or GET_EQUAL_XB, or after 
  4785.  a previous GET_NEXT_XB or even GET_PREV_XB.  What it basically does is get the 
  4786.  key and data record following the current key, and then makes that key the new 
  4787.  current key. 
  4788.  
  4789.  This routine, like all the high-level GET_XB routines, fills in the AP.recNo 
  4790.  of the record accessed.  In this case, it fills AP.recNo with the record 
  4791.  number pointed to by the next key (now the current key). Since this is done 
  4792.  upon each GET_XB access, the AP pack is primed for an UPDATE_XB. ________________________________________________
  4793.  
  4794.  If bit0 of the atomic mode flag of SET_SYSVARS_XB is set to 1, key access is 
  4795.  based on a given starting point.  This simplifies index access in 
  4796.  multi-threaded code, where another thread may have altered the last key 
  4797.  accessed in the index file.  This mode lets you set a starting point for the 
  4798.  operation by supplying in AP.keyPtr the key value to start at. 
  4799.  
  4800.  For example, say you use GET_FIRST_XB.  On return, AP.keyPtr has the the very 
  4801.  first key.  Say elsewhere in your multi-threaded program, another operation 
  4802.  accesses that same index file handle, and performs some other access, where 
  4803.  the last accessed key is no longer the same (i.e., not the first key).  Your 
  4804.  first thread is expecting that a GET_NEXT_XB would get the second key, 
  4805.  however, it very likely won't since the second thread has altered the last 
  4806.  accessed key for that file handle.  By using the atomic mode for key access, 
  4807.  your first thread, which has the first key value in its AP.keyPtr, can do a 
  4808.  call to GET_NEXT_XB and get expected results, since the NEXT operation first 
  4809.  positions to the value in AP.keyPtr and then follows up with a GET_NEXT 
  4810.  operation.  This is performed within the Bullet kernel, and so won't be 
  4811.  interrupted by another thread (i.e., it is an atomic operation).  For this to 
  4812.  work, you must ensure that the AP.keyPtr value is set to the value of the last 
  4813.  accessed key.  This will always be the case unless uninitialized, or you are 
  4814.  using global variables for your threads' AP (AccessPack).  On return from the 
  4815.  operation, AP.keyPtr will once again be set up for another atomic operation. 
  4816.  
  4817.  Note:  You must supply a valid key value for this atomic access mode. 
  4818.  AP.keyPtr must be at least as large as the key length in all cases, and is to 
  4819.  have the starting point for the operation (i.e., the last accessed key).  You 
  4820.  may, alternatively, set the first byte of the key buffer to 0 (but not 
  4821.  AP.keyPtr itself to NULL).  This disables atomic mode for that access, and 
  4822.  reverts to the internally-stored last key accessed as the starting point. 
  4823.  
  4824.  
  4825. ΓòÉΓòÉΓòÉ 9.60. GET_PREV_XB ΓòÉΓòÉΓòÉ
  4826.  
  4827. Pack: ACCESSPACK               Source Example 
  4828.  
  4829.      IN               OUT
  4830.    AP.func          AP.stat
  4831.    AP.handle        AP.recNo
  4832.    AP.recPtr        *AP.recPtr
  4833.    AP.keyPtr        *AP.keyPtr
  4834.  
  4835.  Retrieve the previous indexed key and its data record. 
  4836.  
  4837.  The key returned includes an enumerator if the index file uses non-unique keys 
  4838.  (DUPS_ALLOWED). 
  4839.  
  4840.  This routine is typically called after the index file has first been 
  4841.  positioned to a known key using either GET_LAST_XB or GET_EQUAL_XB, or after a 
  4842.  previous GET_PREV_XB or even GET_NEXT_XB.  What it basically does is get the 
  4843.  key and data record preceding the current key, and then makes that key the new 
  4844.  current key. 
  4845.  
  4846.  This routine, like all the high-level GET_XB routines, fills in the AP.recNo 
  4847.  of the record accessed.  In this case, it fills AP.recNo with the record 
  4848.  number pointed to by the previous key (now the current key). Since this is 
  4849.  done upon each GET_XB access, the AP pack is primed for an UPDATE_XB. ________________________________________________
  4850.  
  4851.  If bit0 of the atomic mode flag of SET_SYSVARS_XB is set to 1, key access is 
  4852.  based on a given starting point.  This simplifies index access in 
  4853.  multi-threaded code, where another thread may have altered the last key 
  4854.  accessed in the index file.  This mode lets you set a starting point for the 
  4855.  operation by supplying in AP.keyPtr the key value to start at. 
  4856.  
  4857.  For example, say you use GET_FIRST_XB.  On return, AP.keyPtr has the the very 
  4858.  first key.  Say elsewhere in your multi-threaded program, another operation 
  4859.  accesses that same index file handle, and performs some other access, where 
  4860.  the last accessed key is no longer the same (i.e., not the first key).  Your 
  4861.  first thread is expecting that a GET_NEXT_XB would get the second key, 
  4862.  however, it very likely won't since the second thread has altered the last 
  4863.  accessed key for that file handle.  By using the atomic mode for key access, 
  4864.  your first thread, which has the first key value in its AP.keyPtr, can do a 
  4865.  call to GET_NEXT_XB and get expected results, since the NEXT operation first 
  4866.  positions to the value in AP.keyPtr and then follows up with a GET_NEXT 
  4867.  operation.  This is performed within the Bullet kernel, and so won't be 
  4868.  interrupted by another thread (i.e., it is an atomic operation).  For this to 
  4869.  work, you must ensure that the AP.keyPtr value is set to the value of the last 
  4870.  accessed key.  This will always be the case unless uninitialized, or you are 
  4871.  using global variables for your threads' AP (AccessPack).  On return from the 
  4872.  operation, AP.keyPtr will once again be set up for another atomic operation. 
  4873.  
  4874.  Note:  You must supply a valid key value for this atomic access mode. 
  4875.  AP.keyPtr must be at least as large as the key length in all cases, and is to 
  4876.  have the starting point for the operation (i.e., the last accessed key).  You 
  4877.  may, alternatively, set the first byte of the key buffer to 0 (but not 
  4878.  AP.keyPtr itself to NULL).  This disables atomic mode for that access, and 
  4879.  reverts to the internally-stored last key accessed as the starting point. 
  4880.  
  4881.  
  4882. ΓòÉΓòÉΓòÉ 9.61. GET_LAST_XB ΓòÉΓòÉΓòÉ
  4883.  
  4884. Pack: ACCESSPACK               Source Example 
  4885.  
  4886.      IN               OUT
  4887.    AP.func          AP.stat
  4888.    AP.handle        AP.recNo
  4889.    AP.recPtr        *AP.recPtr
  4890.    AP.keyPtr        *AP.keyPtr
  4891.  
  4892.  Retrieve the last indexed key and its data record. 
  4893.  
  4894.  The key returned includes an enumerator if the index file uses non-unique keys 
  4895.  (DUPS_ALLOWED). 
  4896.  
  4897.  This routine is typically used to process a database in reverse index order 
  4898.  starting at the last ordered key (and its data record).  After processing this 
  4899.  last entry, subsequent reverse-order access of the database is achieved by 
  4900.  using GET_PREV_XB, until the top of the database is reached, at which point an 
  4901.  error is returned. 
  4902.  
  4903.  This routine, like all the high-level GET_XB routines, fills in the AP.recNo 
  4904.  of the record accessed.  In this case, it fills AP.recNo with the record 
  4905.  number pointed to by the last key. Since this is done upon each GET_XB access, 
  4906.  the AP pack is primed for an UPDATE_XB 
  4907.  
  4908.  
  4909. ΓòÉΓòÉΓòÉ 9.62. INSERT_XB ΓòÉΓòÉΓòÉ
  4910.  
  4911. Pack: ACCESSPACK               Source Example 
  4912.  
  4913.      IN               OUT
  4914.    AP.func          AP.stat
  4915.    AP.handle        AP.recNo
  4916.    AP.recNo         *AP.keyPtr
  4917.    AP.recPtr
  4918.    AP.keyPtr
  4919.    AP.nextPtr
  4920.  
  4921.  Append the data records to data files and build and insert the related keys 
  4922.  into all linked index files.  (Alternate forms are possible.) 
  4923.  
  4924.  This routine is used to add new entries into a database.  Up to 256 index 
  4925.  files may be inserted into per call, with up to 256 data files being added, 
  4926.  too, for a total of 512 files managed per single INSERT_XB call. 
  4927.  
  4928.  Note:  Bullet comes in 100, 250, and 1024-file versions and so this routine is 
  4929.  able to use as many files as handles are still available. If non-standard 
  4930.  fields are used (i.e., non-char structure members to match non-ASCII data 
  4931.  fields in your non-standard DBF), then be aware that your compiler more than 
  4932.  likely will add padding to align on member-size boundaries.  This will result 
  4933.  in a mis-match between your compiler structure and your DBF structure (as 
  4934.  described in fieldList[]).  To prevent this, place #pragma pack(1) / #pragma 
  4935.  pack() around your structures that BULLET uses.  Consult your particular 
  4936.  compiler for alternate methods if it does not support #pragma pack. 
  4937.  
  4938.  Only index handles are listed in AP.handle.  Each index file has associated 
  4939.  with it a data file, known internally to BULLET (the xbLink from OPEN_XB). 
  4940.  There may be more than one index file for a data file, but there is always one 
  4941.  data file per index handle specified in the list.  In other words, you can 
  4942.  list five index files, each indexing the same xbLink data file, and have 
  4943.  BULLET perform an atomic insert of that list.  Or, another possibility is that 
  4944.  you have a single index file, indexing a single data file.  Or, you can list 
  4945.  256 index files, each indexing a single data file (512 total files). 
  4946.  
  4947.  This and several other routines are transaction-list-based.  This means that 
  4948.  if a failure occurs prior to the routine's completion, all changes made to the 
  4949.  database by the routine will be backed-out, and the database (data and index 
  4950.  files) effectively restored to its original state. 
  4951.  
  4952.  If the routine failed to complete, the function return value is the number 
  4953.  (1-based) of the pack that caused the failure.  A positive number indicates 
  4954.  the failure was from an index operation; a negative number indicates the 
  4955.  failure was from a data operation.  In each case, the absolute value of the 
  4956.  return code is the list item that failed (the pack index).  For example, if 
  4957.  five index handles are in the list (AP[0] to AP[4]), and an error occurred on 
  4958.  the last pack's index file, the return code would be positive 5, indicating 
  4959.  the fifth pack (AP[4]) failed.  Since it was a positive 5, the index file was 
  4960.  being processed when the error occurred.  Being processed means not only 
  4961.  physical access, but verification, etc.  If the return code was -5, then 
  4962.  again, the error was in the fifth pack, but since it is negative, the error 
  4963.  occurred while processing the data file.  In either case, upon return, the 
  4964.  database is effectively restored to the way it was before the INSERT_XB call 
  4965.  was made.  Remedy the error, if possible, and INSERT_XB again. 
  4966.  
  4967.  Each pack must include a separate key buffer.  You must not share a common key 
  4968.  buffer.  Doing so disables any chance of recovering the index files in case of 
  4969.  error, since it is in these buffers that BULLET places the newly built keys, 
  4970.  and it is from these that BULLET, upon an error condition, deletes the keys 
  4971.  (required for roll-back). 
  4972.  
  4973.  The enumerator is automatically set up by this routine, if required 
  4974.  (DUPS_ALLOWED and the key already exists with enumerator 0).  It does this by 
  4975.  seeking the last possible enumerator value (0xFFFF) and then backing up to the 
  4976.  previous key.  That key's enumerator is evaluated and incremented, and used as 
  4977.  this key's. 
  4978.  
  4979.  Specifying Files 
  4980.  
  4981.  As mentioned, only the index file handles are specified in AP.handle. Data 
  4982.  files are implicitly specified by their links to the index files, as specified 
  4983.  when the index file was opened (OP.xbLink).  INSERT_XB can process up to 256 
  4984.  index files per call.  Since each index file requires a data file, this means 
  4985.  that up to 256 data files can be processed per call, as well.  Also possible 
  4986.  is that all 256 index handles refer to the same, single data file.  Yet 
  4987.  another possibility is that there is 1 index file, and so 1 data file.  The 
  4988.  possibilities can include those and anything in between. 
  4989.  
  4990.  Example: Specifying a single index file 
  4991.  
  4992.  The simplest form is where a single index handle is specified.  This implies a 
  4993.  single data file, too.  AccessPack setup for this is: 
  4994.  
  4995.   AP.func = INSERT_XB;
  4996.   AP.handle = indexHandle;
  4997.   AP.recNo = 0;
  4998.   AP.recPtr = &recordStruct; // contents referred to below as *recordStruct
  4999.   AP.keyPtr = keyBuffer;
  5000.   AP.nextPtr = NULL;
  5001.  
  5002.  A call to BULLET with the above does the following: 
  5003.  
  5004.    1. The data in *recordStruct is used as a new record that is appended to the 
  5005.       data file.  The data file was linked to this index during the index open, 
  5006.       in OP.xbLink. 
  5007.  
  5008.    2. A key is built by BULLET, based on the data in *recordStruct, and that 
  5009.       key is inserted into the index file (AP.handle).  Stored with the key is 
  5010.       the record number of the record added above. 
  5011.  
  5012.  Note:  AP.recNo must be set to 0 prior to the call.  Any positive number 
  5013.  results in an error (0x80000000, and negative numbers, may be used when more 
  5014.  than one AP pack is used - see below). 
  5015.  
  5016.  Upon return, if no error, the return code is 0.  AP.recNo is set to the 
  5017.  physical record number in the data file that *recordStruct was placed.  The 
  5018.  key that was stored, including any enumerator, is in *keyBuffer. 
  5019.  
  5020.  Upon return, and there was an error, the return code is either -1 or 1. If -1, 
  5021.  the error was caused during processing of the data file portion, and the error 
  5022.  code itself is in AP.stat.  If +1, the error was caused during processing of 
  5023.  the index file, and the error code itself is in AP.stat, as well.  The return 
  5024.  code is, as in all BULLET transaction-list routines, an index of the AP pack 
  5025.  that generated the error -- negative if a data file error, positive if an 
  5026.  index file error.  Since this example has only the single pack, only a -1 or 
  5027.  +1 could be returned, or 0. 
  5028.  
  5029.  Note:  If an error occurred after any part of the database had changed (during 
  5030.  this particular call), then any and all changes that were made are backed-out, 
  5031.  and the files restored to the same state as before the call. 
  5032.  
  5033.  Example: Specifying two index files for a single data file 
  5034.  
  5035.  Two index files, related to the same data file, would set AccessPack to: 
  5036.  
  5037.   AP[0].func = INSERT_XB;
  5038.   AP[0].handle = indexHandle_0;
  5039.   AP[0].recNo = 0;
  5040.   AP[0].recPtr = &recordStruct;
  5041.   AP[0].keyPtr = keyBuffer_0;
  5042.   AP[0].nextPtr = AP[1];
  5043.  
  5044.   AP[1].handle = indexHandle_1;
  5045.   AP[1].recNo = 0x80000000;
  5046.   AP[1].recPtr = &recordStruct;
  5047.   AP[1].keyPtr = keyBuffer_1;
  5048.   AP[1].nextPtr = NULL;
  5049.  
  5050.  A call to BULLET with the above does the following: 
  5051.  
  5052.    1. The data in *recordStruct is used as a new record that is appended 
  5053.       (added) to the data file. 
  5054.  
  5055.    2. A key is built by BULLET, based on the data in *recordStruct, and that 
  5056.       key is inserted into the index file (AP[0].handle).  Stored with the key 
  5057.       is the record number of the record added above. 
  5058.  
  5059.    3. A second key is built by BULLET, based on the data in *recordStruct, and 
  5060.       that key is inserted into the second index file (AP[1].handle).  Stored 
  5061.       with the key is the record number of the record added above. 
  5062.  
  5063.  Note:  The 0x80000000 in AP[1].recNo signifies that AP[1] is using the same 
  5064.  data record that was appended during processing of AP[0].  This results in 
  5065.  just the one data record being added.  AP[1].recPtr must still, however, point 
  5066.  to the same data as AP[0].recPtr does. 
  5067.  
  5068.  Upon return, if no error, the return code is 0.  AP[0].recNo is set to the 
  5069.  physical record number in the data file that *recordStruct was placed.  The 
  5070.  key that was stored for the first index, including any enumerator, is in the 
  5071.  buffer at AP[0].keyPtr.  AP[1].recNo is set to the same physical record number 
  5072.  as AP[0].recNo, except that the record number is negative: For example, if 
  5073.  AP[0].recNo is 22 on return, AP[1].recNo is -22 (the original 0x80000000 value 
  5074.  is overwritten).  The key that was stored for the second index, including any 
  5075.  enumerator, is in the buffer at AP[1].keyPtr. 
  5076.  
  5077.  Upon return, and there was an error, the return code can be -2, -1, 1, or 2. 
  5078.  If negative, the error was caused during processing of that AP pack's data 
  5079.  file portion, and the error code itself is in AP[abs(rez)-1].stat (where rez 
  5080.  is the return code, and -1 since C arrays start at 0).  If the return code was 
  5081.  positive, the error was caused during processing of that AP pack's index file, 
  5082.  and the error code itself is in AP[rez-1].stat, as well.  The return code is, 
  5083.  as in all BULLET transaction-list routines, an index of the AP pack that 
  5084.  generated the error -- negative if a data file error, positive if an index 
  5085.  file error. 
  5086.  
  5087.  Note:  If an error occurred after any part of the database had changed (during 
  5088.  this particular call), then any and all changes that were made are backed-out, 
  5089.  and the files restored to the same state as before the call. 
  5090.  
  5091.  Example: Specifying two index files for each of two different data files 
  5092.  
  5093.  Four total files: two index files related to one data file, and two other 
  5094.  index files related to another data file, would set AccessPack to: 
  5095.  
  5096.   AP[0].func = INSERT_XB;
  5097.   AP[0].handle = indexHandle_0;
  5098.   AP[0].recNo = 0;
  5099.   AP[0].recPtr = &recordStruct_0;
  5100.   AP[0].keyPtr = keyBuffer_0;
  5101.   AP[0].nextPtr = AP[1];
  5102.  
  5103.   AP[1].handle = indexHandle_1;
  5104.   AP[1].recNo = 0x80000000;
  5105.   AP[1].recPtr = &recordStruct_0;
  5106.   AP[1].keyPtr = keyBuffer_1;
  5107.   AP[1].nextPtr = AP[2];
  5108.  
  5109.   AP[2].handle = indexHandle_2;
  5110.   AP[2].recNo = 0;
  5111.   AP[2].recPtr = &recordStruct_1;
  5112.   AP[2].keyPtr = keyBuffer_2;
  5113.   AP[2].nextPtr = AP[3];
  5114.  
  5115.   AP[3].handle = indexHandle_3;
  5116.   AP[3].recNo = 0x80000000;
  5117.   AP[3].recPtr = &recordStruct_1;
  5118.   AP[3].keyPtr = keyBuffer_3;
  5119.   AP[3].nextPtr = NULL;
  5120.  
  5121.  A call to BULLET with the above does the following: 
  5122.  
  5123.    1. The data in *recordStruct_0 is used as a new record that is appended to 
  5124.       the data file linked to the index file in AP[0].handle. 
  5125.  
  5126.    2. A key is built by BULLET, based on the data in *recordStruct_0, and that 
  5127.       key is inserted into the index file (AP[0].handle).  Stored with the key 
  5128.       is the record number of the record added above, for _0. 
  5129.  
  5130.    3. A second key is built by BULLET, based on the data in *recordStruct_0, 
  5131.       and that key is inserted into the second index file (AP[1].handle). 
  5132.       Stored with the key is the record number of the record added above, using 
  5133.       *recordStruct_0. 
  5134.  
  5135.    4. The data in *recordStruct_1 is used as a new record that is appended to 
  5136.       the data file linked to the index file in AP[2].handle. 
  5137.  
  5138.    5. A third key is built by BULLET, based on the data in *recordStruct_1, and 
  5139.       that key is inserted into the index file (AP[2].handle).  Stored with the 
  5140.       key is the record number of the record added above, for _1. 
  5141.  
  5142.    6. A fourth key is built by BULLET, based on the data in *recordStruct_1, 
  5143.       and that key is inserted into the fourth index file (AP[3].handle). 
  5144.       Stored with the key is the record number of the record added above, using 
  5145.       *recordStruct_1. 
  5146.  
  5147.  Note:  The 0x80000000 in AP[1].recNo signifies that AP[1] is using the same 
  5148.  data record that was appended during processing of AP[0].  This results in 
  5149.  just the one data record being added.  AP[1].recPtr must still, however, point 
  5150.  to the same data as AP[0].recPtr does.  The same applies to AP[2] and AP[3] 
  5151.  (though different values, of course). 
  5152.  
  5153.  Upon return, if no error, the return code is 0.  AP[0].recNo is set to the 
  5154.  physical record number in the data file that *recordStruct_0 was placed. The 
  5155.  key that was stored for the first index, including any enumerator, is in the 
  5156.  buffer at AP[0].keyPtr.  AP[1].recNo is set to the same physical record number 
  5157.  as AP[0].recNo, except that the record number is negative: For example, if 
  5158.  AP[0].recNo is 22 on return, AP[1].recNo is -22 (the original 0x80000000 value 
  5159.  is overwritten).  The key that was stored for the second index, including any 
  5160.  enumerator, is in the buffer at AP[1].keyPtr.  AP[2].recNo is set to the 
  5161.  physical record number in the data file that *recordStruct_1 was placed.  The 
  5162.  key that was stored for the third index, including any enumerator, is in the 
  5163.  buffer at AP[2].keyPtr.  AP[3].recNo is set to the same physical record number 
  5164.  as AP[2].recNo, except that the record number is negative: For example, if 
  5165.  AP[2].recNo is 74 on return, AP[3].recNo is -74 (the original 0x80000000 value 
  5166.  is overwritten).  The key that was stored for the fourth index, including any 
  5167.  enumerator, is in the buffer at AP[3].keyPtr. 
  5168.  
  5169.  Upon return, and there was an error, the return code can be -4 to -1, or 1 to 
  5170.  4.  If negative, the error was caused during processing of that AP pack's data 
  5171.  file portion, and the error code itself is in AP[abs(rez)-1].stat (where rez 
  5172.  is the return code, and -1 since C arrays start at 0).  If the return code was 
  5173.  positive, the error was caused during processing of that AP pack's index file, 
  5174.  and the error code itself is in AP[rez-1].stat, as well.  The return code is, 
  5175.  as in all BULLET transaction-list routines, an index of the AP pack that 
  5176.  generated the error -- negative if a data file error, positive if an index 
  5177.  file error. 
  5178.  
  5179.  Note:  If an error occurred after any part of the database had changed (during 
  5180.  this particular call), then any and all changes that were made are backed-out, 
  5181.  and the files restored to the same state as before the call. 
  5182.  
  5183.  Example: Specifying two index files for two records in the same data file 
  5184.  
  5185.  Three files: two index files related to one data file, where two data records 
  5186.  are to be appended, would set AccessPack to: 
  5187.  
  5188.   AP[0].func = INSERT_XB;
  5189.   AP[0].handle = indexHandle_0;
  5190.   AP[0].recNo = 0;
  5191.   AP[0].recPtr = &recordStruct_0;
  5192.   AP[0].keyPtr = keyBuffer_0;
  5193.   AP[0].nextPtr = AP[1];
  5194.  
  5195.   AP[1].handle = indexHandle_1;
  5196.   AP[1].recNo = 0x80000000;
  5197.   AP[1].recPtr = &recordStruct_0;
  5198.   AP[1].keyPtr = keyBuffer_1;
  5199.   AP[1].nextPtr = AP[2];
  5200.  
  5201.   AP[2].handle = indexHandle_0;
  5202.   AP[2].recNo = 0;
  5203.   AP[2].recPtr = &recordStruct_1;
  5204.   AP[2].keyPtr = keyBuffer_2;
  5205.   AP[2].nextPtr = AP[3];
  5206.  
  5207.   AP[3].handle = indexHandle_1;
  5208.   AP[3].recNo = 0x80000000;
  5209.   AP[3].recPtr = &recordStruct_1;
  5210.   AP[3].keyPtr = keyBuffer_3;
  5211.   AP[3].nextPtr = NULL;
  5212.  
  5213.  A call to BULLET with the above does the following: 
  5214.  
  5215.    1. The data in *recordStruct_0 is used as a new record that is appended to 
  5216.       the data file linked to the index file in AP[0].handle. 
  5217.  
  5218.    2. A key is built by BULLET, based on the data in *recordStruct_0, and that 
  5219.       key is inserted into the index file (AP[0].handle).  Stored with the key 
  5220.       is the record number of the record added above, for _0. 
  5221.  
  5222.    3. A second key is built by BULLET, based on the data in *recordStruct_0, 
  5223.       and that key is inserted into the second index file (AP[1].handle). 
  5224.       Stored with the key is the record number of the record added above, using 
  5225.       *recordStruct_0. 
  5226.  
  5227.    4. The data in *recordStruct_1 is used as a new record that is appended to 
  5228.       the data file linked to the index file in AP[2].handle.  Since 
  5229.       AP[2].handle is the same index file as that of AP[0].handle, this means 
  5230.       it's also the same data file as was just operated on above -- a second 
  5231.       data record is appended to the data file.  The net effect of this 
  5232.       operation is to call INSERT_XB twice, once for one insert, then again for 
  5233.       the second.  The difference is that the operation is atomic -- if one 
  5234.       fails, the other is not committed; it's an "all or nothing" operation. 
  5235.  
  5236.    5. A third key is built by BULLET, based on the data in *recordStruct_1, and 
  5237.       that key is inserted into the index file (AP[2].handle).  Stored with the 
  5238.       key is the record number of the record added directly above, for _1. Note 
  5239.       that this index file is the same as specified in AP[0].handle. 
  5240.  
  5241.    6. A fourth key is built by BULLET, based on the data in *recordStruct_1, 
  5242.       and that key is inserted into the fourth index file (AP[3].handle). 
  5243.       Stored with the key is the record number of the record added above, using 
  5244.       *recordStruct_1. 
  5245.  The return ritual is as described above, for "Specifying two index files each 
  5246.  for two different data files". 
  5247.  
  5248.  Example: Specifying a single index file for a previously added data record 
  5249.  
  5250.  This form lets you insert a key without adding a data record.  This would be 
  5251.  required if you were, for example, creating a temporary index of select 
  5252.  records in a data file (i.e., the data records already exist, you just want to 
  5253.  index them).  AccessPack setup for this is: 
  5254.  
  5255.   AP.func = INSERT_XB;
  5256.   AP.handle = indexHandle;
  5257.   AP.recNo = -recordNumberOfExistingRecord;
  5258.   AP.recPtr = &recordStruct;
  5259.   AP.keyPtr = keyBuffer;
  5260.   AP.nextPtr = NULL;
  5261.  
  5262.  A call to BULLET with the above does the following: 
  5263.  
  5264.    1. A key is built by BULLET, based on the data in *recordStruct, and that 
  5265.       key is inserted into the index file (AP.handle).  Stored with the key is 
  5266.       the absolute value of the record number specified in AP.recNo (which is 
  5267.       set to negative record number). 
  5268.  
  5269.  Upon return, if no error, the return code is 0.  AP.recNo is changed to 
  5270.  abs(AP.recNo).  The key that was stored, including any enumerator, is in 
  5271.  *keyBuffer.  No data file access is made. 
  5272.  
  5273.  Upon return, and there was an error, the return code is either -1 or 1. If -1, 
  5274.  the error was caused during processing of the data file portion, and the error 
  5275.  code itself is in AP.stat.  If +1, the error was caused during processing of 
  5276.  the index file, and the error code itself is in AP.stat, as well.  The return 
  5277.  code is, as in all BULLET transaction-list routines, an index of the AP pack 
  5278.  that generated the error -- negative if a data file error, positive if an 
  5279.  index file error.  Since this example has only the single pack, only a -1 or 
  5280.  +1 could be returned. 
  5281.  
  5282.  Note:  If an error occurred after any part of the database had changed (during 
  5283.  this particular call), then any and all changes that were made are backed-out, 
  5284.  and the files restored to the same state as before the call. 
  5285.  
  5286.  An example use of this INSERT_XB feature is to create an ad hoc index of, say, 
  5287.  records marked as deleted.  To do this, create a new index file (say, with a 
  5288.  key of NAME).  Get each data record, by record number using GET_RECORD_XB (for 
  5289.  records 1 to number-of-records), and check the .tag byte.  If '*', call 
  5290.  INSERT_XB with the negative value of AP.recNo.  Do this for every such marked 
  5291.  record.  After all records are processed, you have an index of all deleted 
  5292.  records in the data file.  Delete the index when no longer needed.  That's 
  5293.  just one example. 
  5294.  
  5295.  
  5296. ΓòÉΓòÉΓòÉ 9.63. UPDATE_XB ΓòÉΓòÉΓòÉ
  5297.  
  5298. Pack: ACCESSPACK               Source Example 
  5299.  
  5300.      IN               OUT
  5301.    AP.func          AP.stat
  5302.    AP.handle        *AP.keyPtr
  5303.    AP.recNo
  5304.    AP.recPtr
  5305.    AP.keyPtr
  5306.    AP.nextPtr
  5307.  
  5308.  Update any and all files in the transaction list if necessary, including both 
  5309.  index and data files. 
  5310.  
  5311.  This routine is used to update data records while also updating the index 
  5312.  files if a key field has changed due to data record updates.  Up to 256 index 
  5313.  files may be updated per call, as well as 256 data files, too, for a total of 
  5314.  512 files managed per single UPDATE_XB call. 
  5315.  
  5316.  Only index handles are listed in AP.handle.  Each index file has associated 
  5317.  with it a data file, known internally to BULLET (the xbLink from OPEN_XB). 
  5318.  There may be more than one index file for a data file, but there is always one 
  5319.  data file per index handle specified in the list.  In other words, you can 
  5320.  list five index files, each indexing the same xbLink data file, and have 
  5321.  BULLET perform an atomic update of that list. Or, another possibility is that 
  5322.  you have a single index file, indexing a single data file.  Or, you can list 
  5323.  256 index files, each indexing a single data file (512 total files). 
  5324.  
  5325.  This and several other routines are transaction-list-based.  This means that 
  5326.  if a failure occurs prior to the routine's completion, all changes made to the 
  5327.  database by the routine will be backed-out, and the database (data and index 
  5328.  files) effectively restored to its original state. 
  5329.  
  5330.  If the routine failed to complete, the function return value is the number 
  5331.  (1-based) of the pack that caused the failure.  A positive number indicates 
  5332.  the failure was from an index operation; a negative number indicates the 
  5333.  failure was from a data operation.  In each case, the absolute value of the 
  5334.  return code is the list item that failed (the pack index).  For example, if 
  5335.  five index handles are in the list(AP[0] to AP[4]), and an error occurred on 
  5336.  the last pack's index file, the return code would be positive 5, indicating 
  5337.  the fifth pack (AP[4]) failed.  Since it was a positive 5, the index file was 
  5338.  being processed when the error occurred.  Being processed means not only 
  5339.  physical access, but verification, etc.  If the return code was -5, then 
  5340.  again, the error was in the fifth pack, but since it is negative, the error 
  5341.  occurred while processing the data file.  In either case, upon return, the 
  5342.  database is restored to the way it was before the UPDATE_XB call was made. 
  5343.  Remedy the error, if possible, and UPDATE_XB again. 
  5344.  
  5345.  Each pack must include a separate key buffer.  You must not share a common key 
  5346.  buffer.  Doing so disables any chance of recovering the index files in case of 
  5347.  error, since it is in these buffers that BULLET places any newly built keys, 
  5348.  and it is from these that BULLET, upon an error condition, deletes these keys 
  5349.  (required for roll-back). 
  5350.  
  5351.  The enumerator is automatically maintained by this routine, if required 
  5352.  (DUPS_ALLOWED and the key already exists with enumerator 0).  The process is 
  5353.  the same as INSERT_XB's. 
  5354.  
  5355.  How an update works 
  5356.  
  5357.  All data records specified in the list are read from disk into memory, except 
  5358.  those with AP.recNo=0.  Therefore, a memory allocation large enough to store 
  5359.  all unique data records is made upon entry to this routine (and released at 
  5360.  exit).  For example, if the list includes two implicit data files, and the 
  5361.  record lengths of those two data files are 2048 and 4096 bytes, an allocation 
  5362.  of 6K is made.  In addition, 40KB more is allocated for workspace.  So, for 
  5363.  this example, 46K is allocated (rounded up to 48KB, the next 4KB page 
  5364.  boundary).  Since up to 256 unique records are possible, where a unique record 
  5365.  is identified by handle/record number, be aware of the memory requirements if 
  5366.  you are updating very large databases (e.g., 256 unique records, each 4KB in 
  5367.  length, would have UPDATE_XB allocate a bit over 1MB of memory for this call). 
  5368.  
  5369.  After the data records have been read from disk, each list-item is processed, 
  5370.  in order.  The disk record image previously read is compared with the record 
  5371.  image at AP.recPtr.  If the same, that item is skipped, and the next item in 
  5372.  the list is processed.  If you know beforehand that that record is the same, 
  5373.  set that item's AP.recNo=0 so you can avoid having its disk image read and 
  5374.  stored (or do not include it in the list at all).  If the images differ, 
  5375.  BULLET creates a key for the index file being processed, for each record image 
  5376.  (the original and the one in AP.recPtr).  If the keys generated are the same, 
  5377.  no index file update is needed.  If different, the original key for that 
  5378.  record is deleted from that index file, and the new key inserted. Finally, the 
  5379.  new record replaces the old, the new directly overwriting the original.  Note 
  5380.  that the actual sequence of the update event differs somewhat from this 
  5381.  description in order to optimize the process. 
  5382.  
  5383.  Specifying Files 
  5384.  
  5385.  As mentioned, only the index file handles are specified in AP.handle. Data 
  5386.  files are implicitly specified by their links to the index files, as specified 
  5387.  when the index file was opened (OP.xbLink).  UPDATE_XB can process up to 256 
  5388.  index files per call.  Since each index file requires a data file, this means 
  5389.  that up to 256 data files can be processed per call as well.  Also possible is 
  5390.  that all 256 index handles refer to the same, single data file.  Yet another 
  5391.  possibility is that there is 1 index file, and so 1 data file.  The 
  5392.  possibilities can include those and anything in between. 
  5393.  
  5394.  Example: Specifying a single index file 
  5395.  
  5396.  The simplest form is where a single index handle is specified.  This implies a 
  5397.  single data file, too.  AccessPack setup for this is: 
  5398.  
  5399.   AP.func = UPDATE_XB;
  5400.   AP.handle = indexHandle;
  5401.   AP.recNo = recordToUpdate;
  5402.   AP.recPtr = &recordStruct;
  5403.   AP.keyPtr = keyBuffer;
  5404.   AP.nextPtr = NULL;
  5405.  
  5406.  A call to BULLET with the above does the following: 
  5407.  
  5408.    1. The data in *recordStruct is used as the new record that is to replace 
  5409.       the data record at AP.recNo.  The data file was linked to this index file 
  5410.       (AP.handle) during the index open, in OP.xbLink. 
  5411.  
  5412.    2. If the record data in *recordStruct is the same as the original disk 
  5413.       record, nothing is done.  If the data is new, the key fields are compared 
  5414.       to that belonging to the original disk record, and if the same, only the 
  5415.       record data is updated.  If the new record's key differs from the 
  5416.       original's, the original key for this record is removed from the index, 
  5417.       and the new key inserted. 
  5418.  
  5419.  AP.recNo must be set to the record number that you are updating. Any GET_XB 
  5420.  routine (GET_EQUAL_XB, etc.) may be used to identify the number of a data 
  5421.  record.  Key access has the obvious advantage of knowing the record number of 
  5422.  a specific key (for example, Betty Barbar's data). Any record number, from 1 
  5423.  to number of records in the data file, can be used.  In addition, a negative 
  5424.  record number can be used.  This is treated exactly the same as a positive 
  5425.  record number (the absolute value is used). The reason this is allowed is 
  5426.  because INSERT_XB replaces 0x80000000 record numbers with the negative value 
  5427.  of the previous insert. 
  5428.  
  5429.  Upon return, if no error, the return code is 0.  If the record data was new, 
  5430.  the key for that data record, including any enumerator, is in *keyBuffer. 
  5431.  This is so even if key fields had not changed. 
  5432.  
  5433.  Upon return, and there was an error, the return code is either -1 or 1. If -1, 
  5434.  the error was caused during processing of the data file portion, and the error 
  5435.  code itself is in AP.stat.  If +1, the error was caused during processing of 
  5436.  the index file, and the error code itself is in AP.stat, as well.  The return 
  5437.  code is, as in all BULLET transaction-list routines, an index of the AP pack 
  5438.  that generated the error -- negative if a data file error, positive if an 
  5439.  index file error.  Since this example has only the single pack, only a -1 or 
  5440.  +1 could be returned. 
  5441.  
  5442.  Note:  If an error occurred after any part of the database had changed (during 
  5443.  this particular call), then any and all changes that were made are backed-out, 
  5444.  and the files restored to the same state as before the call. 
  5445.  
  5446.  Example: Specifying two index files for a single data file 
  5447.  
  5448.  Two index files, related to the same data file, would set AccessPack to: 
  5449.  
  5450.   AP[0].func = UPDATE_XB;
  5451.   AP[0].handle = indexHandle_0;
  5452.   AP[0].recNo = recordToUpdate;
  5453.   AP[0].recPtr = &recordStruct;
  5454.   AP[0].keyPtr = keyBuffer_0;
  5455.   AP[0].nextPtr = AP[1];
  5456.  
  5457.   AP[1].handle = indexHandle_1;
  5458.   AP[1].recNo = recordToUpdate;
  5459.   AP[1].recPtr = &recordStruct;
  5460.   AP[1].keyPtr = keyBuffer_1;
  5461.   AP[1].nextPtr = NULL;
  5462.  
  5463.  A call to BULLET with the above does the following: 
  5464.  
  5465.    1. The data in *recordStruct is used as the new record that is to replace 
  5466.       the data record at AP.recNo.  The data file was linked to this index file 
  5467.       (AP.handle) during the index open, in OP.xbLink. 
  5468.  
  5469.    2. If the record data in *recordStruct is the same as the original disk 
  5470.       record, nothing is done.  If the data is new, the key fields are compared 
  5471.       to that belonging to the original disk record, and if the same, only the 
  5472.       record data is updated.  If the new record's key differs from the 
  5473.       original's, the original key for this record is removed from the index, 
  5474.       and the new key inserted. 
  5475.  
  5476.    3. The operation performed directly above is repeated, this time for the 
  5477.       second index file.  The new record data, and the record number to update 
  5478.       are, for this particular example, the same. 
  5479.  
  5480.  AP.recNo must be set to the record number that you are updating. Each 
  5481.  AP[].recNo must be set to a valid record number, even if the record number is 
  5482.  the same as the previous AP[] pack's (the case where you have more than one 
  5483.  index file for a data file).  BULLET knows if the record number duplicates a 
  5484.  number in a previous AP pack, and allocates resources for only the first 
  5485.  encounter of the data record.  Subsequent encounters refer to the first. 
  5486.  
  5487.  Upon return, if no error, the return code is 0.  If the new and original data 
  5488.  records differ, the key for the new data record, including any enumerator, is 
  5489.  in the buffer at AP[0].keyPtr.  This even if the key fields did not change. 
  5490.  The same applies to the second index, with the new data key in AP[1].keyPtr. 
  5491.  
  5492.  Upon return, and there was an error, the return code can be -2, -1, 1, or 2. 
  5493.  If negative, the error was caused during processing of that AP pack's data 
  5494.  file portion, and the error code itself is in AP[abs(rez)-1].stat (where rez 
  5495.  is the return code, and -1 since C arrays start at 0).  If the return code was 
  5496.  positive, the error was caused during processing of that AP pack's index file, 
  5497.  and the error code itself is in AP[rez-1].stat, as well.  The return code is, 
  5498.  as in all BULLET transaction-list routines, an index of the AP pack that 
  5499.  generated the error -- negative if a data file error, positive if an index 
  5500.  file error. 
  5501.  
  5502.  Note:  If an error occurred after any part of the database had changed (during 
  5503.  this particular call), then any and all changes that were made are backed-out, 
  5504.  and the files restored to the same state as before the call. 
  5505.  
  5506.  Example: Specifying two index files for each of two different data files 
  5507.  
  5508.  Four total files: two index files related to one data file, and two other 
  5509.  index files related to another data file, would set AccessPack to: 
  5510.  
  5511.   AP[0].func = UPDATE_XB;
  5512.   AP[0].handle = indexHandle_0;
  5513.   AP[0].recNo = recordToUpdate_0;
  5514.   AP[0].recPtr = &recordStruct_0;
  5515.   AP[0].keyPtr = keyBuffer_0;
  5516.   AP[0].nextPtr = AP[1];
  5517.  
  5518.   AP[1].handle = indexHandle_1;
  5519.   AP[1].recNo = recordToUpdate_0;
  5520.   AP[1].recPtr = &recordStruct_0;
  5521.   AP[1].keyPtr = keyBuffer_1;
  5522.   AP[1].nextPtr = AP[2];
  5523.  
  5524.   AP[2].handle = indexHandle_2;
  5525.   AP[2].recNo = recordToUpdate_1;
  5526.   AP[2].recPtr = &recordStruct_1;
  5527.   AP[2].keyPtr = keyBuffer_2;
  5528.   AP[2].nextPtr = AP[3];
  5529.  
  5530.   AP[3].handle = indexHandle_3;
  5531.   AP[3].recNo = recordToUpdate_1;
  5532.   AP[3].recPtr = &recordStruct_1;
  5533.   AP[3].keyPtr = keyBuffer_3;
  5534.   AP[3].nextPtr = NULL;
  5535.  
  5536.  A call to BULLET with the above does the following: 
  5537.  
  5538.    1. The data in *recordStruct_0 is used as the new record that is to replace 
  5539.       the data record at AP[0].recNo in the data file linked to the index file 
  5540.       in AP[0].handle. 
  5541.  
  5542.    2. If the record data in *recordStruct_0 is the same as the original disk 
  5543.       record, nothing is done.  If the data is new, the key fields are compared 
  5544.       to that belonging to the original disk record, and if the same, only the 
  5545.       record data is updated.  If the new record's key differs from the 
  5546.       original's, the original key for this record is removed from the index, 
  5547.       and the new key inserted. 
  5548.  
  5549.    3. The operation performed directly above is repeated, this time for the 
  5550.       second index file.  The new record data, and the record number to update, 
  5551.       are for this particular example, the same. 
  5552.  
  5553.    4. The data in *recordStruct_1 is used as the new record that is to replace 
  5554.       the data record at AP[2].recNo in the data file linked to the index file 
  5555.       in AP[2].handle. 
  5556.  
  5557.    5. If the record data in *recordStruct_1 is the same as the original disk 
  5558.       record, nothing is done.  If the data is new, the key fields are compared 
  5559.       to that belonging to the original disk record, and if the same, only the 
  5560.       record data is updated.  If the new record's key differs from the 
  5561.       original's, the original key for this record is removed from the index, 
  5562.       and the new key inserted. 
  5563.  
  5564.    6. The operation performed directly above is repeated, this time for the 
  5565.       fourth index file.  The new record data, and the record number to update 
  5566.       are, for this particular example, the same. 
  5567.  
  5568.  Upon return, if no error, the return code is 0.  If the new and original data 
  5569.  records differ, the keys for the new data records, including any enumerators, 
  5570.  are in the buffers at AP[0].keyPtr to AP[3].keyPtr.  This even if the key 
  5571.  fields did not change.  If one, or all, of the new data records matched the 
  5572.  original data record, nothing is placed in *keyBuffer for that index. 
  5573.  
  5574.  Upon return, and there was an error, the return code can be -4 to -1, or 1 to 
  5575.  4.  If negative, the error was caused during processing of that AP pack's data 
  5576.  file portion, and the error code itself is in AP[abs(rez)-1].stat (where rez 
  5577.  is the return code, and rez-1 since C arrays start at 0).  If the return code 
  5578.  was positive, the error was caused during processing of that AP pack's index 
  5579.  file, and the error code itself is in AP[rez-1].stat, as well.  The return 
  5580.  code is, as in all BULLET transaction-list routines, an index of the AP pack 
  5581.  that generated the error -- negative if a data file error, positive if an 
  5582.  index file error. 
  5583.  
  5584.  Note:  If an error occurred after any part of the database had changed (during 
  5585.  this particular call), then any and all changes that were made are backed-out, 
  5586.  and the files restored to the same state as before the call. 
  5587.  
  5588.  Example: Specifying two index files for two records in the same data file 
  5589.  
  5590.  Three files: two index files related to one data file, where two data records 
  5591.  are to be updated, would set AccessPack to: 
  5592.  
  5593.   AP[0].func = UPDATE_XB;
  5594.   AP[0].handle = indexHandle_0;
  5595.   AP[0].recNo = recordToUpdate_0;
  5596.   AP[0].recPtr = &recordStruct_0;
  5597.   AP[0].keyPtr = keyBuffer_0;
  5598.   AP[0].nextPtr = AP[1];
  5599.  
  5600.   AP[1].handle = indexHandle_1;
  5601.   AP[1].recNo = recordToUpdate_0;
  5602.   AP[1].recPtr = &recordStruct_0;
  5603.   AP[1].keyPtr = keyBuffer_1;
  5604.   AP[1].nextPtr = AP[2];
  5605.  
  5606.   AP[2].handle = indexHandle_0;
  5607.   AP[2].recNo = recordToUpdate_1;
  5608.   AP[2].recPtr = &recordStruct_1;
  5609.   AP[2].keyPtr = keyBuffer_2;
  5610.   AP[2].nextPtr = AP[3];
  5611.  
  5612.   AP[3].handle = indexHandle_1;
  5613.   AP[3].recNo = recordToUpdate_1;
  5614.   AP[3].recPtr = &recordStruct_1;
  5615.   AP[3].keyPtr = keyBuffer_3;
  5616.   AP[3].nextPtr = NULL;
  5617.  
  5618.  A call to BULLET with the above does the following: 
  5619.  
  5620.    1. The data in *recordStruct_0 is used as the new record that is to replace 
  5621.       the data record at AP[0].recNo in the data file linked to the index file 
  5622.       in AP[0].handle. 
  5623.  
  5624.    2. If the record data in *recordStruct_0 is the same as the original disk 
  5625.       record, nothing is done.  If the data is new, the key fields are compared 
  5626.       to that belonging to the original disk record, and if the same, only the 
  5627.       record data is updated.  If the new record's key differs from the 
  5628.       original's, the original key for this record is removed from the index, 
  5629.       and the new key inserted. 
  5630.  
  5631.    3. The operation performed directly above is repeated, this time for the 
  5632.       second index file.  The new record data, and the record number to update, 
  5633.       are for this particular example, the same. 
  5634.  
  5635.    4. The data in *recordStruct_1 is used as the new record that is to replace 
  5636.       the data record at AP[2].recNo in the data file linked to the index file 
  5637.       in AP[2].handle.  This is the same index file as the first AP pack, and 
  5638.       also the same data file.  However, this is a different record number. 
  5639.  
  5640.    5. If the record data in *recordStruct_1 is the same as the original disk 
  5641.       record, nothing is done.  If the data is new, the key fields are compared 
  5642.       to that belonging to the original disk record, and if the same, only the 
  5643.       record data is updated.  If the new record's key differs from the 
  5644.       original's, the original key for this record is removed from the index, 
  5645.       and the new key inserted. 
  5646.  
  5647.    6. The operation performed directly above is repeated, this time for the 
  5648.       fourth index file. The new record data, and the record number to update 
  5649.       are, for this particular example, the same. 
  5650.  The return ritual is as described above, for "Specifying two index files each 
  5651.  for two different data files". 
  5652.  
  5653.  
  5654. ΓòÉΓòÉΓòÉ 9.64. REINDEX_XB ΓòÉΓòÉΓòÉ
  5655.  
  5656. Pack: ACCESSPACK               Source Example 
  5657.  
  5658.      IN               OUT
  5659.    AP.func          AP.stat
  5660.    AP.handle        AP.recNo
  5661.    AP.keyPtr        *AP.keyPtr
  5662.    AP.nextPtr
  5663.  
  5664.  Reindex all files in the transaction list, re-evaluating the key expression in 
  5665.  the process. 
  5666.  
  5667.  This routine is used to reindex up to 256 index files per call. The index 
  5668.  files must already exist and be open.  Any existing key values are overwritten 
  5669.  by new key data.  In other words, if you have a 100MB index file, REINDEX_XB 
  5670.  uses the same file space, building new keys over old.  This results in a less 
  5671.  fragmented disk and also minimizes disk space needed.  You can also create a 
  5672.  new, empty index file and reindex to that.  This would be useful, for 
  5673.  instance, if you needed to create a temporary index file -- something that 
  5674.  you'd use for a report, say, then delete after the report.  Another use for 
  5675.  creating a new index file and reindexing to that is to, after creating it 
  5676.  (COPY_INDEX_HEADER_XB can be used), use EXPAND_FILE_DOS and expand it to the 
  5677.  expected size.  This has the benefit of ensuring that this file allocation is 
  5678.  as contiguous as the file system allows (without relying on OS/API-specific 
  5679.  calls). 
  5680.  
  5681.  If the routine failed to complete, the function return value is the number 
  5682.  (1-based) of the pack that caused the failure.  A positive number indicates 
  5683.  the failure was from an index operation; a negative number indicates the 
  5684.  failure was from a data operation (reading the data file).  In each case, the 
  5685.  absolute value of the return code is the list item that failed (the pack 
  5686.  index).  For example, if five index handles are in the list(AP[0] to AP[4]), 
  5687.  and an error occurred on the last pack's index file, the return code would be 
  5688.  positive 5, indicating the fifth pack (AP[4]) failed.  Since it was a positive 
  5689.  5, the index file was being processed when the error occurred.  Being 
  5690.  processed means not only physical access, but verification, etc.  If the 
  5691.  return code was -5, then again, the error was in the fifth pack, but since it 
  5692.  is negative, the error occurred while processing the data file. 
  5693.  
  5694.  Unlike INSERT_XB and UPDATE_XB, each pack need not include a separate key 
  5695.  buffer; you may share a common key buffer.  If duplicate keys are generated in 
  5696.  the reindex process and the sort function does not flag DUPS_ALLOWED, an error 
  5697.  is returned.  The duplicate key is in *AP.keyPtr and the record number it was 
  5698.  generated from in AP.recNo (both these are valid only on error).  Since no 
  5699.  roll-back is performed, there is only a real need for a single key buffer. 
  5700.  You may use separate ones, too. 
  5701.  
  5702.  This routine creates a temporary work file in either the current directory or, 
  5703.  if the environment variable TMP is defined, in the directory pointed to by 
  5704.  TMP=.  The path used for this temporary file may also be specified at run-time 
  5705.  by using the TMP_PATH_PTR item for SET_SYSVARS_XB.  If TMP_PATH_PTR is NULL 
  5706.  (default), then TMP= is used, or if that is not found, then the current 
  5707.  directory is used.  The size of this temporary file is, in bytes, 
  5708.  approximately (keylength+4) * number of records in the data file.  The 
  5709.  resultant index files are, by default, optimized for minimum size and maximum 
  5710.  retrieval speed.  This full-node packing leaves one empty key per node, which 
  5711.  means b-tree splitting will occur almost immediately upon inserting data (with 
  5712.  INSERT_XB or STORE_KEY_XB). 
  5713.  
  5714.  This behaviour can be modified with the REINDEX_PACK_PCT item for 
  5715.  SET_SYSVARS_XB so that less packing is done.  Less packing would improve 
  5716.  subsequent INSERT_XB performance since all nodes are not almost full as they 
  5717.  are with a full pack.  File size and retrieval times increase, though, but 
  5718.  perhaps not noticeably. 
  5719.  
  5720.  During the reindex process, each record is checked for a matching skip-tag 
  5721.  value, as set in SET_SYSVARS_XB.  The skip-tag is set to 0 by default, where 
  5722.  no check is done and keys for all records in the data file are inserted into 
  5723.  the index file. 
  5724.  
  5725.  
  5726. ΓòÉΓòÉΓòÉ 9.65. LOCK_XB ΓòÉΓòÉΓòÉ
  5727.  
  5728. Pack: LOCKPACK                 Source Example 
  5729.  
  5730.      IN               OUT
  5731.    LP.func          LP.stat
  5732.    LP.handle
  5733.    LP.xlMode
  5734.    LP.dlMode
  5735.    LP.recStart=0
  5736.    LP.nextPtr
  5737.  
  5738.  Lock all bytes of the files in the list for exclusive use by the current 
  5739.  process, and reload file headers from disk.  LP.recStart must be 0 for each 
  5740.  pack. 
  5741.  
  5742.  This routine is used to lock the database for either exclusive use by this 
  5743.  process, or shared access (allowing any process to read, but not write, to the 
  5744.  files).  Up to 256 index files may be locked per call, as well as 256 data 
  5745.  files, too, for a total of 512 files per single LOCK_XB call.  Shared-access 
  5746.  locking prevents all processes from writing to the file while a shared lock is 
  5747.  in force, including this process.  To relock in exclusive lock mode, without 
  5748.  unlocking first, use: RELOCK_XB. 
  5749.  
  5750.  Only index handles are listed in LP.handle.  Each index file has associated 
  5751.  with it a data file, known internally to BULLET (the xbLink from OPEN_XB). 
  5752.  There may be more than one index file for a data file, but there is always one 
  5753.  data file per index handle specified in the list.  For example, you can list 
  5754.  five index files, each indexing the same xbLink data file, and have BULLET 
  5755.  perform an atomic lock of that list. 
  5756.  
  5757.  LP.xlMode is set to 1 to perform a shared lock on the index file.  Set to 0 
  5758.  for an exclusive lock.  A shared lock allows only reading. 
  5759.  
  5760.  LP.dlMode is set to 1 to perform a shared lock on the data file.  Set to 0 for 
  5761.  an exclusive lock.  A shared lock allows only reading. 
  5762.  
  5763.  The lock mode (shared <-> exclusive) can be changed using RELOCK_XB. 
  5764.  
  5765.  Bullet maintains a per-handle lock count, and does a physical region lock only 
  5766.  upon the first lock request (or on a relock request).  It is only on this 
  5767.  first lock request that the header is reloaded.  When the lock count returns 
  5768.  to 0 (from UNLOCK_XB calls), it is at that time the header is flushed, if 
  5769.  required.  Only full-locks are maintained in this way.  The number of 
  5770.  outstanding locks can be determined from the SIP and SDP structures, from the 
  5771.  STAT_XB routines.  Note that individual LOCK_INDEX_XB and UNLOCK_INDEX_XB 
  5772.  routines, as well as the data ones, also act upon this lock count.  Therefore, 
  5773.  you can lock a file 100 times in a row, but only on the first lock are any 
  5774.  operations actually performed, and only on the last unlock are any performed. 
  5775.  Other lock/unlock calls (other than the first lock or last unlock) simply 
  5776.  increment or decrement the lock count for that handle. 
  5777.  
  5778.  This and several other routines are transaction-list-based.  This means that 
  5779.  if a failure occurs prior to the routine's completion, all locks made to the 
  5780.  database by this routine will be unlocked. 
  5781.  
  5782.  If the routine failed to complete, the function return value is the number 
  5783.  (1-based) of the pack that caused the failure.  A positive number indicates 
  5784.  the failure was from an index operation; a negative number indicates the 
  5785.  failure was from a data operation.  In each case, the absolute value of the 
  5786.  return code is the list item that failed (the pack index).  For example, if 
  5787.  five index handles are in the list(AP[0] to AP[4]), and an error occurred on 
  5788.  the last pack's index file, the return code would be positive 5, indicating 
  5789.  the fifth pack (AP[4]) failed.  Since it was a positive 5, the index file was 
  5790.  being processed when the error occurred.  Being processed means not only 
  5791.  physical access, but verification, etc.  If the return code was -5, then 
  5792.  again, the error was in the fifth pack, but since it is negative, the error 
  5793.  occurred while processing the data file.  In either case, upon return, any 
  5794.  files locked during this call are unlocked before returning. 
  5795.  
  5796.  The advantage of using region locks (LOCK_XB locks entire file regions) to 
  5797.  control file access is that the file does not need to be opened/closed using 
  5798.  the Deny Read/Write sharing attribute.  Opening the file for Deny None, and 
  5799.  controlling subsequent access with region locks, allows for faster processing 
  5800.  since files do not need to be constantly opened and closed, as they would if 
  5801.  access were controlled by opening with Deny Read/Write. 
  5802.  
  5803.  Using the operating system to control access also prevents other processes 
  5804.  from accessing the files.  Other methods, such as internal locking (such as 
  5805.  using 'L' in the tag field as a program-aware in-use flag), work fine so long 
  5806.  as each process accessing the files knows about this internal "locking". 
  5807.  However, since it's proprietary, other processes may not know about it.  Any 
  5808.  locking system that is not commonly shared throughout the system is not 
  5809.  effective when it comes to preventing other processes from corrupting files. 
  5810.  
  5811.  Note:  Region locking prevents other processes from both writing and reading 
  5812.  the locked file.  For operating systems that do not provide shared locks, and 
  5813.  read-access is required at all times, you may specify this type access with 
  5814.  the access-sharing mode when the BULLET file is opened.  Once opened for this 
  5815.  (R/W, DenyWrite) then only the current process can write to the file until it 
  5816.  is closed.  Other processes must open the file for Read-Only access.  For 
  5817.  small networks (two or three nodes), this may be suitable.  Otherwise, region 
  5818.  locking is much preferred, and very much faster, since files do not have to be 
  5819.  opened and closed every time the access state needs to change. 
  5820.  
  5821.  
  5822. ΓòÉΓòÉΓòÉ 9.66. UNLOCK_XB ΓòÉΓòÉΓòÉ
  5823.  
  5824. Pack: LOCKPACK                 Source Example 
  5825.  
  5826.      IN               OUT
  5827.    LP.func          LP.stat
  5828.    LP.handle
  5829.    LP.recStart=0
  5830.    LP.nextPtr
  5831.  
  5832.  Unlock all bytes in the specified files (previously locked) and flush the 
  5833.  files' headers to disk (the flush is done before the locks are released). Also 
  5834.  unlock all bytes in the related data file and flush the data file header to 
  5835.  disk.  LP.recStart must be 0 for each pack. 
  5836.  
  5837.  Note:  If a shared-lock is active for this handle (as set by this process), 
  5838.  the flush is not performed.  This because writing to the locked region is not 
  5839.  permitted (nor is the flush required since nothing could have been changed). 
  5840.  
  5841.  If the routine failed to complete, the function return value is the number 
  5842.  (1-based) of the pack that caused the failure.  A positive number indicates 
  5843.  the failure was from an index operation; a negative number indicates the 
  5844.  failure was from a data operation.  In each case, the absolute value of the 
  5845.  return code is the list item that failed (the pack index).  For example, if 
  5846.  five index handles are in the list(AP[0] to AP[4]), and an error occurred on 
  5847.  the last pack's index file, the return code would be positive 5, indicating 
  5848.  the fifth pack (AP[4]) failed.  Since it was a positive 5, the index file was 
  5849.  being processed when the error occurred.  Being processed means not only 
  5850.  physical access, but verification, etc.  If the return code was -5, then 
  5851.  again, the error was in the fifth pack, but since it is negative, the error 
  5852.  occurred while processing the data file. 
  5853.  
  5854.  This routine does not attempt to re-lock those files unlocked successfully if 
  5855.  an error occurs in the transaction.  If an error does occur (unlikely), the 
  5856.  remaining files must be manually unlocked with the UNLOCK_KEY_XB and 
  5857.  UNLOCK_DATA_XB routines. 
  5858.  
  5859.  Bullet maintains a per-handle lock count, and does a physical region lock only 
  5860.  upon the first lock request (or on a relock request).  It is only on this 
  5861.  first lock request that the header is reloaded.  When the lock count returns 
  5862.  to 0 (from UNLOCK_XB calls), it is at that time the header is flushed, if 
  5863.  required.  Only full-locks are maintained in this way.  The number of 
  5864.  outstanding locks can be determined from the SIP and SDP structures, from the 
  5865.  STAT_XB routines.  Note that individual LOCK_INDEX_XB and UNLOCK_INDEX_XB 
  5866.  routines, as well as the data ones, also act upon this lock count.  Therefore, 
  5867.  you can lock a file 100 times in a row, but only on the first lock are any 
  5868.  operations actually performed, and only on the last unlock are any performed. 
  5869.  Other lock/unlock calls (other than the first lock or last unlock) simply 
  5870.  increment or decrement the lock count for that handle. 
  5871.  
  5872.  
  5873. ΓòÉΓòÉΓòÉ 9.67. LOCK_INDEX_XB ΓòÉΓòÉΓòÉ
  5874.  
  5875. Pack: LOCKPACK                 Source Example 
  5876.  
  5877.      IN               OUT
  5878.    LP.func          LP.stat
  5879.    LP.handle
  5880.    LP.xlMode
  5881.  
  5882.  Lock all bytes of the index file for exclusive use by the current process and 
  5883.  reload the index file's header from disk. 
  5884.  
  5885.  LP.xlMode is set to 1 to perform a shared lock.  Set to 0 for an exclusive 
  5886.  lock.  A shared lock allows only reading.  The lock mode (shared <-> 
  5887.  exclusive) can be changed using RELOCK_INDEX_XB. 
  5888.  
  5889.  Bullet maintains a per-handle lock count, and does a physical region lock only 
  5890.  upon the first lock request (or on a relock request).  It is only on this 
  5891.  first lock request that the header is reloaded.  When the lock count returns 
  5892.  to 0 (from UNLOCK_XB calls), it is at that time the header is flushed, if 
  5893.  required.  Only full-locks are maintained in this way.  The number of 
  5894.  outstanding locks can be determined from the SIP and SDP structures, from the 
  5895.  STAT_XB routines.  Note that individual LOCK_INDEX_XB and UNLOCK_INDEX_XB 
  5896.  routines, as well as the data ones, also act upon this lock count.  Therefore, 
  5897.  you can lock a file 100 times in a row, but only on the first lock are any 
  5898.  operations actually performed, and only on the last unlock are any performed. 
  5899.  Other lock/unlock calls (other than the first lock or last unlock) simply 
  5900.  increment or decrement the lock count for that handle. 
  5901.  
  5902.  
  5903. ΓòÉΓòÉΓòÉ 9.68. UNLOCK_INDEX_XB ΓòÉΓòÉΓòÉ
  5904.  
  5905. Pack: LOCKPACK                 Source Example 
  5906.  
  5907.      IN               OUT
  5908.    LP.func          LP.stat
  5909.    LP.handle
  5910.  
  5911.  Unlock all bytes in the specified file (previously locked) and flush the 
  5912.  file's header to disk (the flush is done before the locks are released). 
  5913.  
  5914.  If the current lock state is shared, the flush is not performed. 
  5915.  
  5916.  Bullet maintains a per-handle lock count, and does a physical region lock only 
  5917.  upon the first lock request (or on a relock request).  It is only on this 
  5918.  first lock request that the header is reloaded.  When the lock count returns 
  5919.  to 0 (from UNLOCK_XB calls), it is at that time the header is flushed, if 
  5920.  required.  Only full-locks are maintained in this way.  The number of 
  5921.  outstanding locks can be determined from the SIP and SDP structures, from the 
  5922.  STAT_XB routines.  Note that individual LOCK_INDEX_XB and UNLOCK_INDEX_XB 
  5923.  routines, as well as the data ones, also act upon this lock count.  Therefore, 
  5924.  you can lock a file 100 times in a row, but only on the first lock are any 
  5925.  operations actually performed, and only on the last unlock are any performed. 
  5926.  Other lock/unlock calls (other than the first lock or last unlock) simply 
  5927.  increment or decrement the lock count for that handle. 
  5928.  
  5929.  
  5930. ΓòÉΓòÉΓòÉ 9.69. LOCK_DATA_XB ΓòÉΓòÉΓòÉ
  5931.  
  5932. Pack: LOCKPACK                 Source Example 
  5933.  
  5934.      IN               OUT
  5935.    LP.func          LP.stat
  5936.    LP.handle
  5937.    LP.dlMode
  5938.    LP.recStart
  5939.    LP.recCount
  5940.  
  5941.  Lock all bytes of the data file specified in LP.handle for exclusive use by 
  5942.  the current process.  It also reloads the data file header from disk. You must 
  5943.  set LP.recStart=0 to lock all bytes.  To lock a single record, or a set of 
  5944.  contiguous records, set LP.recStart to the first record to lock and 
  5945.  LP.recCount to the number of records to lock. 
  5946.  
  5947.  Header re-loading is performed only if locking all bytes. 
  5948.  
  5949.  If LP.recStart is not 0, be aware that the header is not locked, nor is it 
  5950.  re-loaded.  Also, maintaining a lock on the single record prevents any other 
  5951.  process from doing a full lock on that data file, thereby preventing write 
  5952.  access to the file from any other BULLET process using LOCK_XB, but not 
  5953.  necessarily preventing other applications from writing to that file.  That may 
  5954.  or may not be good.  It does not prevent other BULLET processes from reading 
  5955.  that file (except for that locked record). 
  5956.  
  5957.  Multiple single records are allowed, but each must then be unlocked 
  5958.  individually, in the same format (start, count) as the lock. 
  5959.  
  5960.  LP.dlMode is set to 1 to perform a shared lock.  Set to 0 for an exclusive 
  5961.  lock.  A shared lock allows only reading.  The lock mode (shared <-> 
  5962.  exclusive) can be changed using RELOCK_DATA_XB. 
  5963.  
  5964.  Bullet maintains a per-handle lock count, and does a physical region lock only 
  5965.  upon the first lock request (or on a relock request).  It is only on this 
  5966.  first lock request that the header is reloaded.  When the lock count returns 
  5967.  to 0 (from UNLOCK_XB calls), it is at that time the header is flushed, if 
  5968.  required.  Only full-locks are maintained in this way.  The number of 
  5969.  outstanding locks can be determined from the SIP and SDP structures, from the 
  5970.  STAT_XB routines.  Note that individual LOCK_INDEX_XB and UNLOCK_INDEX_XB 
  5971.  routines, as well as the data ones if a full lock, also act upon this lock 
  5972.  count.  Therefore, you can lock a file 100 times in a row, but only on the 
  5973.  first lock are any operations actually performed, and only on the last unlock 
  5974.  are any performed.  Other lock/unlock calls (other than the first lock or last 
  5975.  unlock) simply increment or decrement the lock count for that handle. 
  5976.  
  5977.  
  5978. ΓòÉΓòÉΓòÉ 9.70. UNLOCK_DATA_XB ΓòÉΓòÉΓòÉ
  5979.  
  5980. Pack: LOCKPACK                 Source Example 
  5981.  
  5982.      IN               OUT
  5983.    LP.func          LP.stat
  5984.    LP.handle
  5985.    LP.recStart
  5986.    LP.recCount
  5987.  
  5988.  Unlock all bytes in the specified file handle (previously locked) and flush 
  5989.  the data file header to disk (the flush is done before the lock is released). 
  5990.  You must set LP.recStart=0 to unlock all bytes.  To unlock a single record, or 
  5991.  a set of contiguous records, set LP.recStart to the first record to unlock and 
  5992.  LP.recCount to the number of records to unlock. 
  5993.  
  5994.  Header flushing is performed only if unlocking a full lock. 
  5995.  
  5996.  An unlock must exactly mimic its corresponding lock.  This means if you lock 
  5997.  several records singly, you must unlock each of those records -- you cannot 
  5998.  use LP.recStart=0 to unlock singly-locked records. 
  5999.  
  6000.  Bullet maintains a per-handle lock count, and does a physical region lock only 
  6001.  upon the first lock request (or on a relock request).  It is only on this 
  6002.  first lock request that the header is reloaded.  When the lock count returns 
  6003.  to 0 (from UNLOCK_XB calls), it is at that time the header is flushed, if 
  6004.  required.  Only full-locks are maintained in this way.  The number of 
  6005.  outstanding locks can be determined from the SIP and SDP structures, from the 
  6006.  STAT_XB routines.  Note that individual LOCK_INDEX_XB and UNLOCK_INDEX_XB 
  6007.  routines, as well as the data ones if a full lock, also act upon this lock 
  6008.  count.  Therefore, you can lock a file 100 times in a row, but only on the 
  6009.  first lock are any operations actually performed, and only on the last unlock 
  6010.  are any performed.  Other lock/unlock calls (other than the first lock or last 
  6011.  unlock) simply increment or decrement the lock count for that handle. 
  6012.  
  6013.  
  6014. ΓòÉΓòÉΓòÉ 9.71. CHECK_REMOTE_XB ΓòÉΓòÉΓòÉ
  6015.  
  6016. Pack: REMOTEPACK               Source Example 
  6017.  
  6018.      IN               OUT
  6019.    RP.func          RP.stat
  6020.    RP.handle        RP.isRemote
  6021.       -or-          RP.flags=0
  6022.    RP.drive         RP.isShare=1
  6023.  
  6024.  If RP.handle is non-zero, determine if the specified handle of a file or 
  6025.  device is remote.  If the handle is local (e.g., not a network file or 
  6026.  device), RP.isRemote returns 0, otherwise it is remote.  RP.flags=0 and 
  6027.  RP.isShare=1 on return for either a handle or drive check under OS/2. 
  6028.  
  6029.  If RP.handle is zero, determine if the drive specified in RP.drive is remote. 
  6030.  Drive A: is 1, B: is 2, C: is 3, and so on.  To check the default drive use 0 
  6031.  (the default drive is the current drive).  If the drive is local (e.g., not a 
  6032.  network drive), RP.isRemote returns 0, otherwise it is remote. 
  6033.  
  6034.  The significance of the remote-ness is less important in a multitasking 
  6035.  environment since sharing of resources (files, in particular) must always be 
  6036.  managed, compared to single-tasking environments where, typically, sharing 
  6037.  (locking mechanisms) need only be performed when the resource is able to be 
  6038.  accessed by another process (ie is a 'network' drive).  Note that the resource 
  6039.  need not be located elsewhere to be classified as remote: Drives or devices or 
  6040.  files on the same machine may be classified as remote if the network software 
  6041.  is redirecting local access (such as on a server). 
  6042.  
  6043.  Note:  This routine is not mutex-protected. 
  6044.  
  6045.  
  6046. ΓòÉΓòÉΓòÉ 9.72. RELOCK_XB ΓòÉΓòÉΓòÉ
  6047.  
  6048. Pack: LOCKPACK                 Source Example 
  6049.  
  6050.      IN               OUT
  6051.    LP.func          LP.stat
  6052.    LP.handle
  6053.    LP.xlMode
  6054.    LP.dlMode
  6055.    LP.recStart=0
  6056.    LP.nextPtr
  6057.  
  6058.  Relock all bytes of the index files for the mode specified in LP.xlMode (index 
  6059.  files) and LP.dlMode (data files).  Also relock all bytes in the related data 
  6060.  file.  LP.recStart must be 0 for each pack. 
  6061.  
  6062.  Set LP.xlMode=1 to select a shared lock for the index file; set to 0 for an 
  6063.  exclusive lock.  Set LP.dlMode=1 to select a shared lock for the data file; 
  6064.  set to 0 for an exclusive lock. 
  6065.  
  6066.  If the lock mode is from exclusive to shared, the file is flushed before the 
  6067.  shared state is set.  BULLET maintains the current lock state and knows which 
  6068.  direction the lock is going in.  The lock state (shared or exclusive) can be 
  6069.  determined by the SIP and SDP structures from the STAT_XB routines.  This 
  6070.  routine does not affect the lock count, nor are the headers reloaded (nor 
  6071.  should they be). 
  6072.  
  6073.  The lock state is on a file handle basis, not on an LP[] pack basis. This 
  6074.  means the file, as identified by the handle, is in the lock state last set. 
  6075.  
  6076.  Note:  The lock switch is made atomic:  Rather than unlocking, and then 
  6077.  locking again in the new state, this performs all operations without the 
  6078.  possibility that another process can grab the lock away, if supported by the 
  6079.  OS.  If relock is not supported by the OS, and shared (read-only) locks are 
  6080.  supported, the relock will be performed by Bullet rather than the OS.  If 
  6081.  Bullet performs the relock, another, non-Bullet process may be able to steal 
  6082.  away the lock since it is no longer guaranteed to be atomic. 
  6083.  
  6084.  
  6085. ΓòÉΓòÉΓòÉ 9.73. RELOCK_INDEX_XB ΓòÉΓòÉΓòÉ
  6086.  
  6087. Pack: LOCKPACK                 Source Example 
  6088.  
  6089.      IN               OUT
  6090.    LP.func          LP.stat
  6091.    LP.handle
  6092.    LP.xlMode
  6093.  
  6094.  Relock all bytes of the index file for the mode specified in LP.xlMode and 
  6095.  reload the header. 
  6096.  
  6097.  Set LP.xlMode=1 to select a shared lock; set to 0 for an exclusive lock. If 
  6098.  the lock mode is from exclusive to shared, the file is flushed before the 
  6099.  shared state is set.  BULLET maintains the current lock state and knows which 
  6100.  direction the lock is going in.  The lock state (shared or exclusive) can be 
  6101.  determined by the SIP structure from the STAT_INDEX_XB routine.  This routine 
  6102.  does not affect the lock count, nor is the header reloaded (nor should it be). 
  6103.  
  6104.  Note:  The lock switch is made atomic:  Rather than unlocking, and then 
  6105.  locking again in the new state, this performs all operations without the 
  6106.  possibility that another process can grab the lock away, if supported by the 
  6107.  OS.  If relock is not supported by the OS, and shared (read-only) locks are 
  6108.  supported, the relock will be performed by Bullet rather than the OS.  If 
  6109.  Bullet performs the relock, another, non-Bullet process may be able to steal 
  6110.  away the lock since it is no longer guaranteed to be atomic. 
  6111.  
  6112.  
  6113. ΓòÉΓòÉΓòÉ 9.74. RELOCK_DATA_XB ΓòÉΓòÉΓòÉ
  6114.  
  6115. Pack: LOCKPACK                 Source Example 
  6116.  
  6117.      IN               OUT
  6118.    LP.func          LP.stat
  6119.    LP.handle
  6120.    LP.dlMode
  6121.    LP.recStart
  6122.    LP.recCount
  6123.  
  6124.  Relock all bytes of the data file for the mode specified in LP.dlMode and 
  6125.  reload the header, unless LP.recStart is non-zero. 
  6126.  
  6127.  If the lock mode is from exclusive to shared, the file is flushed before the 
  6128.  shared state is set.  BULLET maintains the current lock state and knows which 
  6129.  direction the lock is going in.  The lock state (shared or exclusive) can be 
  6130.  determined by the SDP structure from the STAT_DATA_XB routine.  This routine 
  6131.  does not affect the lock count, nor is the header reloaded (nor should it be). 
  6132.  
  6133.  You must set LP.recStart=0 to relock all bytes.  To relock a single record, or 
  6134.  set of contiguous records, set LP.recStart=record# to relock and LP.recCount 
  6135.  to the number of records to relock. 
  6136.  
  6137.  Note:  The lock switch is made atomic:  Rather than unlocking, and then 
  6138.  locking again in the new state, this performs all operations without the 
  6139.  possibility that another process can grab the lock away, if supported by the 
  6140.  OS.  If relock is not supported by the OS, and shared (read-only) locks are 
  6141.  supported, the relock will be performed by Bullet rather than the OS.  If 
  6142.  Bullet performs the relock, another, non-Bullet process may be able to steal 
  6143.  away the lock since it is no longer guaranteed to be atomic. 
  6144.  
  6145.  
  6146. ΓòÉΓòÉΓòÉ 9.75. DELETE_FILE_DOS ΓòÉΓòÉΓòÉ
  6147.  
  6148. Pack: DOSFILEPACK              Source Example 
  6149.  
  6150.      IN               OUT
  6151.    DFP.func         DFP.stat
  6152.    DFP.filenamePtr
  6153.  
  6154.  Delete the specified file. 
  6155.  
  6156.  Note:  OS/2 DosForceDelete is used so the file is not recoverable with the 
  6157.  UNDELETE command. 
  6158.  
  6159.  
  6160. ΓòÉΓòÉΓòÉ 9.76. RENAME_FILE_DOS ΓòÉΓòÉΓòÉ
  6161.  
  6162. Pack: DOSFILEPACK              Source Example 
  6163.  
  6164.      IN               OUT
  6165.    DFP.func         DFP.stat
  6166.    DFP.filenamePtr
  6167.    DFP.newNamePtr
  6168.  
  6169.  Rename a file.  May also be used to move the file to a new directory within 
  6170.  the partition. 
  6171.  
  6172.  If the specified directory differs from the file's directory, the file's 
  6173.  directory entry is moved to the new directory. 
  6174.  
  6175.  For example, if the filenamePtr filename is /LP100/PROJ94A.INF and the 
  6176.  newFilenamePtr filename is /ARCH/PROJ93A.INA, the file is essentially renamed 
  6177.  and also moved to the /ARCH directory. 
  6178.  
  6179.  
  6180. ΓòÉΓòÉΓòÉ 9.77. CREATE_FILE_DOS ΓòÉΓòÉΓòÉ
  6181.  
  6182. Pack: DOSFILEPACK              Source Example 
  6183.  
  6184.      IN               OUT
  6185.    DFP.func         DFP.stat
  6186.    DFP.filenamePtr
  6187.    DFP.attr
  6188.  
  6189.  Create a new file. 
  6190.  
  6191.  The specified filename/pathname must not already exist. 
  6192.  
  6193.  The file created is not left open.  You must OPEN_FILE_DOS to use it. 
  6194.  
  6195.  The attribute used during the create can be: 
  6196.  
  6197.    Attribute  Value   Meaning
  6198.     Normal       0      normal access permitted to file
  6199.     Read-Only    1      read-only access permitted to file
  6200.     Hidden       2      file does not appear in directory listing
  6201.     System       4      file is a system file
  6202.     SubDir      10h     FILENAME is a subdirectory
  6203.     Archive     20h     file is marked for archiving
  6204.  
  6205.  Note:  Use MAKE_DIR_DOS to create a subdirectory. 
  6206.  
  6207.  
  6208. ΓòÉΓòÉΓòÉ 9.78. OPEN_FILE_DOS ΓòÉΓòÉΓòÉ
  6209.  
  6210. Pack: DOSFILEPACK              Source Example 
  6211.  
  6212.      IN               OUT
  6213.    DFP.func         DFP.stat
  6214.    DFP.filenamePtr  DFP.handle
  6215.    DFP.asMode
  6216.  
  6217.  Open the file with the access-sharing mode, returning the handle on success. 
  6218.  
  6219.  
  6220. ΓòÉΓòÉΓòÉ 9.79. SEEK_FILE_DOS ΓòÉΓòÉΓòÉ
  6221.  
  6222. Pack: DOSFILEPACK              Source Example 
  6223.  
  6224.      IN               OUT
  6225.    DFP.func         DFP.stat
  6226.    DFP.handle       DFP.seekTo
  6227.    DFP.seekTo
  6228.    DFP.method
  6229.  
  6230.  Position the file pointer of the file to the seekTo position based on the 
  6231.  method specified. 
  6232.  
  6233.  The position is a 32-bit value and is relative to either the start of the 
  6234.  file, the current file pointer position, or the end of the file. 
  6235.  
  6236.   Method   Meaning
  6237.     0      start move from the start of file (offset is a 32-bit unsigned value)
  6238.     1      start move at the current position (offset a signed value)
  6239.     2      start move at the end of file (offset a signed value)
  6240.  For example, to move to the last byte of a sector (512th byte, but offset 
  6241.  511), set the offset value to 511 and use Method 0.  On return, the absolute 
  6242.  offset value of the new position is returned.  This return value is useful 
  6243.  with Method 2 since you can specify an offset of 0 and have the file length 
  6244.  returned.  To move to the start of the file, use method 0, offset 0.  To move 
  6245.  to the first byte of the second sector, use offset 512. 
  6246.  
  6247.  Note:  Never position the file pointer to before the start of file. 
  6248.  
  6249.  
  6250. ΓòÉΓòÉΓòÉ 9.80. READ_FILE_DOS ΓòÉΓòÉΓòÉ
  6251.  
  6252. Pack: DOSFILEPACK              Source Example 
  6253.  
  6254.      IN               OUT
  6255.    DFP.func         DFP.stat
  6256.    DFP.handle       DFP.bytes
  6257.    DFP.bytes
  6258.    DFP.bufferPtr
  6259.  
  6260.  Read from the file or device the specified number of bytes into a buffer. 
  6261.  
  6262.  On block devices (such as disks) input starts at the current file position and 
  6263.  the file pointer is repositioned to the last byte read +1. 
  6264.  
  6265.  It is possible to read less than the bytes specified without an error being 
  6266.  generated.  Compare the bytes to read with the returned bytes read value.  If 
  6267.  less then end of file was reached during the read.  If 0 then file was already 
  6268.  at EOF. 
  6269.  
  6270.  
  6271. ΓòÉΓòÉΓòÉ 9.81. WRITE_FILE_DOS ΓòÉΓòÉΓòÉ
  6272.  
  6273. Pack: DOSFILEPACK              Source Example 
  6274.  
  6275.      IN               OUT
  6276.    DFP.func         DFP.stat
  6277.    DFP.handle       DFP.bytes
  6278.    DFP.bytes
  6279.    DFP.bufferPtr
  6280.  
  6281.  Write to the file or device the specified number of bytes from a buffer. 
  6282.  
  6283.  If the number of bytes written is less than the specified bytes, this routine 
  6284.  returns an error. 
  6285.  
  6286.  On block devices (such as disk) output starts at the current file position, 
  6287.  and the file pointer is repositioned to the last byte written +1. 
  6288.  
  6289.  Note:  If the specified bytes to write is 0, the file is truncated at the 
  6290.  current file pointer position. 
  6291.  
  6292.  
  6293. ΓòÉΓòÉΓòÉ 9.82. CLOSE_FILE_DOS ΓòÉΓòÉΓòÉ
  6294.  
  6295. Pack: DOSFILEPACK              Source Example 
  6296.  
  6297.      IN               OUT
  6298.    DFP.func         DFP.stat
  6299.    DFP.handle
  6300.  
  6301.  Close the file flushing any internal buffers, releasing any locked regions, 
  6302.  and updating the directory entry to the correct size, date, and time. 
  6303.  
  6304.  
  6305. ΓòÉΓòÉΓòÉ 9.83. ACCESS_FILE_DOS ΓòÉΓòÉΓòÉ
  6306.  
  6307. Pack: DOSFILEPACK              Source Example 
  6308.  
  6309.      IN               OUT
  6310.    DFP.func         DFP.stat
  6311.    DFP.filenamePtr
  6312.    DFP.asMode
  6313.  
  6314.  Determine if the specified file can be accessed with the specified 
  6315.  access-sharing mode. 
  6316.  
  6317.  Basically, a Does-File-Exist routine.  It uses the specified access-sharing 
  6318.  mode when trying to open the file.  For example, if you specify DFP.attr = 
  6319.  0x0042 (R/W access + Deny None sharing) and issue ACCESS_FILE_DOS on a 
  6320.  Read-Only file, an error is returned.  A sharing mode must be specified; it 
  6321.  cannot be left 0. 
  6322.  
  6323.  
  6324. ΓòÉΓòÉΓòÉ 9.84. EXPAND_FILE_DOS ΓòÉΓòÉΓòÉ
  6325.  
  6326. Pack: DOSFILEPACK              Source Example 
  6327.  
  6328.      IN               OUT
  6329.    DFP.func         DFP.stat
  6330.    DFP.handle
  6331.    DFP.bytes
  6332.  
  6333.  Expands the file by the number of bytes beyond its current size. 
  6334.  
  6335.  This routine is useful in pre-allocating disk space.  By reserving disk space 
  6336.  in advance you can guarantee that enough disk space will be available for a 
  6337.  future operation (especially if more than 1 process is running). You'll also 
  6338.  be able ensure that the disk space that a file does use is as contiguous as 
  6339.  possible. 
  6340.  
  6341.  Database systems are dynamic and their files typically allocate new space on 
  6342.  an as-needed basis.  This dynamic allocation can cause parts of a file to be 
  6343.  located throughout the disk system, possibly affecting performance 
  6344.  drastically.  By pre-allocating the disk space you can be assured of 
  6345.  consistent throughput performance since the file is contiguous. 
  6346.  
  6347.  Note:  The file space is not initialized. 
  6348.  
  6349.  * --------------------------------------------------------------------------- 
  6350.  
  6351.  
  6352. ΓòÉΓòÉΓòÉ 9.85. MAKE_DIR_DOS ΓòÉΓòÉΓòÉ
  6353.  
  6354. Pack: DOSFILEPACK              Source Example 
  6355.  
  6356.      IN               OUT
  6357.    DFP.func         DFP.stat
  6358.    DFP.filenamePtr
  6359.  
  6360.  Create a new subdirectory. 
  6361.  
  6362.  
  6363. ΓòÉΓòÉΓòÉ 9.86. COMMIT_FILE_DOS ΓòÉΓòÉΓòÉ
  6364.  
  6365. Pack: DOSFILEPACK              Source Example 
  6366.  
  6367.      IN               OUT
  6368.    DFP.func         DFP.stat
  6369.    DFP.handle
  6370.  
  6371.  Flushes the OS system buffers for the handle, and updates the directory entry 
  6372.  for size. 
  6373.  
  6374.  
  6375. ΓòÉΓòÉΓòÉ 10. Bullet Source Examples ΓòÉΓòÉΓòÉ
  6376.  
  6377. Bullet source example excerpts for the C language follow.  Complete program 
  6378. source examples are provide on the included disk. 
  6379.  
  6380. In the examples, consider that 
  6381.  
  6382.         CHAR keyBuffer[64];
  6383.         AP.keyPtr = keyBuffer;
  6384.  
  6385. provides the compiler with a pointer whenever 'keyBuffer' is referenced, hence 
  6386. no need to use &keyBuffer.  Contrast this with a structure definition 
  6387.  
  6388.         struct yourRecordLayout yourRecord;
  6389.         AP.recPtr = &yourRecord;
  6390.  
  6391. where &yourRecord is required. 
  6392.  
  6393. Be aware of how you use zero-terminated strings, especially for fields that are 
  6394. not to be 0T'ed (DATE and NUMERIC fields, for example).  Use sscanf() and 
  6395. sprintf(), as required. 
  6396.  
  6397.  
  6398. ΓòÉΓòÉΓòÉ 10.1. Bullet Initialization ΓòÉΓòÉΓòÉ
  6399.  
  6400. /* All example source uses minimal error checking/handling throughout */
  6401. // comment marks are used throughout
  6402.  
  6403. // To simplify the source examples, error handling is typically of the form:
  6404. //
  6405. //   if (rez) goto ErrorHandler;
  6406. //
  6407. // Use suitable coding as you would normally handle the error.
  6408.  
  6409. #include "bullet_2.h"
  6410.  
  6411. INITPACK IP;                    // packs used here
  6412.  
  6413. IP.func = INIT_XB;              // start up Bullet
  6414. IP.JFTsize = 30;                // allow at least 30 handles to be open
  6415. rez = BULLET(&IP);
  6416. if (rez) return(rez);
  6417.  
  6418.  
  6419. ΓòÉΓòÉΓòÉ 10.2. Bullet Shutdown ΓòÉΓòÉΓòÉ
  6420.  
  6421. #include "bullet_2.h"
  6422.  
  6423. EXITPACK EP;                    // packs used here
  6424.  
  6425. EP.func = EXIT_XB;              // shutdown Bullet
  6426. rez = BULLET(&EP);
  6427. if (rez) return(rez);
  6428.  
  6429.  
  6430. ΓòÉΓòÉΓòÉ 10.3. Memory Available ΓòÉΓòÉΓòÉ
  6431.  
  6432. #include "bullet_2.h"
  6433.  
  6434. MEMORYPACK EP;                  // packs used here
  6435.  
  6436. MP.func = MEMORY_XB;
  6437. rez = BULLET(&MP);
  6438. if (rez==0) {
  6439.    printf("Private memory arena space right now is %d bytes\n",MP.memory);
  6440. }
  6441.  
  6442.  
  6443. ΓòÉΓòÉΓòÉ 10.4. File Backup Procedure ΓòÉΓòÉΓòÉ
  6444.  
  6445. #include "bullet_2.h"
  6446.  
  6447. // code determines file type of handle, and selects appropriate backup method
  6448. // this type of work (copy/backup) would be a prelude to reindexing an index
  6449. // file or performing a pack on a data file since both of those routines
  6450. // overwrite existing data
  6451.  
  6452. COPYPACK CP;
  6453. LOCKPACK LP;
  6454. STATHANDLEPACK SHP;
  6455. STATDATAPACK SDP;
  6456. STATINDEXPACK SIP;
  6457.  
  6458. CHAR CopyOfIndexHdrName[260];
  6459. CHAR BackupDataName[260];
  6460.  
  6461. // Given a handle, find out its type and, if index, generate a copy
  6462. // of the index file's header, or if data, backup the entire data file.
  6463. // Files are locked to ensure that access if permissible.
  6464.  
  6465. SHP.func = STAT_HANDLE_XB;
  6466. SHP.handle = passedHandle;
  6467. rez = BULLET(&SHP);
  6468. if (SHP.ID==-1)
  6469.    puts("Handle is not a Bullet data or index file.  Use DosCopy() API call.");
  6470. else {
  6471.    if (SHP.ID==0) {
  6472.  
  6473.       // Since the copy takes place on open files, ensure a full-lock is in place
  6474.       // A shared lock is okay since this file is only read
  6475.  
  6476.       // locking the entire file also RELOADS the index header
  6477.  
  6478.       LP.func = LOCK_INDEX_XB;
  6479.       LP.handle = passedHandle;
  6480.       LP.xlMode = LOCK_SHARED;          // in bullet_2.h
  6481.       rez = BULLET(&LP);
  6482.       if (rez) goto ErrorHandler;
  6483.  
  6484.       SIP.func = STAT_INDEX_XB;
  6485.       SIP.handle = passedHandle;
  6486.       rez = BULLET(&SIP);
  6487.       if (rez) goto ErrorHandler;       // must unlock file in handler
  6488.  
  6489.       // SIP.filenamePtr -> pathname of this handle, from which you can
  6490.       // derive a suitable name for the index header written next -- in
  6491.       // case it's not obvious, this function is not part of Bullet
  6492.  
  6493.       DeriveSuitableName(SIP.filenamePtr,CopyOfIndexHdrName);
  6494.  
  6495.       CP.func = COPY_INDEX_HEADER_XB;
  6496.       CP.handle = passedHandle;
  6497.       CP.filenamePtr = CopyOfIndexHdrName;
  6498.       rez = BULLET(&CP);
  6499.       if (rez) goto ErrorHandler;       // must unlock file in handler
  6500.  
  6501.       // unlocking also flushes the index header if not LOCK_SHARED (and if required)
  6502.  
  6503.       LP.func = UNLOCK_INDEX_XB;
  6504.       LP.handle = passedHandle;
  6505.       rez = BULLET(&LP);
  6506.       if (rez) goto ErrorHandler;
  6507.    }
  6508.    else {
  6509.  
  6510.       // locking the entire file also RELOADS the data header
  6511.  
  6512.       LP.func = LOCK_DATA_XB;
  6513.       LP.handle = passedHandle;
  6514.       LP.dlMode = LOCK_SHARED;
  6515.       LP.startRec = 0;                  // lock entire data file
  6516.       rez = BULLET(&LP);
  6517.       if (rez) goto ErrorHandler;
  6518.  
  6519.       SDP.func = STAT_DATA_XB;
  6520.       SDP.handle = passedHandle;
  6521.       rez = BULLET(&SDP);
  6522.       if (rez) goto ErrorHandler;       // must unlock file in handler
  6523.  
  6524.       DeriveSuitableName(SDP.filenamePtr,BackupDataName);
  6525.  
  6526.       CP.func = BACKUP_FILE_XB;
  6527.       CP.handle = passedHandle;         // set to -passedHandle to skip memo backup
  6528.       CP.filenamePtr = BackupDataName;
  6529.       rez = BULLET(&CP);
  6530.       if (rez) goto ErrorHandler;       // must unlock file in handler
  6531.  
  6532.       // unlocking also flushes the data header if not LOCK_SHARED (and if required)
  6533.  
  6534.       LP.func = UNLOCK_DATA_XB;
  6535.       LP.handle = passedHandle;
  6536.       rez = BULLET(&LP);
  6537.       if (rez) goto ErrorHandler;
  6538.    }
  6539. }
  6540.  
  6541.  
  6542. ΓòÉΓòÉΓòÉ 10.5. Get Error Class ΓòÉΓòÉΓòÉ
  6543.  
  6544. #include "bullet_2.h"
  6545.  
  6546. XERRORPACK XEP;                 // packs used here
  6547.  
  6548. // Bullet errors range from 8192 to 8999, any other return code
  6549. // indicates the error number was generated by OS/2 itself
  6550.  
  6551. if (rez < 8192) | (rez > 8999) {
  6552.    XEP.func = GET_ERROR_CLASS_XB;
  6553.    XEP.stat = rez;
  6554.    rez = BULLET(&XEP);
  6555.  
  6556.    // here XEP.errClass, .action, and .location are set
  6557.    // this call is the same as OS/2 API DosErrClass()
  6558.  
  6559.  
  6560. ΓòÉΓòÉΓòÉ 10.6. Query System Variables ΓòÉΓòÉΓòÉ
  6561.  
  6562. #include "bullet_2.h"
  6563.  
  6564. QUERYSETPACK  QSP;              // packs used here
  6565.  
  6566. // Query a Bullet system variable
  6567.  
  6568. QSP.func = QUERY_SYSVARS_XB;
  6569. QSP.item = MUTEX_SEM_HANDLE;    // in bullet_2.h
  6570. rez = BULLET(&QSP);
  6571. if (rez==0)
  6572.    printf("Bullet/2 mutex handle is %d\n",QSP.itemValue);
  6573.  
  6574.  
  6575. ΓòÉΓòÉΓòÉ 10.7. Set System Variables ΓòÉΓòÉΓòÉ
  6576.  
  6577. #include "bullet_2.h"
  6578.  
  6579. QUERYSETPACK  QSP;              // packs used here
  6580.  
  6581. // Set a Bullet system variable
  6582.  
  6583. QSP.func = SET_SYSVARS_XB;
  6584. QSP.item = REINDEX_BUFFER_SIZE; // in bullet_2.h
  6585. QSP.itemValue = 384*1024;       // set to 384KB
  6586. rez = BULLET(&QSP);
  6587. if (rez==0) {
  6588.    printf("Reindex buffer sized changed to 384K.\n");
  6589.    printf("Previous setting was %d.\n",QSP.itemValue);
  6590.  
  6591.    // For REINDEX_BUFFER_SIZE, a value of 0 represents 'autosize', for which
  6592.    // Bullet selects a minimum usuable size (often 144KB).  The minimum size
  6593.    // that you can use for REINDEX_BUFFER_SIZE is 48KB.
  6594.  
  6595.  
  6596. ΓòÉΓòÉΓòÉ 10.8. Set Dual-video Monitor ΓòÉΓòÉΓòÉ
  6597.  
  6598.  
  6599. // SET_DVMON_XB is not currently used
  6600.  
  6601.  
  6602. ΓòÉΓòÉΓòÉ 10.9. Query Vectors ΓòÉΓòÉΓòÉ
  6603.  
  6604. #include "bullet_2.h"
  6605.  
  6606. QUERYSETPACK  QSP;              // packs used here
  6607.  
  6608. // Query a Bullet vector
  6609.  
  6610. QSP.func = QUERY_VECTORS_XB;
  6611. QSP.item = VECTOR_GET_SORT_TABLE;  // in bullet_2.h
  6612. rez = BULLET(&QSP);
  6613. if (rez==0)
  6614.    printf("Bullet get-sort-table vector is %x\n",QSP.itemValue);
  6615.  
  6616.  
  6617. ΓòÉΓòÉΓòÉ 10.10. Set Vectors ΓòÉΓòÉΓòÉ
  6618.  
  6619. #include "bullet_2.h"
  6620.  
  6621. QUERYSETPACK  QSP;              // packs used here
  6622.  
  6623. // Set a Bullet vector
  6624.  
  6625. // external routine (in ccdosfn.c, for example)
  6626. LONG __cdecl BulletMalloc(ULONG bytes, VOID **basePtr);
  6627.  
  6628. QSP.func = SET_VECTORS_XB;
  6629. QSP.item = VECTOR_MALLOC;
  6630. QSP.itemValue = (ULONG) &BulletMalloc;
  6631. rez = BULLET(&QSP);
  6632. if (rez==0) {
  6633.    printf("Memory allocation changed to new routine.\n");
  6634.    printf("Previous routine's address was %x.\n",QSP.itemValue);
  6635.  
  6636.  
  6637. ΓòÉΓòÉΓòÉ 10.11. Create, Open, and Close Data and Index Files ΓòÉΓòÉΓòÉ
  6638.  
  6639. #include "bullet_2.h"
  6640.  
  6641. CREATEDATAPACK  CDP;
  6642. CREATEINDEXPACK CIP;
  6643. OPENPACK        OP;
  6644. HANDLEPACK      HP;             // packs used here
  6645.  
  6646. // create the data file
  6647.  
  6648. #pragma pack(1)         // ensure compiler does not pad Bullet-used structures
  6649.                         // (not needed here since all members are CHAR)
  6650.  
  6651. // generally, only left-justified strings should be 0-terminated, numbers or
  6652. // date fields should not be 0-terminated
  6653.  
  6654. typedef struct _RECTYPE {
  6655.  CHAR tag;              // record tag, init to SPACE, '*' means deleted
  6656.  CHAR userSSN[9];       // first field in DBF (not 0-terminated in this case)
  6657.  CHAR userScore[6];     // second field (also not 0T)
  6658. } RECTYPE;              // (total record length is 16 bytes)
  6659. RECTYPE ourRecord;
  6660.  
  6661. #pragma pack()
  6662.  
  6663. CHAR nameIX3[] = "INDEX.IX3";   // index pathname
  6664. CHAR keyExpression[] = "SSN";   // key is built from field named 'SSN'
  6665. ULONG indexID=0;                // handle of opened index file
  6666. CHAR keyBuffer[68];             // buffer to store/receive key values
  6667.  
  6668. CHAR nameData[] = "DATA.DBF";   // data pathname
  6669. ULONG dataID=0;                 // handle of opened data file
  6670. FIELDDESCTYPE fieldList[2];     // 2 fields used in data record (SSN and SCORE)
  6671.  
  6672. // the field descriptor info must have unused entries set to 0
  6673.  
  6674. memset(fieldList,0,sizeof(fieldList));  // init unused bytes to 0 (required)
  6675.  
  6676. // fill in the field descriptor info for the data file you want to create
  6677. // this descriptor must match the layout of ourRecord, above (ourRecord.tag
  6678. // is implicit and is not a formal field, and so is not in fieldList[])
  6679.  
  6680. strcpy(fieldList[0].fieldName, "SSN");  // field names must be upper-case
  6681. fieldList[0].fieldType = 'C';           // field types must be upper-case
  6682. fieldList[0].fieldLen = 9;              // * Note that the .fieldname here
  6683. fieldList[0].fieldDC = 0;               // * matches the keyExpression
  6684.  
  6685. strcpy(fieldList[1].fieldName, "SCORE");
  6686. fieldList[1].fieldType = 'C';
  6687. fieldList[1].fieldLen = 6;              // 6 is total size of field
  6688. fieldList[1].fieldDC = 0;
  6689.  
  6690. // Create the data file as defined in fieldList above
  6691. // To create only a DBF, set CDP.fileID=3
  6692. // To create both a DBF and a DBT memo file, set CDP.fileID=0x8B
  6693.  
  6694. CDP.func = CREATE_DATA_XB;
  6695. CDP.filenamePtr = nameData;
  6696. CDP.noFields = 2;
  6697. CDP.fieldListPtr = fieldList;
  6698. CDP.fileID = 3;
  6699. rez = BULLET(&CDP);
  6700. if (rez) {
  6701.    printf("Failed data file create.  Err: %d\n",rez);
  6702.    return(rez);
  6703. }
  6704.  
  6705. // Open the data file (required before creating an index file for it)
  6706.  
  6707. OP.func = OPEN_DATA_XB;
  6708. OP.filenamePtr = nameData;
  6709. OP.asMode = READWRITE | DENYNONE;
  6710. rez = BULLET(&OP);
  6711. if (rez) {
  6712.    printf("Failed data file open.  Err: %d\n",rez);
  6713.    return(rez);
  6714. }
  6715. dataID = OP.handle;
  6716.  
  6717. // Create an index file for the data file opened above.
  6718. // This example uses a simple primary key: the SSN field.
  6719. // Since it is assumed to be unique, DUPS_ALLOWED is not
  6720. // OR'ed with the .sortFunction.
  6721.  
  6722. CIP.func = CREATE_INDEX_XB;
  6723. CIP.filenamePtr = nameIX3;
  6724. CIP.keyExpPtr = keyExpression;
  6725. CIP.xbLink = dataID;            // the handle of the data file
  6726. CIP.sortFunction = ASCII_SORT;  // sort key by ASCII (fine for SSN ordering)
  6727. CIP.codePage = 0;               // use OS-default code page
  6728. CIP.countryCode = 0;            // use OS-default country code
  6729. CIP.collatePtr = NULL;          // no need for a special collate table
  6730. CIP.nodeSize = 512;             // 512-byte node size (or 1024, 2048 bytes)
  6731. rez = BULLET(&CIP);
  6732. if (rez) {
  6733.    printf("Failed index file create.  Err: %d\n",rez);
  6734.    return(rez);
  6735. }
  6736.  
  6737. // Open the index file (what we just created above).
  6738. // As with the index-create, the index-open requires the handle of the data
  6739. // file which this index file indexes.
  6740.  
  6741. OP.func = OPEN_INDEX_XB;
  6742. OP.filenamePtr = nameIX3;
  6743. OP.asMode = READWRITE | DENYNONE;
  6744. OP.xbLink = dataID;
  6745. rez = BULLET(&OP);
  6746. if (rez) {
  6747.    printf("Failed index file open.  Err: %d\n",rez);
  6748.    return(rez);
  6749. }
  6750. indexID = OP.handle;
  6751.  
  6752. // at this point, both the data and index files are open and accessible
  6753.  
  6754. // |
  6755. // | do work as required, then, when done, close them
  6756. // |
  6757.  
  6758. if (indexID) {
  6759.    HP.func = CLOSE_INDEX_XB;
  6760.    HP.handle = indexID;
  6761.    rez = BULLET(&HP);
  6762.    if (rez)
  6763.       printf("Failed index file close.  Err: %d\n",rez);
  6764. }
  6765.  
  6766. if (dataID) {
  6767.    HP.func = CLOSE_DATA_XB;
  6768.    HP.handle = dataID;
  6769.    rez = BULLET(&HP);
  6770.    if (rez)
  6771.       printf("Failed data file close.  Err: %d\n",rez);
  6772. }
  6773.  
  6774.  
  6775. ΓòÉΓòÉΓòÉ 10.12. Read Data and Index Header ΓòÉΓòÉΓòÉ
  6776.  
  6777. #include "bullet_2.h"
  6778.  
  6779. HANDLEPACK HP;                  // packs used here
  6780.  
  6781. // Since it is recommended that a full-lock be in force before reloading
  6782. // data or index headers, and since performing a full lock from BULLET does
  6783. // itself reload the header, this routine would not normally be used.
  6784. // However, if you are doing your own locking, then you need to call this.
  6785.  
  6786. rez = YourExternalControlLockRoutine;  // so you have your own locks...
  6787.  
  6788. if (rez==0) {
  6789.  
  6790.    if (youWantDataReload) {
  6791.       HP.func = READ_DATA_HEADER_XB;
  6792.       HP.func = dataID;
  6793.    }
  6794.    else {
  6795.       HP.func = READ_INDEX_HEADER_XB;
  6796.       HP.func = indexID;
  6797.    }
  6798.    rez = BULLET(&HP);
  6799.  
  6800.    // since locked, release lock regardless rez value
  6801.  
  6802.    rez2 = YourExternalControlUnlockRoutine;
  6803. }
  6804.  
  6805. // Be sure to read the explanation above
  6806.  
  6807.  
  6808. ΓòÉΓòÉΓòÉ 10.13. Flush Data and Index Header ΓòÉΓòÉΓòÉ
  6809.  
  6810. #include "bullet_2.h"
  6811.  
  6812. HANDLEPACK HP;                  // packs used here
  6813.  
  6814. // While BULLET automatically flushes data and index info whenever
  6815. // a BULLET file is unlocked from a full-lock (and if it
  6816. // is needed), you may to flush more frequently.
  6817.  
  6818. // It is recommended that you have a full-lock on the file before
  6819. // flushing.  In normal use, you would always have a full-lock when
  6820. // writing to a file (the only time you need to flush is if the file
  6821. // has been written to).  If you are, for whatever reason, keeping
  6822. // the file locked, and are updating it repeatedly, and have no
  6823. // intention of unlocking (and thereby flushing it) any time soon,
  6824. // you may do a manual flush to ensure that the disk image matches
  6825. // the memory image (in case the power goes out and you have no UPS)
  6826.  
  6827. if (youWantDataFlush) {
  6828.    HP.func = FLUSH_DATA_HEADER_XB;
  6829.    HP.func = dataID;
  6830. }
  6831. else {
  6832.    HP.func = FLUSH_INDEX_HEADER_XB;
  6833.    HP.func = indexID;
  6834. }
  6835. rez = BULLET(&HP);
  6836.  
  6837. // Only if the file has been changed does a flush actually write to disk.
  6838. // You should have an exclusive full-lock; a shared full-lock cannot be
  6839. // used since a shared lock does not allow writing to the file.
  6840.  
  6841.  
  6842. ΓòÉΓòÉΓòÉ 10.14. Copy (Add) a Subset of Records to a New File ΓòÉΓòÉΓòÉ
  6843.  
  6844. #include "bullet_2.h"
  6845.  
  6846. ACCESSPACK APo;                 // used when accessing original
  6847. ACCESSPACK APn;                 // used when accessing new
  6848. COPYPACK   CP;
  6849. HANDLEPACK HP;
  6850. OPENPACK   OP;                  // packs used here
  6851.  
  6852. RECTYPE ourRecord;              // as defined in Create example
  6853.  
  6854. // Assume an open, locked DBF data file, handle in dataID, and that you
  6855. // want to copy those records that are marked as deleted, one at a time, to a
  6856. // new file, prior to packing the database.  An extension to this procedure is
  6857. // to access each record in key order, and to copy each record to the new
  6858. // file, thereby giving a SORTED data file (also known as a clustered file).
  6859. // The lock must be a full-lock, but may be a shared full-lock.  A ZAP is done
  6860. // on the new file if the copy did not complete as expected.
  6861.  
  6862. // No indexed access is used in this example.
  6863.  
  6864. CP.func = COPY_DATA_HEADER_XB;
  6865. CP.handle = dataID;             // dataID is the original data file handle
  6866. CP.filenamePtr = "DELRECS.DBF"; // new file for deleted records
  6867. rez = BULLET(&CP);
  6868. if (rez) {
  6869.    printf("Failed header copy.  Err: %d\n",rez);
  6870.    return(rez);
  6871. }
  6872.  
  6873. // DELRECS.DBF now is exactly like the original, but has 0 records.  Since
  6874. // we're building this file, open it for exclusive use (DENYREADWRTE) --
  6875. // this is different from using the LOCK_XB routines since the lock is done
  6876. // at the file open level (no other process may even open it), whereas
  6877. // the LOCK_XB routines are at the access level (other processes may
  6878. // open the file, but may or may not access it).  You could instead use
  6879. // LOCK_DATA_XB for an exclusive full-lock, but this is simpler.
  6880.  
  6881. OP.func = OPEN_DATA_XB;
  6882. OP.filenamePtr = "DELRECS.DBF";         // open it
  6883. OP.asMode = READWRITE | DENYREADWRITE;  // for exclusive use
  6884. rez = BULLET(&OP);
  6885. if (rez) {
  6886.    printf("Failed new file open.  Err: %d\n",rez);
  6887.    return(rez);
  6888. }
  6889.  
  6890. // Now have two files open:  the original, with all the records, and
  6891. // the new, with no records.  The procedure here is to get all original
  6892. // records, check each for being deleted, if so, add that record (copy it)
  6893. // to the new file.  After copying, the original file is packed so that
  6894. // all deleted records are removed.  Then an index to it is reindexed.
  6895.  
  6896. // most BULLET pack members will be invariant within loops... (low overhead!)
  6897.  
  6898. APn.func = ADD_RECORD_XB;       // AccessPack for the new file
  6899. APn.handle = OP.handle;         // the handle just opened above
  6900. APn.recPtr = &ourRecord;
  6901.  
  6902. APo.func = GET_RECORD_XB;       // AccessPack for the original file
  6903. APo.handle = dataID;
  6904. APo.recNo = 1;                  // start at the first record
  6905. APo.recPtr = &ourRecord;        // read data into this
  6906. rez = BULLET(&APo);             // read the first data record
  6907.  
  6908. while (rez==0) {
  6909.  
  6910.    // check if this record is deleted, if so copy it else continue
  6911.  
  6912.    if (ourRecord.tag = '*') {
  6913.       rez = BULLET(&APn);       // add it to the new file
  6914.       if (rez) break;
  6915.       // here APn.recNo is the record number used for the just-added record
  6916.    }
  6917.  
  6918.    // This while() loop could have been a for() loop if we had used
  6919.    // STAT_DATA_XB to get the number of records, but in this example,
  6920.    // the original file is read until EXB_BAD_RECNO is returned,
  6921.    // indicating that the last record has been passed.
  6922.  
  6923.    APo.recNo++;                 // get next original record
  6924.    rez = BULLET(&APo);          // everything else is already setup
  6925. }
  6926.  
  6927. // the expected rez here is EXB_BAD_RECNO, any other then quit
  6928.  
  6929. if (rez != EXB_BAD_RECNO) {
  6930.     printf("Failed the while() loop, ZAPing new file.  Err: %d\n",rez);
  6931.  
  6932.     // As an example, if the copy failed to complete as expected, the
  6933.     // new file is ZAP'ed, removing any records that may have been copied
  6934.     // up to the point that the error occurred -- investigate failure and
  6935.     // restart process (you may want to just delete, rather than ZAP/CLOSE).
  6936.  
  6937.     HP.func = ZAP_DATA_HEADER_XB;
  6938.     HP.handle = APn.handle;     // the new file handle
  6939.     rez2 = BULLET(&HP);         // using 'rez2' to preserve initial error code
  6940.     if (rez2)
  6941.        printf("Failed ZAP!  Err: %d\n",rez2);
  6942.  
  6943.     HP.func = CLOSE_DATA_XB;    // close
  6944.     rez2 = BULLET(&HP);
  6945.     if (rez2)
  6946.        printf("Failed CLOSE!  Err: %d\n",rez2);
  6947.  
  6948.     return(rez);                // return initial error code
  6949. }
  6950.  
  6951. // done with the new file
  6952. // it contains all the records in the original marked as deleted
  6953.  
  6954. HP.func = CLOSE_DATA_XB;        // always use the correct pack for the routine
  6955. HP.handle = APn.handle;         // -- do not try to use AP when closing a file
  6956. rez = BULLET(&HP);
  6957. if (rez) return(rez);
  6958.  
  6959. // Pack the original data file, now that we've "saved" the delete-marked recs.
  6960. // Note: You may want to use BACKUP_XB before using this next routine
  6961. // in case a serious error occurs.  BULLET packs in place!  Also, before
  6962. // packing, memos belonging to records about to be deleted should have
  6963. // have been deleted before packing.  Neither is shown here.
  6964.  
  6965. APo.func = PACK_RECORDS_XB;
  6966. rez = BULLET(&APo);
  6967. if (rez==0) {
  6968.  
  6969.    // After a pack, you must reindex any related index files.
  6970.    // Assume here one index file, handle in indexID
  6971.  
  6972.    APo.func = REINDEX_XB;
  6973.    APo.handle = indexID;
  6974.    rez = BULLET(&APo);  // rez is not errc, but is pack # than failed
  6975.    if (rez)
  6976.       printf("Failed reindex.  Err: %d\n",APo.stat);
  6977. }
  6978. else {
  6979.    printf("Failed packed!  Recommend restore from backup.  Err: %d\n",rez);
  6980.    printf("Note: Unless error is known to not be severe.\n");
  6981. }
  6982.  
  6983. // Here and rez==0 then everything went as planned.
  6984.  
  6985. return(rez);
  6986.  
  6987.  
  6988. ΓòÉΓòÉΓòÉ 10.15. Zap Index File ΓòÉΓòÉΓòÉ
  6989.  
  6990. #include "bullet_2.h"
  6991.  
  6992. HANDLEPACK HP;                  // packs used here
  6993.  
  6994. // Since BULLET reindexes in place, there's typically no need to use
  6995. // ZAP to reduce disk requirements (there won't be two separate file
  6996. // spaces since the reindex copies right over the old key data).
  6997.  
  6998. HP.func = ZAP_INDEX_HEADER_XB;
  6999. HP.handle = indexToZap;
  7000. rez = BULLET(&HP);
  7001. if (rez) return(rez);
  7002.  
  7003.  
  7004. ΓòÉΓòÉΓòÉ 10.16. Get Descriptor, Using a DBF Not Created by Bullet ΓòÉΓòÉΓòÉ
  7005.  
  7006. #include <os2.h>
  7007. #include <stdio.h>
  7008. #include <stdlib.h>
  7009. #include <string.h>
  7010.  
  7011. #include "bullet_2.h"
  7012.  
  7013. int main(int argc,char *argv[]) {
  7014.  
  7015. INITPACK IP;
  7016. EXITPACK EP;
  7017. DESCRIPTORPACK DP;
  7018. OPENPACK OP;
  7019. HANDLEPACK HP;
  7020. STATDATAPACK SDP;
  7021. ACCESSPACK AP;          // packs used here
  7022.  
  7023. PFIELDDESCTYPE fieldDescPtr;    // pointer to field descriptor base allocation
  7024. PFIELDDESCTYPE fdPtr;           // roving pointer to any field's descriptor
  7025.  
  7026. CHAR dataRec[8192];     // 'unknown' record layout since reading "any" DBF
  7027. CHAR  fmt[32];          // printf() fmt string for on-the-fly formatting
  7028. ULONG dataID;           // handle of DBF
  7029. LONG  recNo;            // loop counter
  7030. BYTE  fldNo;            // loop counter2
  7031. int   rez;              // primary op return code
  7032. int   rez2;             // secondary op return code (so to perserve primary rc)
  7033.  
  7034. if (argc < 2) {
  7035.    puts("Use: C>progname anyfile.dbf");
  7036.    return(1);
  7037. }
  7038.  
  7039. // init Bullet
  7040.  
  7041. IP.func = INIT_XB;
  7042. IP.JFTsize = 20;                // 20 handles is all we need here
  7043. rez = BULLET(&IP);
  7044. if (rez!=0) {
  7045.    printf("INIT_XB failed: %d\n",rez);
  7046.    return(1);
  7047. }
  7048.  
  7049. // open existing DBF as named in command line
  7050.  
  7051. OP.func = OPEN_DATA_XB;
  7052. OP.filenamePtr = argv[1];
  7053. OP.asMode = READWRITE | DENYNONE;
  7054. rez = BULLET(&OP);
  7055. if (rez==0) {
  7056.  
  7057.    dataID = OP.handle;
  7058.  
  7059.    SDP.func = STAT_DATA_XB;
  7060.    SDP.handle = dataID;
  7061.    rez = BULLET(&SDP);
  7062.    if (rez==0) {
  7063.  
  7064.       // allocate field descriptors needed (SDP.fields is number needed)
  7065.       // calloc() used since 0-filled storage is required
  7066.  
  7067.       fieldDescPtr = calloc(SDP.fields,sizeof(FIELDDESCTYPE));
  7068.  
  7069.       if (fieldDescPtr != NULL) {
  7070.  
  7071.          fdPtr = fieldDescPtr;          // fdPtr->each descriptor
  7072.  
  7073.          // read each field descriptor from Bullet, storing to our program
  7074.          // show each for display
  7075.  
  7076.          //      1234567890-123456789-123456789-12345
  7077.          printf("FLD#   FIELDNAME  T  LEN.DEC  OFFSET\n");
  7078.  
  7079.          DP.func = GET_DESCRIPTOR_XB;
  7080.          DP.handle = dataID;
  7081.          for (fldNo=1;fldNo <= SDP.fields;fldNo++) {
  7082.  
  7083.             DP.fieldNumber = fldNo;
  7084.             rez = BULLET(&DP);
  7085.             if (rez==0) {
  7086.  
  7087.                strcpy(fdPtr->fieldName, DP.FD.fieldName);
  7088.                fdPtr->fieldType = DP.FD.fieldType;
  7089.                fdPtr->fieldLen = DP.FD.fieldLen;
  7090.                fdPtr->fieldDC = DP.FD.fieldDC;
  7091.                fdPtr->fieldDA = DP.fieldOffset;
  7092.                printf("%3u   %-10s  %c  %3u.%1u     %4u\n",
  7093.                   fldNo,
  7094.                   fdPtr->fieldName,
  7095.                   fdPtr->fieldType,
  7096.                   (ULONG) fdPtr->fieldLen,
  7097.                   (ULONG) fdPtr->fieldDC,
  7098.                   fdPtr->fieldDA);
  7099.                fdPtr++;                 // next field descriptor
  7100.             }
  7101.             else
  7102.                break;
  7103.          }
  7104.  
  7105.          // An interesting item above is where fdPtr->fieldDA is set to
  7106.          // DP.fieldOffset.  fieldDA is a run-time storage area that in
  7107.          // dBASE is used to directly access the field (DA="direct access").
  7108.          // It has no meaning except for that particular run (it is a memory
  7109.          // address). In this program example I use it to store the offset
  7110.          // of the field, relative the start of the record buffer (where the
  7111.          // tag byte = offset 0).  You could just as easily use some of the
  7112.          // 12 reserved bytes left over in the descriptor, as I do for the
  7113.          // alternate field length.  But, since fieldDA is already there, and
  7114.          // not used otherwise, it makes sense to use it.
  7115.  
  7116.          // Now have all we need to know about the DBF fields, having just
  7117.          // read and stored the field descriptors.  For this example, we
  7118.          // grab the first nine records and spit them out, by field, in record
  7119.          // number order (no indexing used).
  7120.  
  7121.          if (SDP.records != 0) {
  7122.  
  7123.             AP.func = GET_RECORD_XB;
  7124.             AP.handle = dataID;
  7125.             AP.recPtr = &dataRec;
  7126.  
  7127.             for (recNo=1;recNo <= 9; recNo++) {
  7128.  
  7129.                printf("\nrecNo %u: ",recNo);    // show line number
  7130.                AP.recNo = recNo;                // get this record #...
  7131.                rez = BULLET(&AP);               // ...to dataRec buffer
  7132.                if (rez==0) {
  7133.                   printf("%.1s ",(CHAR *) dataRec); // show if deleted or not
  7134.  
  7135.                   fdPtr = fieldDescPtr; // fdPtr->first field descriptor
  7136.  
  7137.                   for (fldNo=1;fldNo <= SDP.fields;fldNo++) {
  7138.  
  7139.                      // No special formatting is done on this output for this
  7140.                      // example -- since standard DBF data is always in pure
  7141.                      // ASCII form, all is printable.
  7142.  
  7143.                      switch (fdPtr->fieldType) {
  7144.                      case 'C':  // text
  7145.                      case 'D':  // date, show as-is
  7146.                      case 'L':  // logical, show as-is
  7147.                      case 'M':  // memo field (block number in ASCII)
  7148.                      case 'N':  // numeric (ASCII)
  7149.  
  7150.                         // make fmt[] string like this: "%xx.xxs"
  7151.                         // where xx is field length for this field
  7152.  
  7153.                         sprintf(fmt,"%%-%i.%is ",
  7154.                                 fdPtr->fieldLen,
  7155.                                 fdPtr->fieldLen);
  7156.  
  7157.                         // fdPtr->fieldDA=offset of the field within the record
  7158.                         // so it plus dataRec (buffer base) results in the
  7159.                         // offset of the current field we are processing
  7160.  
  7161.                         printf(fmt,dataRec+fdPtr->fieldDA);
  7162.                         break;
  7163.                      default:
  7164.                         printf("\nUnknown field type: %c\n",fdPtr->fieldType);
  7165.                      } // switch
  7166.  
  7167.                      fdPtr += 1;                  // next field's descriptor
  7168.  
  7169.                   } // for fields
  7170.                } // if record read
  7171.  
  7172.                else {
  7173.                   if (rez==EXB_BAD_RECNO)       // if < for-count records in DBF
  7174.                      rez=0;                     // then would get this error
  7175.                   else
  7176.                      printf("Failed GET_RECORD_XB, err: %d\n",rez);
  7177.                   break;                        // break for any ELSE case
  7178.                }
  7179.  
  7180.             } // for records
  7181.             if (rez==0) printf("\nDone.\n"); // all FOR recs done
  7182.          }
  7183.          else
  7184.             printf("No records in file\n");
  7185.  
  7186.          free(fieldDescPtr);
  7187.       }
  7188.       else
  7189.          printf("calloc failed!\n");
  7190.    }
  7191.    else
  7192.       printf("STAT_DATA_XB failed: %d\n",rez);
  7193.  
  7194.    HP.func = CLOSE_DATA_XB;
  7195.    HP.handle = dataID;
  7196.    rez2 = BULLET(&HP);
  7197. }
  7198. else
  7199.    printf("OPEN_DATA_XB failed: %d\n",rez);
  7200.  
  7201. EP.func = EXIT_XB;
  7202. rez2=BULLET(&EP);
  7203.  
  7204. printf("\nPress ENTER to exit");
  7205. getchar();
  7206. if (rez==0) rez=rez2;  // rez is more important, but if 0 use rez2 result
  7207. return(rez);
  7208. }
  7209.  
  7210. The above is a complete program.  Running it against a sample DBF results in 
  7211. the following output: 
  7212.  
  7213. FLD#   FIELDNAME  T  LEN.DEC  OFFSET
  7214.   1   SSN         C    9.0        1
  7215.   2   LNAME       C   16.0       10
  7216.   3   FNAME       C   16.0       26
  7217.   4   HIRED       D    8.0       42
  7218.   5   DEPT_ID     C    6.0       50
  7219.  
  7220. recNo 1:   465309999 Que              Barbie           19900131 BOSS
  7221. recNo 2:   445038888 Stewart          Jackie           19910228 ACC
  7222. recNo 3:   760443232 Whitman          Kelly            19920414 HUM
  7223. recNo 4:   845309944 Beatty           Leslie           19940122 PRG
  7224. recNo 5:   555033388 Jasper           Amy              19930230 PRG
  7225. recNo 6:   430443222 Hauntos          Poco             19920414 PRG
  7226. recNo 7:   365502949 Hopkins          Lisa             19910121 PRG
  7227. recNo 8:   685733868 Leonard          Rosina           19850218 PRG
  7228. recNo 9:   500945242 Morton           Holly            19950406 PHY
  7229. Done.
  7230.  
  7231. Press ENTER to exit
  7232.  
  7233.  
  7234. ΓòÉΓòÉΓòÉ 10.17. Update a Data Record ΓòÉΓòÉΓòÉ
  7235.  
  7236. #include "bullet_2.h"
  7237.  
  7238. ACCESSPACK AP;                  // packs used here
  7239.  
  7240. typedef struct _RECTYPE {
  7241.  CHAR tag;              // record tag, init to SPACE, '*' means deleted
  7242.  CHAR userSSN[9];       // first field in DBF (not 0-terminated in this case)
  7243.  CHAR userScore[6];     // second field (also not 0T)
  7244. } RECTYPE;              // (total record length is 16 bytes)
  7245. RECTYPE ourRecord;
  7246.  
  7247. // This excerpt demonstrates how to update (change) a record.
  7248. // The idea is to get the current contents of a record (by record
  7249. // number since no index is used for this update routine), change
  7250. // what needs changing, then write it back.  Under no circumstances
  7251. // should you change any field that is used as a key by an index, or
  7252. // as a foreign key, or in any other way removes the referential
  7253. // integrity of the database.  If you need to change a key field, then
  7254. // you must use UPDATE_XB.
  7255.  
  7256. AP.func = GET_RECORD_XB;
  7257. AP.handle = dataID;
  7258. AP.recNo = recordToUpdate;
  7259. AP.recPtr = &ourRecord;
  7260. rez = BULLET(&AP);
  7261. if (rez) return(rez);
  7262.  
  7263. // ourRecord has data stored at record number recordToUpdate -- since
  7264. // userScore is not used as a key field, this routine may be used to
  7265. // modify the contents of that field.  Since numbers are stored as ASCII
  7266. // text in compatible DBF files, must convert to binary, perform needed
  7267. // math, then convert back to text:
  7268.  
  7269. //t = atol(ourRecord.userScore);  // use scanf() since not 0T
  7270. sscanf(t,"%6u",&ourRecord.userScore);
  7271. t = t + ClassCurve;             // increase each score by curve value
  7272. sprintf(ourRecord.userScore,"%6.6u",t)
  7273.  
  7274. AP.func = UPDATE_RECORD_XB;     // other AP values already set up from GET
  7275. rez = BULLET(&AP);              // write out the record with the new score
  7276. if (rez) return(rez);
  7277.  
  7278.  
  7279. ΓòÉΓòÉΓòÉ 10.18. Delete, Undelete, 'Debump' a Data Record ΓòÉΓòÉΓòÉ
  7280.  
  7281. #include "bullet_2.h"
  7282.  
  7283. ACCESSPACK AP;                  // packs used here
  7284.  
  7285. // delete or undelete or remove (debump)
  7286.  
  7287. switch(*requestMsg) {
  7288. case 'delete':
  7289.    AP.func = DELETE_RECORD_XB;  // places a '*' in .tag byte
  7290.    break;
  7291. case 'undelete':
  7292.    AP.func = UNDELETE_RECORD_XB; // places a SPACE in .tag byte
  7293.    break;
  7294. case 'debump':
  7295.    AP.func = DEBUMP_RECORD_XB;  // physically removes record from file, but
  7296.    break;                       // fails if AP.recNo is not last record number
  7297. }
  7298.  
  7299. AP.handle = dataID;             // same for all three
  7300. AP.recNo = recordNumber;
  7301. rez = BULLET(&AP);
  7302. return(rez);
  7303.  
  7304.  
  7305. ΓòÉΓòÉΓòÉ 10.19. Reading Memo Records ΓòÉΓòÉΓòÉ
  7306.  
  7307. #include "bullet_2.h"
  7308.  
  7309. ACCESSPACK AP;
  7310. LOCKPACK LP;
  7311. MEMODATAPACK MDP;       // packs used here
  7312.  
  7313. typedef struct _RECTYPE {
  7314.  CHAR tag;              // record tag, init to SPACE, '*' means deleted
  7315.  CHAR userSSN[9];       // first field in DBF (not 0-terminated in this case)
  7316.  CHAR userMemo[10];     // second field (also not 0T), is memo field type
  7317. } RECTYPE;
  7318. RECTYPE someRecord;
  7319.  
  7320. // a minimum shared record lock is required on the DBF record that owns
  7321. // memoNumber in this example, since only reading of the single memo is done
  7322.  
  7323. LP.func = LOCK_DATA_XB;
  7324. LP.handle = dataID;
  7325. LP.dlMode = LOCK_SHARED;        // only reading here, shared record lock is okay
  7326. LP.recStart = recordToGet;      // lock this record
  7327. LP.recCount = 1;                // and only this record
  7328. rez = BULLET(&LP);
  7329. if (rez) return(rez);
  7330.  
  7331. // hereafter, must unlock before exiting
  7332.  
  7333. AP.func = GET_RECORD_XB;
  7334. AP.handle = dataID;
  7335. AP.recNo = recordToGet;
  7336. AP.recPtr = &someRecord;        // load someRecord with data on disk
  7337. rez = BULLET(&AP);
  7338. if (rez) return(rez);           // UNLOCK! before doing this exit
  7339.  
  7340. // memoNumber = atol(someRecord.userMemo); // the memo number (0 if none)
  7341. sscanf(memoNumber,"%10u",&someRecord.userMemo);
  7342.  
  7343. // this code reads the number of data bytes in the memo and allocates a
  7344. // run-time buffer to read that memo into
  7345.  
  7346. MDP.func = GET_MEMO_SIZE_XB;
  7347. MDP.dbfHandle = dataID;         // handle of the DBF this memo belongs to
  7348. MDP.memoNo = memoNumber;        // memo number to get size of (1=first)
  7349. rez = BULLET(&MDP);             // (returns an error if memoNumber is 0)
  7350. if (rez==0) {
  7351.  
  7352.    // BULLET does maintain 0-sized memo records, so you may want to check
  7353.    // if MDP.memoBytes from GET_MEMO_SIZE_XB is 0, and skip processing if so
  7354.  
  7355.    memoBytesToRead = MDP.memoBytes;         // since overwritten by next call
  7356.    memoBufferPtr = malloc(memoBytesToRead); // assuming you want it all at once
  7357.  
  7358.    if (memoBufferPtr) {
  7359.  
  7360.       MDP.func = GET_MEMO_XB;
  7361.       MDP.dbfHandle = dataID;      // same as before, as is .memoNo
  7362.       MDP.memoNo = memoNumber;
  7363.       MDP.memoPtr = memoBufferPtr; // memo disk data is loaded into this buffer
  7364.       MDP.memoOffset = 0;          // read from very first memo data byte
  7365.       MDP.memoBytes = memoBytesToRead;
  7366.  
  7367.       // MDP.memoBytes is already set to the total data size -- you may read
  7368.       // fewer bytes, and you may use .offset to move through the memo data
  7369.       // chunks at a time, rather than all at once -- the above simply reloads
  7370.       // it with the same count, since here memoBytesToRead==MDP.memoBytes
  7371.  
  7372.       rez = BULLET(&MDP);          // returns with MDP.memoBytes= bytes read
  7373.       if (rez==0) {
  7374.  
  7375.          // if (MDP.memoBytes != memoBytesToRead)
  7376.          //   printf("Could not read all bytes requested - probably at end of memo\n");
  7377.          // above would not happen in this case since the exact size was requested
  7378.  
  7379.          // process as required (here passes buffer ptr and bytes actually read)
  7380.  
  7381.          DoWhatYouWillWithThisMemoData(memoBufferPtr,MDP.memoBytes);
  7382.       }
  7383.       free(memoBufferPtr);
  7384.    }
  7385.    else rez=8;  // malloc failed, return 8=not enough memory
  7386. }
  7387.  
  7388. LP.func = UNLOCK_DATA_XB;
  7389. LP.handle = dataID;
  7390. LP.recStart = recordToGet;      // unlock this record
  7391. LP.recCount = 1;                // and only this record
  7392. rez2 = BULLET(&LP);
  7393.  
  7394. if (rez==0) rez=rez2;
  7395. return(rez);
  7396.  
  7397.  
  7398. ΓòÉΓòÉΓòÉ 10.20. Add, Update, Delete a Memo Record ΓòÉΓòÉΓòÉ
  7399.  
  7400. #include "bullet_2.h"
  7401.  
  7402. ACCESSPACK AP;
  7403. LOCKPACK LP;
  7404. MEMODATAPACK MDP;       // packs used here
  7405.  
  7406. typedef struct _RECTYPE {
  7407.  CHAR tag;
  7408.  CHAR userSSN[9];
  7409.  CHAR userMemo[10];
  7410. } RECTYPE;
  7411. RECTYPE someRecord;
  7412.  
  7413. // an exclusive lock is required on the DBF file that owns this memo file
  7414. // since writing is done to the memo file (memo file header, especially)
  7415.  
  7416. LP.func = LOCK_DATA_XB;
  7417. LP.handle = dataID;
  7418. LP.dlMode = LOCK_EXCLUSIVE;     // writing here, exclusive full lock required
  7419. LP.recStart = 0;                // lock all
  7420. rez = BULLET(&LP);
  7421. if (rez) return(rez);
  7422.  
  7423. // hereafter, must unlock before exiting
  7424.  
  7425. AP.func = GET_RECORD_XB;
  7426. AP.handle = dataID;
  7427. AP.recNo = recordToGet;
  7428. AP.recPtr = &someRecord;        // load someRecord with data on disk
  7429. rez = BULLET(&AP);
  7430. if (rez) return(rez);           // UNLOCK! before doing this exit
  7431.  
  7432. // memoNumber = atol(someRecord.userMemo); // the memo number (0 if none)
  7433. sscanf(memoNumber,"%10u",&someRecord.userMemo);
  7434.  
  7435. // if there is no current memo, this example adds one
  7436. // if there is, this example updates it by:
  7437. //   - changing the first 16 bytes to "Kilroy was here."
  7438. //   - adding the text "Was updated." to the end of the current memo data
  7439. // the example then deletes the memo
  7440.  
  7441. CHAR kilroyStr[] = "Kilroy was here.";
  7442. CHAR updateStr[] = "Was updated.";
  7443. CHAR newStr[] = "New.";
  7444.  
  7445. if (memoNumber) {
  7446.  
  7447.    // modify the current memo -- first, the text "Kilroy was here." is
  7448.    // placed at the start of the memo, then the memo size is gotten (in
  7449.    // case the original memo size were less than the size of "Kilroy...").
  7450.  
  7451.    MDP.func = UPDATE_MEMO_XB;
  7452.    MDP.dbfHandle = dataID;      // handle of the DBF this memo belongs to
  7453.    MDP.memoNo = memoNumber;     // memo number to update (1=first)
  7454.    MDP.memoPtr = kilroyStr;     // data to write
  7455.    MDP.memoOffset = 0;          // start write at first byte of memo
  7456.    MDP.memoBytes = strlen(kilroyStr); // bytes to write
  7457.    rez = BULLET(&MDP);
  7458.  
  7459.       // the first 16 bytes of the memo now say kilroyStr (overwrote what was there)
  7460.       // the memo size changes only if the original memo was < 16 bytes, in
  7461.       // which case the size is now 16
  7462.  
  7463.    if (rez==0) {
  7464.       printf("%s overwrote first 16 bytes\n",kilroyStr);
  7465.  
  7466.       // must check if the update resulted in a new memo block being
  7467.       // used (if the update required more allocation blocks), and if
  7468.       // so must update the DBF field storing the memo number
  7469.       // MDP.memoNo is the memo number returned, memoNumber the original number
  7470.  
  7471.       // IT CAN BE ASSUMED IN THIS PARTICULAR example that this will never
  7472.       // be needed since the update modified the first 16 bytes of the
  7473.       // memo only, and so would never have required any more blocks --
  7474.       // however, unless you know before-hand that the update will not need
  7475.       // more allocation blocks (not difficult, if you know the block size,
  7476.       // overhead bytes (8), and your offset and bytes to write), it should
  7477.       // be checked -- hint: as with all Bullet routines, the idea is to
  7478.       // wrap up these separate operations into nice, neat callable routines
  7479.       // that take care of your particular need; there are no doubt 1000s of
  7480.       // variations -- pick one you can deal with.
  7481.  
  7482.       if (MDP.memoNo != memoNumber) {
  7483.          sprintf(someRecord.userMemo,"%10.10u",MDP.memoNo)
  7484.          memoNumber = MDP.memoNo;       // set original to new for next update
  7485.  
  7486.          // rather than updating here, and possibly again below, you
  7487.          // may elect to set a flag and then do the DBF update at the end, once
  7488.          // again -- this updates the _data_ record, in the DBF file:
  7489.  
  7490.          AP.func = UPDATE_RECORD_XB;    // this updates the data record only
  7491.          AP.handle = dataID;
  7492.          AP.recNo = recordToGet;
  7493.          AP.recPtr = &someRecord;       // write the new data
  7494.          rez = BULLET(&AP);
  7495.          if (rez) return(rez);          // UNLOCK! before doing this exit
  7496.       }
  7497.  
  7498.       MDP.func = GET_MEMO_SIZE_XB;  // other MDP members already set above
  7499.       rez = BULLET(&MDP);
  7500.       if (rez=0) {              // size of memo is at least 16 (from kilroyStr)
  7501.                                 // but may be bigger if was bigger before
  7502.          MDP.func = UPDATE_MEMO_XB;
  7503.          MDP.memoPtr = updateStr;
  7504.  
  7505.          // the current memo size is used as the offset for the appending of
  7506.          // the updateStr bytes (offset is 0-based, so using MDP.memoBytes
  7507.          // results in the offset being the current size + 1)
  7508.  
  7509.          MDP.memoOffset = MDP.memoBytes;
  7510.          MDP.memoBytes = strlen(updateStr);
  7511.          rez = BULLET(&MDP);   // returns with MDP.memoNo
  7512.                                // bytes written==MDP.memoBytes always
  7513.          if (rez==0)
  7514.  
  7515.             printf("%s appended to memo\n",updateStr);
  7516.             // _minimum_ memo contents now is kilroyStr plus updateStr
  7517.             // more if original memo was > 16 bytes
  7518.  
  7519.             if (MDP.memoNo != memoNumber) {
  7520.                sprintf(someRecord.userMemo,"%10.10u",MDP.memoNo)
  7521.                AP.func = UPDATE_RECORD_XB;         //
  7522.                AP.handle = dataID;                 // as explained above
  7523.                AP.recNo = recordToGet;             //
  7524.                AP.recPtr = &someRecord;
  7525.                rez = BULLET(&AP);
  7526.                if (rez) return(rez);    // actually must unlock before exit!
  7527.             }
  7528.          } // memo update #2 failed
  7529.       } // memo size failed
  7530.    }
  7531.    else
  7532.       printf("update failed, err: %d\n",rez); // disk full probably
  7533. }
  7534. else {
  7535.  
  7536.    // no current memo, add one
  7537.  
  7538.    MDP.func = ADD_MEMO_XB;
  7539.    MDP.dbfHandle = dataID;      // handle of the DBF this memo belongs to
  7540.    MDP.memoPtr = newStr;        // data to write
  7541.    MDP.memoBytes = strlen(newStr); // bytes to write
  7542.    rez = BULLET(&MDP);
  7543.    if (rez==0) {
  7544.       sprintf(someRecord.userMemo,"%10.10u",MDP.memoNo)
  7545.       AP.func = UPDATE_RECORD_XB;         //
  7546.       AP.handle = dataID;                 // as explained above
  7547.       AP.recNo = recordToGet;             //
  7548.       AP.recPtr = &someRecord;
  7549.       rez = BULLET(&AP);
  7550.    }
  7551.    else
  7552.      printf("add failed, err: %d\n",rez);
  7553. }
  7554.  
  7555. // delete the memo just operated on
  7556.  
  7557. if (rez==0) {
  7558.  
  7559.    MDP.func = DELETE_MEMO_XB;
  7560.    // MDP.memoNo is already set
  7561.    rez = BULLET(&MDP);
  7562.    if (rez==0) {
  7563.       strcpy(someRecord.userMemo,"          ");// DBF memo field to all spaces
  7564.       AP.func = UPDATE_RECORD_XB;         //
  7565.       AP.handle = dataID;                 // as explained above
  7566.       AP.recNo = recordToGet;             //
  7567.       AP.recPtr = &someRecord;
  7568.       rez = BULLET(&AP);
  7569.    }
  7570.    else
  7571.      printf("delete failed, err: %d\n",rez);
  7572. }
  7573.  
  7574. LP.func = UNLOCK_DATA_XB;
  7575. LP.handle = dataID;
  7576. LP.recStart = 0;                // unlock all
  7577. rez2 = BULLET(&LP);
  7578.  
  7579. if (rez==0) rez=rez2;
  7580. return(rez);
  7581.  
  7582.  
  7583. ΓòÉΓòÉΓòÉ 10.21. Memo Bypass (Memo Create, Open, Close, Read/Flush Header) ΓòÉΓòÉΓòÉ
  7584.  
  7585. #include "bullet_2.h"
  7586.  
  7587. MEMODATAPACK MDP;               // packs used here
  7588.  
  7589.  
  7590. //  These five routines are normally performed automatically, as described
  7591. //  in the main documentation, and seldom would need to be called directly.
  7592.  
  7593.  
  7594. MDP.func = MEMO_BYPASS_XB;
  7595. MDP.dbfHandle = dataID;         // handle of DBF
  7596. MDP.memoBypass = BypassRoutineToDo;
  7597.  
  7598. // where BypassRoutineToDo is one of the following:
  7599. //
  7600. //   BYPASS_CREATE_MEMO
  7601. //   BYPASS_OPEN_MEMO
  7602. //   BYPASS_CLOSE_MEMO
  7603. //   BYPASS_READ_MEMO_HEADER
  7604. //   BYPASS_FLUSH_MEMO_HEADER
  7605.  
  7606. rez = BULLET(&MDP);
  7607. if (rez) return(rez);
  7608.  
  7609.  
  7610. ΓòÉΓòÉΓòÉ 10.22. Key Access Without Data Record Read ΓòÉΓòÉΓòÉ
  7611.  
  7612. #include "bullet_2.h"
  7613.  
  7614. CHAR keyBuffer[64];             // enough for the largest possible key
  7615.  
  7616. ACCESSPACK AP;                  // packs used here
  7617.  
  7618. // -----------------------------------------------------------
  7619. // this section starts at the first in-order key and reads all
  7620. // keys in the index file in order
  7621.  
  7622. AP.func = FIRST_KEY_XB;
  7623. AP.handle = indexID;
  7624. AP.keyPtr = keyBuffer;
  7625. rez = BULLET(&AP);
  7626. while (rez==0) {
  7627.  
  7628.    // show first 8 bytes of key, and the record number the key is for
  7629.    printf("%8.8s  %9.9lu\r", keyBuffer, AP.recNo);
  7630.  
  7631.    AP.func = NEXT_KEY_XB;       // and get the next key...
  7632.    rez = BULLET(&AP);           // until all keys accessed
  7633. };
  7634. if (rez!=EXB_END_OF_FILE) return(rez); // expected rez is EXB_END_OF_FILE
  7635.  
  7636.  
  7637. // ----------------------------------------------------------
  7638. // this section starts at the last in-order key and reads all
  7639. // keys in the index file in reverse order
  7640.  
  7641. AP.func = LAST_KEY_XB;
  7642. AP.handle = indexID;
  7643. AP.keyPtr = keyBuffer;
  7644. rez = BULLET(&AP);
  7645. while (rez==0) {
  7646.  
  7647.    // show first 8 bytes of key, and the record number the key is for
  7648.    printf("%8.8s  %9.9lu\r", keyBuffer, AP.recNo);
  7649.  
  7650.    AP.func = PREV_KEY_XB;       // and get the previous key...
  7651.    rez = BULLET(&AP);           // until all keys accessed
  7652. };
  7653. if (rez!=EXB_TOP_OF_FILE) return(rez); // expected rez is EXB_TOP_OF_FILE
  7654.  
  7655. // this section starts at the first key that starts with "SM", or if
  7656. // no keys do, the first key after "SM", and gets that key
  7657. // keys in the index file in reverse order
  7658.  
  7659. memset(keyBuffer,0,64);         // ensure remaining bytes are \0 (required)
  7660. strcpy(keyBuffer,"SM");         // get key of "SM", if present (not likely)
  7661. AP.func = EQUAL_KEY_XB;
  7662. AP.handle = indexID;
  7663. AP.keyPtr = keyBuffer;
  7664. rez = BULLET(&AP);
  7665.  
  7666. // since "SM" is only being used as a partial key search criterion,
  7667. // it won't be found (though, of course, it is a valid key) in this
  7668. // example -- however, by using NEXT_KEY_XB, the next key is accessed,
  7669. // say, for example, "SMITH"...  It could also be "TIMBU" if there were
  7670. // no keys with values greater than "SM" and less than "TIMBU".
  7671.  
  7672. // Be aware that if another thread in this process (repeat:
  7673. // this process!) is accessing this index file (it's not likely that
  7674. // you will write your could so that this would happen), then you
  7675. // can no longer rely on any multi-call key access to be an atomic
  7676. // operation.  If you need to have more than one thread access the
  7677. // same index (and you require NEXT_KEY_XB or PREV_KEY_XB), then you
  7678. // must semaphore protect your code so you don't try to access the same
  7679. // index file.
  7680.  
  7681. if (rez!=EXB_KEY_NOT_FOUND) {   // expected
  7682.    AP.func = NEXT_KEY_XB;       // so get the first key after "SM"
  7683.    AP.handle = indexID;
  7684.    AP.keyPtr = keyBuffer;
  7685.    rez = BULLET(&AP);
  7686.    if (rez==0)
  7687.       printf("The first key >= SM is %s\n",AP.keyBuffer);
  7688. }
  7689.  
  7690.  
  7691. ΓòÉΓòÉΓòÉ 10.23. Building and Storing Raw Key ΓòÉΓòÉΓòÉ
  7692.  
  7693. #include "bullet_2.h"
  7694.  
  7695. ACCESSPACK AP;                  // packs used here
  7696.  
  7697. // this example shows a simple database insert process
  7698. // INSERT_XB should be used instead since it does all this and then some
  7699. // files should be locked (not shown)
  7700.  
  7701. AP.func = ADD_RECORD_XB;
  7702. AP.handle = dataID;
  7703. AP.recPtr = &yourRecord;
  7704. rez = BULLET(&AP);
  7705. if (rez) return(rez);
  7706.  
  7707. // AP.recNo is returned by Bullet and will be used later
  7708.  
  7709. AP.func = BUILD_KEY_XB;
  7710. AP.handle = indexID;
  7711. AP.recPtr = &yourRecord;
  7712. AP.keyPtr = keyBuffer;          // CHAR keyBuffer[64];
  7713. rez = BULLET(&AP);
  7714. if (rez) return(rez);
  7715.  
  7716. // keyBuffer filled with key to store
  7717. // a \0\0 enumerator is attached if the index file was created with DUPS_ALLOWED
  7718.  
  7719. AP.func = STORE_KEY_XB;
  7720. AP.handle = indexID;
  7721. // AP.recNo is already set from the ADD_RECORD_XB call
  7722. AP.keyPtr = keyBuffer;
  7723. rez = BULLET(&AP);
  7724. if (rez) return(rez);
  7725.  
  7726. // if no error, the key was inserted in the index file and the record
  7727. // number was associated with that key -- next time you access that
  7728. // key, the record number is returned (along with the key itself) --
  7729. // and with that record number you access the data file
  7730.  
  7731. // when using this routine, you must check the error for a EXB_KEY_EXISTS
  7732. // error and if DUPS_ALLOWED, you must manage your own enumerator --
  7733. // INSERT_XB is the only routine that does this automatically so unless
  7734. // you have a real desire to manage this yourself (among other things)
  7735. // use INSERT_XB instead of all this.
  7736.  
  7737.  
  7738. ΓòÉΓòÉΓòÉ 10.24. Getting Current Key, Key for Rec/RecNo Pair, Deleting Key ΓòÉΓòÉΓòÉ
  7739.  
  7740. #include "bullet_2.h"
  7741.  
  7742. ACCESSPACK AP;
  7743. LOCKPACK LP;                    // packs used here
  7744.  
  7745. AP.func = GET_CURRENT_KEY_XB;
  7746. AP.handle = indexID;
  7747. AP.keyPtr = keyBuffer;          // current key placed here by Bullet
  7748. rez = BULLET(&AP);
  7749. if (rez) return(rez);
  7750. printf("The last accessed key for indexID is in keyBuffer, including any enumerator\n");
  7751.  
  7752. // This next example assumes that you are maintaining your own method of
  7753. // transaction rollback, and are about to delete the last item added to the
  7754. // database: in this case, the last data record is removed from the one
  7755. // DBF data file, and the key for that record is removed from the index file
  7756. // -- normally, you wouldn't do this, but if you have the need...
  7757.  
  7758. rez = InsertToDatabaseHoweverYouDoIt(yourPtr);
  7759.  
  7760. // Assume the above called succeeded, but you've decided, for whatever reason,
  7761. // that you want to backout the insert... normally, if you used INSERT_XB to
  7762. // insert a record/key into a database, you'd already have the record number
  7763. // used AND the key used for the record (for each if more than one) -- but for
  7764. // this example, assume that only the record number is known.  Steps done
  7765. // to remove the record and key for this would be:
  7766. //
  7767. //  1. Exclusive full-lock files
  7768. //  2. Get the record data at the record number (GET_RECORD_XB)
  7769. //  3. Get the key for this record/recNo pair (GET_KEY_FOR_RECORD_XB)
  7770. //  4. Delete the key (DELETE_KEY_XB) (delete the key before deleting the record)
  7771. //  5. Delete the record data (DEBUMP_RECORD_XB) (record must be last record in file)
  7772. //  6. Unlock files
  7773.  
  7774. // lock files being processed
  7775.  
  7776. LP.func = LOCK_XB;
  7777. LP.handle = indexID;            // also locks indexID's owner (its DBF)
  7778. LP.xlMode = LOCK_EXCLUSIVE;     // exclusive lock for index
  7779. LP.dlMode = LOCK_EXCLUSIVE;     // exclusive lock for data
  7780. LP.nextPtr = NULL;              // only one pack
  7781. rez = BULLET(&LP);
  7782. if (rez) return(LP.stat);       // rez for transaction-list is NOT the error
  7783.  
  7784. // get actual data record for record number
  7785.  
  7786. AP.func = GET_RECORD_XB;
  7787. AP.handle = dataID;
  7788. AP.recNo = recNoToDelete;       // get this record to...
  7789. AP.recPtr = &yourRecord;        // ...this data record buffer (a structure var)
  7790. rez = BULLET(&AP);
  7791. if (rez) goto MustAlwaysUnlock;
  7792.  
  7793. // now have the data record/data number pair --
  7794. // it must be the last physical record in the data file -- if this cannot
  7795. // be known, use STAT_DATA_XB to verify that recNoToDelete==SDP.records
  7796.  
  7797. AP.func = GET_KEY_FOR_RECORD_XB;
  7798. AP.handle = indexID;
  7799. AP.recNo = recNoToDelete;
  7800. AP.recPtr = &yourRecord;
  7801. AP.keyPtr = keyBuffer;          // CHAR keyBuffer[64]; key returned here
  7802. rez = BULLET(&AP);
  7803. if (rez) goto MustAlwaysUnlock;
  7804.  
  7805. // now have the key (with any attached enumerator) in keyBuffer, delete it
  7806.  
  7807. AP.func = DELETE_KEY_XB;
  7808. AP.handle = indexID;
  7809. AP.keyPtr = keyBuffer;          // was set with key by GET_KEY_FOR_RECORD_XB
  7810. rez = BULLET(&AP);
  7811. if (rez) goto MustAlwaysUnlock;
  7812.  
  7813. // and delete (physically remove) the data record
  7814.  
  7815. AP.func = DEBUMP_RECORD_XB;
  7816. AP.handle = dataID;
  7817. AP.recNo = recNoToDelete;
  7818. rez = BULLET(&AP);
  7819. // if (rez) goto MustAlwaysUnlock;
  7820.  
  7821. MustAlwaysUnlock:   // unlock ALWAYS required if lock succeeded
  7822.  
  7823. LP.func = UNLOCK_XB;
  7824. LP.handle = indexID;
  7825. LP.nextPtr = NULL;
  7826. rez2 = BULLET(&LP);
  7827. if (rez2) rez2=LP.stat; // rez for transaction-list is NOT the error
  7828.  
  7829. if (rez==0) rez=rez2;
  7830. return(rez);
  7831.  
  7832.  
  7833. ΓòÉΓòÉΓòÉ 10.25. Get Data by Key Order ΓòÉΓòÉΓòÉ
  7834.  
  7835. #include "bullet_2.h"
  7836.  
  7837. ACCESSPACK AP;                  // packs used here
  7838.  
  7839. // First example starts at first in-order data and moves through to last
  7840.  
  7841. AP.func = GET_FIRST_XB;
  7842. AP.handle = indexID;
  7843. AP.recPtr = &yourRecord;        // struct yourStructure yourRecord;
  7844. AP.keyPtr = keyBuffer;          // CHAR keyBuffer[64];
  7845. rez = BULLET(&AP);
  7846. if (rez) return(rez);
  7847. printf("The first in-order key is in keyBuffer and its record in yourRecord\n");
  7848.  
  7849. AP.func = GET_NEXT_XB;          // other parm same as set above
  7850. while (rez==0) {
  7851.    rez = BULLET(&AP);
  7852.    if (rez) break;
  7853.    printf("The next in-order key is in keyBuffer and its record in yourRecord\n");
  7854. }
  7855. if (rez==EXB_END_OF_FILE) rez==0; // expected rez after end of file
  7856. if (rez) return(rez);
  7857.  
  7858.  
  7859. // Second example starts at last in-order data and moves through to first
  7860. // note: since above already is past last, the call to GET_LAST_XB in
  7861. //       this example would not be necessary -- a call to GET_PREV_XB
  7862. //       could have been made directly -- however, it doesn't matter
  7863.  
  7864. AP.func = GET_LAST_XB;
  7865. AP.handle = indexID;
  7866. AP.recPtr = &yourRecord;
  7867. AP.keyPtr = keyBuffer;
  7868. rez = BULLET(&AP);
  7869. if (rez) return(rez);
  7870. printf("The last in-order key is in keyBuffer and its record in yourRecord\n");
  7871.  
  7872. AP.func = GET_PREV_XB;          // other parms same as set above
  7873. while (rez==0) {
  7874.    rez = BULLET(&AP);
  7875.    if (rez) break;
  7876.    printf("The previous in-order key is in keyBuffer and its record in yourRecord\n");
  7877. }
  7878. if (rez==EXB_TOP_OF_FILE) rez==0; // expected rez before at beginning of file
  7879. if (rez) return(rez);
  7880.  
  7881.  
  7882. // Third example performs a GET_EQUAL_OR_GREATER operation, typically
  7883. // used to locate to a key based on a partial search criterion
  7884.  
  7885. AP.func = GET_EQUAL_XB;
  7886. AP.handle = indexID;
  7887. AP.recPtr = &yourRecord;    // to be filled on return, if found
  7888.  
  7889. memset(keyBuffer,0,sizeof(keyBuffer);   // clear it out (required)
  7890. strcpy(keyBuffer,"KING");               // find first key starting with 'KING'
  7891. AP.keyPtr = keyBuffer;
  7892.  
  7893. rez = BULLET(&AP);
  7894. if (rez==0)
  7895.    printf("Matched search key in keyBuffer EXACTLY -- its record is in yourRecord\n");
  7896. else if (rez==EXB_KEY_NOT_FOUND) {
  7897.  
  7898.    // since not found, get the following in-order one (say, 'KINGSTON')
  7899.  
  7900.    AP.func = GET_NEXT_XB;
  7901.    rez = BULLET(&AP);
  7902.    if (rez) return(rez);
  7903.  
  7904.    printf("Not exact, but next greater key is in keyBuffer and its record is in yourRecord\n");
  7905. }
  7906. else
  7907.    return(rez);
  7908.  
  7909.  
  7910. ΓòÉΓòÉΓòÉ 10.26. Insert Data Record with Key Into Database ΓòÉΓòÉΓòÉ
  7911.  
  7912. #include "bullet_2.h"
  7913.  
  7914. ACCESSPACK AP;
  7915. LOCKPACK LP;                    // packs used here
  7916.  
  7917. LP.func = LOCK_XB;
  7918. LP.handle = indexID;            // also locks indexID's owner (its DBF)
  7919. LP.xlMode = LOCK_EXCLUSIVE;     // exclusive lock for index
  7920. LP.dlMode = LOCK_EXCLUSIVE;     // exclusive lock for data
  7921. LP.nextPtr = NULL;              // only one pack
  7922. rez = BULLET(&LP);
  7923. if (rez) return(LP.stat);       // rez for transaction-list is NOT the error
  7924.  
  7925. AP.func = INSERT_XB;
  7926. AP.handle = indexID;
  7927. AP.recNo = 0;                   // must be zero
  7928. AP.recPtr = &yourRecord;        // contains data record
  7929. AP.keyPtr = keyBuffer;          // empty, on return has key stored
  7930. AP.nextPtr = NULL;              // only the single pack
  7931. rez = BULLET(&AP);
  7932.  
  7933. // on return, as on all transaction-list routines, rez is not the return
  7934. // code but is the pack item that failed (neg if data, pos if index)
  7935.  
  7936. if (rez==0)
  7937.    printf("okay\n");
  7938. else if (rez < 0)
  7939.    printf("insert failed with data, err: %d\n",AP.stat);
  7940. else
  7941.    printf("insert failed with index, err: %d\n",AP.stat);
  7942.  
  7943.  
  7944. // if locked, MUST unlock!
  7945.  
  7946. LP.func = UNLOCK_XB;
  7947. LP.handle = indexID;
  7948. LP.nextPtr = NULL;
  7949. rez2 = BULLET(&LP);
  7950. if (rez2) rez2=LP.stat; // rez for transaction-list is NOT the error
  7951. if (rez==0) rez=rez2    // return the most interesting error, if any
  7952.  
  7953.  
  7954. ΓòÉΓòÉΓòÉ 10.27. Update Data Record with Key Update ΓòÉΓòÉΓòÉ
  7955.  
  7956. #include "bullet_2.h"
  7957.  
  7958. ACCESSPACK AP;
  7959. LOCKPACK LP;                    // packs used here
  7960.  
  7961. LP.func = LOCK_XB;
  7962. LP.handle = indexID;            // also locks indexID's owner (its DBF)
  7963. LP.xlMode = LOCK_SHARED;        // shared lock for index
  7964. LP.dlMode = LOCK_SHARED;        // shared lock for data
  7965. LP.nextPtr = NULL;              // only one pack
  7966. rez = BULLET(&LP);
  7967. if (rez) return(LP.stat);       // rez for transaction-list is NOT the error
  7968.  
  7969. AP.func = GET_FIRST_XB;         // get first key's data record (and its recNo)
  7970. AP.handle = indexID;
  7971. AP.recPtr = &yourRecord;
  7972. AP.keyPtr = keyBuffer;
  7973. rez = BULLET(&AP);
  7974. if (rez==0) {
  7975.  
  7976.    // assume that we want to change this entry now (as if we weren't sure
  7977.    // that we wanted to initially, hence the initial shared lock) --
  7978.    // this requires write access so relock to allow write access
  7979.  
  7980.    LP.func = RELOCK_XB;
  7981.    LP.handle = indexID;
  7982.    LP.xlMode = LOCK_EXCLUSIVE;  // exclusive lock for index
  7983.    LP.dlMode = LOCK_EXCLUSIVE;  // exclusive lock for data
  7984.    LP.recStart = 0;
  7985.    LP.nextPtr = NULL;
  7986.    rez = BULLET(&LP);
  7987.    if (rez) rez=LP.stat         // xaction-list routine so use LP.stat
  7988.    if (rez==0) {
  7989.  
  7990.       strcpy(yourRecord.someField,"new field data");
  7991.  
  7992.       // AP.recNo has been set by Bullet GET_XB call above
  7993.  
  7994.       AP.func = UPDATE_XB;
  7995.       AP.nextPtr = NULL;        // all other AP members set above
  7996.       rez = BULLET(&AP);
  7997.  
  7998.       // on return, as on all transaction-list routines, rez is not the return
  7999.       // code but is the pack item that failed (neg if data, pos if index)
  8000.  
  8001.       if (rez==0)
  8002.          printf("okay\n");
  8003.       else if (rez < 0)
  8004.          printf("update failed with data, err: %d\n",AP.stat);
  8005.       else
  8006.          printf("update failed with index, err: %d\n",AP.stat);
  8007.    }
  8008.    else
  8009.       printf("relock failed, rez: %d  err: %d\n",rez,LP.stat);
  8010. }
  8011.  
  8012. // if locked, MUST unlock!
  8013.  
  8014. LP.func = UNLOCK_XB;
  8015. LP.handle = indexID;
  8016. LP.nextPtr = NULL;
  8017. rez2 = BULLET(&LP);
  8018. if (rez2) rez2=LP.stat; // rez for transaction-list is NOT the error
  8019. if (rez==0) rez=rez2    // return the most interesting error, if any
  8020.  
  8021.  
  8022. ΓòÉΓòÉΓòÉ 10.28. Remote Drive, File/Device Check ΓòÉΓòÉΓòÉ
  8023.  
  8024. #include "bullet_2.h"
  8025.  
  8026. REMOTEPACK RP;                  // packs used here
  8027.  
  8028. // check if file in handle (or device handle) is on a 'network' drive
  8029.  
  8030. RP.func = CHECK_REMOTE_XB;
  8031. RP.handle = indexID;            // check if indexID handle is on a network
  8032. rez = BULLET(&RP);
  8033. if (rez) return(rez);
  8034. if (RP.isRemote)
  8035.    printf("handle is on a network drive\n");
  8036.  
  8037. // check if drive is a 'network' drive
  8038.  
  8039. RP.func = CHECK_REMOTE_XB;
  8040. RP.handle = 0;                  // set RP.handle to 0 to check drive
  8041. RP.drive = 0;                   // check if current drive is network drive
  8042. rez = BULLET(&RP);              // to check drive C:, set RP.drive=3
  8043. if (rez) return(rez);           // D: is RP.drive=4, and so on
  8044. if (RP.isRemote)
  8045.    printf("current drive is a network drive\n");
  8046.  
  8047.  
  8048. ΓòÉΓòÉΓòÉ 10.29. Relock Individual File ΓòÉΓòÉΓòÉ
  8049.  
  8050. #include "bullet_2.h"
  8051.  
  8052. LOCKPACK LP;
  8053. STATHANDLEPACK SHP;
  8054. STATDATAPACK SDP;
  8055. STATINDEXPACK SIP;              // packs used here
  8056.  
  8057. // given a handle, determine if it's DBF or index
  8058. // check if currently locked
  8059. // if locked, determine if shared or exclusive lock
  8060. // if exclusive lock, relock to shared
  8061. // if not locked, do nothing
  8062.  
  8063. SHP.func = STAT_HANDLE_XB;
  8064. SHP.handle = passedHandle;
  8065. rez = BULLET(&SHP);
  8066. if (SHP.ID==-1)
  8067.    puts("Handle is not a Bullet data or index file\n");
  8068. else {
  8069.    if (SHP.ID==0) {
  8070.  
  8071.       // normally, you lock before calling this routine but since
  8072.       // SIP.lockCount and SIP.flags are all that is being checked,
  8073.       // and since nothing is to be done if the handle is not locked,
  8074.       // it's okay in this instance to use this routine without
  8075.       // first explicitly locking the handle
  8076.  
  8077.       SIP.func = STAT_INDEX_XB;
  8078.       SIP.handle = passedHandle;
  8079.       rez = BULLET(&SIP);
  8080.       if (rez) goto ErrorHandler;
  8081.  
  8082.       // if locked, check if the lock is exclusive
  8083.  
  8084.       if (SIP.lockCount) {              // count of active full locks
  8085.  
  8086.          if ((SIP.flags & 4)==0) {      // bit2=0 means lock is not shared
  8087.  
  8088.             // currently exclusive, make it shared
  8089.  
  8090.             LP.func = RELOCK_INDEX_XB;
  8091.             LP.handle = passedHandle;
  8092.             LP.xlMode = LOCK_SHARED;
  8093.             rez = BULLET(&LP);
  8094.             if (rez) goto ErrorHandler;
  8095.          }
  8096.       }
  8097.    }
  8098.    else {
  8099.  
  8100.       SDP.func = STAT_DATA_XB;
  8101.       SDP.handle = passedHandle;
  8102.       rez = BULLET(&SDP);
  8103.       if (rez) goto ErrorHandler;
  8104.  
  8105.       if (SDP.lockCount) {              // count of active full locks
  8106.  
  8107.          if ((SDP.flags & 4)==0) {      // bit2=0 means lock is not shared
  8108.  
  8109.             // currently exclusive, make it shared
  8110.  
  8111.             LP.func = RELOCK_DATA_XB;
  8112.             LP.handle = passedHandle;
  8113.             LP.dlMode = LOCK_SHARED;
  8114.             LP.startRec = 0;            // entire file
  8115.             rez = BULLET(&LP);
  8116.             if (rez) goto ErrorHandler;
  8117.          }
  8118.       }
  8119.    }
  8120. }
  8121.  
  8122.  
  8123. ΓòÉΓòÉΓòÉ 10.30. DOS Disk Routines Through Bullet ΓòÉΓòÉΓòÉ
  8124.  
  8125. #include "bullet_2.h"
  8126.  
  8127. DOSFILEPACK DFP;                // packs used here
  8128.  
  8129. CHAR dataDirname[] = "under";
  8130. CHAR dataFilename[]= "under\\data.dbf";
  8131. CHAR newFilename[] = "under\\newdata.dbf";
  8132.  
  8133. // check if pathame can be access for read/write denynone (expected not here)
  8134.  
  8135. DFP.func = ACCESS_FILE_DOS;
  8136. DFP.filenamePtr = dataFilename;
  8137. DFP.asMode = 0x42;
  8138. rez = BULLET(&DFP);
  8139. if (rez==0) return(0);          // file already exists
  8140. if (rez==5) return(5);          // access denied (exists but in use)
  8141. // other errors possible, too, do the Make and Create and go by those results
  8142.  
  8143. // make directory for file
  8144.  
  8145. DFP.func = MAKE_DIR_DOS;
  8146. DFP.filenamePtr = dataDirname;
  8147. rez = BULLET(&DFP);
  8148. if (rez) rez=0;                 // can't create subdirectory (already exists?)
  8149.  
  8150. // create file
  8151.  
  8152. DFP.func = CREATE_FILE_DOS;
  8153. DFP.filenamePtr = dataFilename;
  8154. DFP.attr = 0;                   // 'normal' attributes
  8155. rez = BULLET(&DFP);
  8156. if (rez) return(rez);           // can't create file
  8157.  
  8158. // open file
  8159.  
  8160. DFP.func = OPEN_FILE_DOS;
  8161. DFP.filenamePtr = dataFilename;
  8162. DFP.asMode = 0x42;
  8163. rez = BULLET(&DFP);
  8164. if (rez) return(rez);           // can't open file
  8165.  
  8166. // DFP.handle is set by OPEN_FILE_DOS call above
  8167. // pre-allocate file space
  8168.  
  8169. DFP.func = EXPAND_FILE_DOS;
  8170. // DFP.handle already set
  8171. // DFP.asMode already set
  8172. DFP.bytes = 128*1024;           // set filesize to 128KB
  8173. rez = BULLET(&DFP);
  8174. if (rez) return(rez);           // can't do it (close file before return)
  8175.  
  8176. CHAR writeStuff[]="Write this string to offset 888";
  8177.  
  8178. DFP.func = SEEK_FILE_DOS;
  8179. // DFP.handle already set
  8180. DFP.seekTo = 888;
  8181. DFP.method = 0;                 // from start of file
  8182. rez = BULLET(&DFP);
  8183. if (rez) return(rez);           // can't do it (close...)
  8184.  
  8185. // write the string to disk
  8186.  
  8187. DFP.func = WRITE_FILE_DOS;
  8188. // DFP.handle already set
  8189. DFP.bytes = strlen(writeStuff);
  8190. DFP.bufferPtr = writeStuff;
  8191. rez = BULLET(&DFP);
  8192. if (rez) return(rez);
  8193.  
  8194. // commit to the deep
  8195.  
  8196. DFP.func = COMMIT_FILE_DOS;
  8197. // DFP.handle already set
  8198. rez = BULLET(&DFP);
  8199. if (rez) return(rez);
  8200.  
  8201. // reposition to where write started so can read what was written
  8202.  
  8203. DFP.func = SEEK_FILE_DOS;
  8204. // DFP.handle already set
  8205. DFP.seekTo = 888;
  8206. DFP.method = 0;
  8207. rez = BULLET(&DFP);
  8208. if (rez) return(rez);
  8209.  
  8210. CHAR readBuffer[128];
  8211.  
  8212. DFP.func = READ_FILE_DOS;
  8213. // DFP.handle already set
  8214. DFP.bytes = strlen(writeStuff); // read it back
  8215. DFP.bufferPtr = readBuffer;
  8216. rez = BULLET(&DFP);
  8217. if (rez) return(rez);
  8218. if (DFP.bytes != strlen(writeStuff))
  8219.    printf("read came up short!\n");
  8220.  
  8221. DFP.func = CLOSE_FILE_DOS;
  8222. // DFP.handle already set
  8223. rez = BULLET(&DFP);
  8224. if (rez) return(rez);
  8225. DFP.handle = 0;                 // it's gone (closed, anyway)
  8226.  
  8227. // rename the file
  8228.  
  8229. DFP.func = RENAME_FILE_DOS;
  8230. DFP.filenamePtr = dataFilename;
  8231. DFP.newFilenamePtr = newFilename;
  8232. rez = BULLET(&DFP);
  8233. if (rez) return(rez);
  8234.  
  8235. // and get rid of it (known now as newFilename)
  8236.  
  8237. DFP.func = DELETE_FILE_DOS;
  8238. DFP.filenamePtr = newFilename;
  8239. rez = BULLET(&DFP);
  8240. return(rez);
  8241.  
  8242. // Why the DosXXX routines when they're standard API?  Not all
  8243. // language tools are able to directly call the API, but can
  8244. // call them indirectly through the Bullet DLL.
  8245.  
  8246.  
  8247. ΓòÉΓòÉΓòÉ 11. Bullet Errors ΓòÉΓòÉΓòÉ
  8248.  
  8249. Bullet error codes are numbered so that they do not overlap OS error codes. 
  8250. The first general Bullet error number is 8193, but Bullet also returns select 
  8251. system error code numbers instead of duplicating system codes (those listed 
  8252. below less than 8192).  In addition, if the error is reported by the OS (for 
  8253. example, attempting to access a locked file), then the OS error in returned by 
  8254. Bullet.  For a list of OS errors, see OS/2 Dos API Errors. 
  8255.  
  8256. System Error Codes
  8257.  
  8258.    8    EXB_NOT_ENOUGH_MEMORY
  8259.         cannot get memory requested
  8260.  
  8261.   15    EXB_INVALID_DRIVE
  8262.         not a valid drive letter
  8263.  
  8264.   38    EXB_UNEXPECTED_EOF
  8265.         unexpected end-of-file where bytes requested for read exceeded EOF
  8266.  
  8267.   39    EXB_DISK_FULL
  8268.         disk full on WriteFile
  8269.  
  8270.   80    EXB_FILE_EXISTS
  8271.         cannot create file since it already exists
  8272.  
  8273.  105    EXB_SEM_OWNER_DIED
  8274.         owner of mutex semaphore died  (used in place of Win32 80h)
  8275.  
  8276.  640    EXB_TIMEOUT
  8277.         mutex semaphore timed out (used in place of Win32 102h)
  8278.  
  8279.  
  8280. 8192+   EXB_OR_WITH_FAULTS
  8281.         1=flush failed on handle close
  8282.         2=free memory failed on handle close
  8283.         4=failed memo handle close (data handle only)
  8284.  
  8285.         During a CLOSE_XB routine, the close process continues
  8286.         regardless of errors, and so the errors are accumulated.
  8287.         For example, 8193 means the flush failed, and 8195 means
  8288.         both the flush and the free failed (8192+1+2=8195).
  8289.         If the error occurred in the actual DosClose() API call,
  8290.         only that error is returned (it will be an OS error code).
  8291.  
  8292. 8251    EXB_216501
  8293.         INT21/6501h not supported by DOS extender (see ccdosfn.c)
  8294.  
  8295. 8256    EXB_216506
  8296.         INT21/6506h not supported by DOS extender (see ccdosfn.c)
  8297.  
  8298.  
  8299. 8300    EXB_ILLEGAL_CMD
  8300.         function not allowed
  8301.  
  8302. 8301    EXB_OLD_DOS
  8303.         OS version < MIN_DOS_NEEDED
  8304.  
  8305. 8302    EXB_NOT_INITIALIZED
  8306.         init not active, must do INIT_XB before using Bullet
  8307.  
  8308. 8303    EXB_ALREADY_INITIALIZED
  8309.         init already active, must do EXIT_XB first
  8310.  
  8311. 8304    EXB_TOO_MANY_HANDLES
  8312.         more than 1024 opens requested,
  8313.         or more than license permits (100, 250, 1024)
  8314.  
  8315. 8305    EXB_SYSTEM_HANDLE
  8316.         Bullet won't use or close handles 0-2
  8317.  
  8318. 8306    EXB_FILE_NOT_OPEN
  8319.         the handle is not a Bullet handle, including the
  8320.         handle supplied in OP.xbLink
  8321.  
  8322. 8307    EXB_FILE_IS_DIRTY
  8323.         tried to reload header but current still dirty;
  8324.         flush the file before reloading the header
  8325.  
  8326. 8308    EXB_BAD_FILETYPE
  8327.         attempted to do a key file operation on non-key file,
  8328.         or a data operation on a non-data file
  8329.  
  8330. 8309    EXB_TOO_MANY_PACKS
  8331.         too many INSERT, UPDATE, REINDEX, LOCK_XB packs (more than 256)
  8332.  
  8333. 8310    EXB_NULL_RECPTR
  8334.         null record pointer passed to Bullet (.recPtr==NULL)
  8335.  
  8336. 8311    EXB_NULL_KEYPTR
  8337.         null key pointer passed to Bullet (.keyPtr==NULL)
  8338.  
  8339. 8312    EXB_NULL_MEMOPTR
  8340.         null memo pointer passed to Bullet (.memoPtr==NULL)
  8341.  
  8342. 8313    EXB_EVALUATION_LIMIT
  8343.         evaluation limit of 300 records exceeded (remedy: buy a license)
  8344.  
  8345. 8314    EXB_BAD_INDEX
  8346.         Query/SetSysVars index selection is beyond the last one
  8347.  
  8348. 8315    EXB_RO_INDEX
  8349.         SetSysVars index item is read-only
  8350.  
  8351. 8316    EXB_FILE_BOUNDS
  8352.         file size > 4GB, or greater than the SetSysVars value
  8353.  
  8354.  
  8355. 8397    EXB_FORCE_ROLLBACK
  8356.         rollback test completed (last AP[].nextPtr=-1 for Insert/Update) (test-use only)
  8357.  
  8358. 8398    EXB_INVALID_DLL
  8359.         DLL seems to be invalid (8399 similar)
  8360.  
  8361.  
  8362. Multi-access Error Codes
  8363.  
  8364. 8401    EXB_BAD_LOCK_MODE
  8365.         lock mode (LP) not valid, must be 0 or 1
  8366.  
  8367. 8402    EXB_NOTHING_TO_RELOCK
  8368.         cannot relock without existing full-lock
  8369.  
  8370. 8403    EXB_SHARED_LOCK_ON
  8371.         unlikely error, write access needed for flush, but lock is shared
  8372.  
  8373.  
  8374. Index Error Codes
  8375.  
  8376. 8501    EXB_KEY_NOT_FOUND
  8377.         exact match of key not found
  8378.  
  8379. 8502    EXB_KEY_EXISTS
  8380.         key exists already and dups not allowed
  8381.  
  8382. 8503    EXB_END_OF_FILE
  8383.         already at last index order
  8384.  
  8385. 8504    EXB_TOP_OF_FILE
  8386.         already at first index order
  8387.  
  8388. 8505    EXB_EMPTY_FILE
  8389.         nothing to do since no keys
  8390.  
  8391. 8506    EXB_CANNOT_GET_LAST
  8392.         cannot locate last key
  8393.  
  8394. 8507    EXB_BAD_INDEX_STACK
  8395.         index file is corrupt
  8396.  
  8397. 8508    EXB_BAD_INDEX_READ0
  8398.         index file is corrupt
  8399.  
  8400. 8509    EXB_BAD_INDEX_WRITE0
  8401.         index file is corrupt
  8402.  
  8403.  
  8404. 8521    EXB_OLD_INDEX
  8405.         incompatible Bullet index, use ReindexOld subroutine, if available
  8406.  
  8407. 8522    EXB_UNKNOWN_INDEX
  8408.         not a Bullet index file
  8409.  
  8410. 8523    EXB_KEY_TOO_LONG
  8411.         keylength > 62 (or 64 if unique), or is 0
  8412.  
  8413.  
  8414. 8531    EXB_PARSER_NULL
  8415.         parser function pointer is NULL
  8416.  
  8417. 8532    EXB_BUILDER_NULL
  8418.         build key function pointer is NULL
  8419.  
  8420. 8533    EXB_BAD_SORT_FUNC
  8421.         CIP.sortFunction not valid (not 1-6, or a custom sort-compare)
  8422.  
  8423. 8534    EXB_BAD_NODE_SIZE
  8424.         CIP.nodeSize is not 512, 1024, or 2048
  8425.  
  8426. 8535    EXB_FILENAME_TOO_LONG
  8427.         CIP.filenamePtr->pathname greater than file system allows
  8428.  
  8429.         This error is detected only for the file system installed,
  8430.         and does not detect using pathnames greater than 80 on a FAT
  8431.         system if HPFS is installed.  The OS returns its own error
  8432.         in this case, after the fact.
  8433.  
  8434.  
  8435. 8541    EXB_KEYX_NULL
  8436.         key expression is effectively NULL
  8437.  
  8438. 8542    EXB_KEYX_TOO_LONG
  8439.         CIP.keyExpPtr->expression is greater than 159 bytes
  8440.  
  8441. 8543    EXB_KEYX_SYM_TOO_LONG
  8442.         fieldname/funcname in expression is longer than 10 chars
  8443.  
  8444. 8544    EXB_KEYX_SYM_UNKNOWN
  8445.         fieldname/funcname in expression is unknown or misspelled
  8446.  
  8447. 8545    EXB_KEYX_TOO_MANY_SYMS
  8448.         too many symbols/fields used in expression (16 max)
  8449.  
  8450. 8546    EXB_KEYX_BAD_SUBSTR
  8451.         invalid SUBSTR() operand in expression
  8452.  
  8453. 8547    EXB_KEYX_BAD_SUBSTR_SZ
  8454.         SUBSTR() exceeds field's size
  8455.  
  8456. 8548    EXB_KEYX_BAD_FORM
  8457.         didn't match expected symbol in expression (missing paren, etc.)
  8458.  
  8459.  
  8460. 8551    EXB_NO_READS_FOR_RUN
  8461.         unlikely error, use different reindex buffer size to fix
  8462.  
  8463. 8552    EXB_TOO_MANY_RUNS
  8464.         unlikely error, too many runs (64K or more runs)
  8465.  
  8466. 8553    EXB_TOO_MANY_RUNS_FOR_BUFFER
  8467.         unlikely error, too many runs for run buffer
  8468.  
  8469. 8554    EXB_TOO_MANY_DUPLICATES
  8470.         more than 64K "identical" keys since the last enumerator used
  8471.         was 0xFFFF -- if ever you have this error, REINDEX_XB should
  8472.         be used to resequence the enumerators
  8473.  
  8474.  
  8475. 8561    EXB_INSERT_RECNO_BAD
  8476.         AP.recNo cannot be > 0 if inserting with INSERT_XB
  8477.  
  8478. 8562    EXB_PREV_APPEND_EMPTY
  8479.         no previous append for INSERT_XB yet AP.recNo==0x80000000
  8480.  
  8481. 8563    EXB_PREV_APPEND_MISMATCH
  8482.         previous append's xbLink does not match this
  8483.         -- if this pack's AP.recNo=0x80000000 then this pack's AP.handle
  8484.         must be the same handle as that of the last pack that added a record
  8485.  
  8486. 8564    EXB_INSERT_KBO_FAILED
  8487.         could not back out key at INSERT_XB
  8488.  
  8489. 8565    EXB_INSERT_DBO_FAILED
  8490.         could not back out data records at INSERT_XB
  8491.  
  8492.  
  8493. 8571    WRN_NOTHING_TO_UPDATE
  8494.         all AP.recNo=0 at UPDATE_XB so nothing to do
  8495.  
  8496. 8572    EXB_INTERNAL_UPDATE
  8497.         internal error UPDATE_XB, not in handle/record# list
  8498.  
  8499. 8573    EXB_FAILED_DATA_RESTORE
  8500.         could not restore original data record (*)
  8501.  
  8502. 8574    EXB_FAILED_KEY_DELETE
  8503.         could not remove new key (*)
  8504.  
  8505. 8575    EXB_FAILED_KEY_RESTORE
  8506.         could not restore original key(*)
  8507.  
  8508.         (*) original error, which forced a back-out, has been
  8509.         replaced by this error -- this error is always returned
  8510.         in the first AP.stat (-1 on data, 1 on index)
  8511.  
  8512.  
  8513. Data Error Codes
  8514.  
  8515. 8601    EXB_EXT_XBLINK
  8516.         xbLink handle is not an internal DBF, as was specified during the
  8517.         index file's creation -- the Bullet routine called requires a Bullet
  8518.         DBF data file (instead use index-only access methods like NEXT_KEY_XB).
  8519.  
  8520. 8602    EXB_FIELDNAME_TOO_LONG
  8521.         fieldname is > 10 characters
  8522.  
  8523. 8603    EXB_RECORD_TOO_LONG
  8524.         record length is > 64K
  8525.  
  8526. 8604    EXB_FIELD_NOT_FOUND
  8527.         fieldname not found in descriptor info
  8528.  
  8529. 8605    EXB_BAD_FIELD_COUNT
  8530.         fields <= 0 or >= MAX_FIELDS; also use of a field number which
  8531.         is beyond the last field
  8532.  
  8533. 8606    EXB_BAD_HEADER
  8534.         bad header (reclen=0, etc.)
  8535.  
  8536. 8607    EXB_BUFFER_TOO_SMALL
  8537.         buffer too small (pack buffer < record length)
  8538.  
  8539. 8608    EXB_INTERNAL_PACK
  8540.         internal error in PackRecords
  8541.  
  8542. 8609    EXB_BAD_RECNO
  8543.         record number=0 or > records in data file header, or
  8544.         pack attempt on empty data file
  8545.  
  8546. 8610    WRN_RECORD_TAGGED
  8547.         record's tag field matches skip tag
  8548.  
  8549.  
  8550. Memo Error Codes
  8551.  
  8552. 8701    WRN_CANNOT_OPEN_MEMO
  8553.         the DBF header has bits 3 & 7 set, which indicates that a memo
  8554.         file is attached to this DBF, but the DBT memo file failed to open
  8555.         -- the DBF open continues, with this warning code returned
  8556.  
  8557. 8702    EXB_MEMO_NOT_OPEN
  8558.         no open memo file for operation
  8559.  
  8560. 8703    EXB_BAD_BLOCKSIZE
  8561.         memo blocksize must be at least 24 bytes
  8562.  
  8563. 8704    EXB_MEMO_DELETED
  8564.         memo is deleted
  8565.  
  8566. 8705    EXB_MEMO_PAST_END
  8567.         memo data requested is past end of record
  8568.  
  8569. 8706    EXB_BAD_MEMONO
  8570.         memo number is not valid
  8571.  
  8572. 8707    EXB_MEMO_IN_USE
  8573.         memo add encountered likely corrupt memo file
  8574.         -- avail list indicates this memo record is deleted, but the memoAvail
  8575.         link for the memo indicates it is use (memoAvail link==0x8FFFF)
  8576.  
  8577. 8708    EXB_BAD_AVAIL_LINK
  8578.         memo avail link cannot be valid (e.g., memoAvail==0)
  8579.  
  8580. 8709    EXB_MEMO_ZERO_SIZE
  8581.         memo data has no size (size is 0)
  8582.  
  8583. 8710    EXB_MEMO_IS_SMALLER
  8584.         memo attempt to shrink but memo size is already <= size requested
  8585.  
  8586.  
  8587. ΓòÉΓòÉΓòÉ 12. OS/2 Dos API Errors ΓòÉΓòÉΓòÉ
  8588.  
  8589.  
  8590.   0   NO_ERROR
  8591.           No error occurred.
  8592.  
  8593.   1   ERROR_INVALID_FUNCTION
  8594.           Invalid function number.
  8595.  
  8596.   2   ERROR_FILE_NOT_FOUND
  8597.           File not found.
  8598.  
  8599.   3   ERROR_PATH_NOT_FOUND
  8600.           Path not found.
  8601.  
  8602.   4   ERROR_TOO_MANY_OPEN_FILES
  8603.           Too many open files (no handles left).
  8604.  
  8605.   5   ERROR_ACCESS_DENIED
  8606.           Access denied.
  8607.  
  8608.   6   ERROR_INVALID_HANDLE
  8609.           Invalid handle.
  8610.  
  8611.   7   ERROR_ARENA_TRASHED
  8612.           Memory control blocks destroyed.
  8613.  
  8614.   8   ERROR_NOT_ENOUGH_MEMORY
  8615.           Insufficient memory.
  8616.  
  8617.   9   ERROR_INVALID_BLOCK
  8618.           Invalid memory-block address.
  8619.  
  8620.   10   ERROR_BAD_ENVIRONMENT
  8621.           Invalid environment.
  8622.  
  8623.   11   ERROR_BAD_FORMAT
  8624.           Invalid format.
  8625.  
  8626.   12   ERROR_INVALID_ACCESS
  8627.           Invalid access code.
  8628.  
  8629.   13   ERROR_INVALID_DATA
  8630.           Invalid data.
  8631.  
  8632.   14   Reserved.
  8633.  
  8634.  
  8635.   15   ERROR_INVALID_DRIVE
  8636.           Invalid drive specified.
  8637.  
  8638.   16   ERROR_CURRENT_DIRECTORY
  8639.           Attempting to remove current directory.
  8640.  
  8641.   17   ERROR_NOT_SAME_DEVICE
  8642.           Not same device.
  8643.  
  8644.   18   ERROR_NO_MORE_FILES
  8645.           No more files.
  8646.  
  8647.   19   ERROR_WRITE_PROTECT
  8648.           Attempt to write on write-protected diskette.
  8649.  
  8650.   20   ERROR_BAD_UNIT
  8651.           Unknown unit.
  8652.  
  8653.   21   ERROR_NOT_READY
  8654.           Drive not ready.
  8655.  
  8656.   22   ERROR_BAD_COMMAND
  8657.           Unknown command.
  8658.  
  8659.   23   ERROR_CRC
  8660.           Data error - cyclic redundancy check.
  8661.  
  8662.   24   ERROR_BAD_LENGTH
  8663.           Invalid request structure length.
  8664.  
  8665.   25   ERROR_SEEK
  8666.           Seek error.
  8667.  
  8668.   26   ERROR_NOT_DOS_DISK
  8669.           Unknown media type.
  8670.  
  8671.   27   ERROR_SECTOR_NOT_FOUND
  8672.           Sector not found.
  8673.  
  8674.   28   ERROR_OUT_OF_PAPER
  8675.           Printer is out of paper.
  8676.  
  8677.   29   ERROR_WRITE FAULT
  8678.           Write fault.
  8679.  
  8680.   30   ERROR_READ_FAULT
  8681.           Read fault.
  8682.  
  8683.   31   ERROR_GEN_FAILURE
  8684.           General failure.
  8685.  
  8686.   32   ERROR_SHARING_VIOLATION
  8687.           Sharing violation.
  8688.  
  8689.   33   ERROR_LOCK_VIOLATION
  8690.           Lock violation.
  8691.  
  8692.   34   ERROR_WRONG_DISK
  8693.           Invalid disk change.
  8694.  
  8695.   35   ERROR_FCB_UNAVAILABLE
  8696.           FCB unavailable.
  8697.  
  8698.   36   ERROR_SHARING_BUFFER_EXCEEDED
  8699.           Sharing buffer overflow.
  8700.  
  8701.   37   ERROR_CODE_PAGE_MISMATCHED
  8702.           Code page does not match.
  8703.  
  8704.   38   ERROR_HANDLE_EOF
  8705.           End of file reached.
  8706.  
  8707.   39   ERROR_HANDLE_DISK_FULL
  8708.           Disk is full.
  8709.  
  8710.   40-49   Reserved.
  8711.  
  8712.  
  8713.   50   ERROR_NOT_SUPPORTED
  8714.           Network request not supported.
  8715.  
  8716.   51   ERROR_REM_NOT_LIST
  8717.           Remote network node is not online.
  8718.  
  8719.   52   ERROR_DUP_NAME
  8720.           Duplicate file name in network.
  8721.  
  8722.   53   ERROR_BAD_NETPATH
  8723.           Network path not found.
  8724.  
  8725.   54   ERROR_NETWORK_BUSY
  8726.           Network is busy.
  8727.  
  8728.   55   ERROR_DEV_NOT_EXIST
  8729.           Device is not installed in network.
  8730.  
  8731.   56   ERROR_TOO_MANY_CMDS
  8732.           Network command limit reached.
  8733.  
  8734.   57   ERROR_ADAP_HDW_ERR
  8735.           Network adapter hardware error.
  8736.  
  8737.   58   ERROR_BAD_NET_RESP
  8738.           Incorrect response in network.
  8739.  
  8740.   59   ERROR_UNEXP_NET_ERR
  8741.           Unexpected error in network.
  8742.  
  8743.   60   ERROR_BAD_REM_ADAP
  8744.           Remote network adapter error.
  8745.  
  8746.   61   ERROR_PRINTQ_FULL
  8747.           Network printer queue is full.
  8748.  
  8749.   62   ERROR_NO_SPOOL_SPACE
  8750.           No space in print spool file.
  8751.  
  8752.   63   ERROR_PRINT_CANCELLED
  8753.           Print spool file deleted.
  8754.  
  8755.   64   ERROR_NETNAME_DELETED
  8756.           Network name deleted.
  8757.  
  8758.   65   ERROR_NETWORK_ACCESS_DENIED
  8759.           Access to network denied.
  8760.  
  8761.   66   ERROR_BAD_DEV_TYPE
  8762.           Device type invalid for network.
  8763.  
  8764.   67   ERROR_BAD_NET_NAME
  8765.           Network name not found.
  8766.  
  8767.   68   ERROR_TOO_MANY_NAMES
  8768.           Network name limit exceeded.
  8769.  
  8770.   69   ERROR_TOO_MANY_SESS
  8771.           Network session limit exceeded.
  8772.  
  8773.   70   ERROR_SHARING_PAUSED
  8774.           Temporary pause in network.
  8775.  
  8776.   71   ERROR_REQ_NOT_ACCEP
  8777.           Network request denied.
  8778.  
  8779.   72   ERROR_REDIR_PAUSED
  8780.           Pause in network print disk redirection.
  8781.  
  8782.   73   ERROR_SBCS_ATT_WRITE_PROT
  8783.           Attempted write on protected disk.
  8784.  
  8785.   74   ERROR_SBCS_GENERAL_FAILURE
  8786.           General failure, single-byte character set.
  8787.  
  8788.   75-79   Reserved.
  8789.  
  8790.  
  8791.   80   ERROR_FILE_EXISTS
  8792.           File exists.
  8793.  
  8794.   81   ERROR_DUP_FCB
  8795.           Reserved.
  8796.  
  8797.   82   ERROR_CANNOT_MAKE
  8798.           Cannot make directory entry.
  8799.  
  8800.   83   ERROR_FAIL_I24
  8801.           Failure on INT 24.
  8802.  
  8803.   84   ERROR_OUT_OF_STRUCTURES
  8804.           Too many redirections.
  8805.  
  8806.   85   ERROR_ALREADY_ASSIGNED
  8807.           Duplicate redirection.
  8808.  
  8809.   86   ERROR_INVALID_PASSWORD
  8810.           Invalid password.
  8811.  
  8812.   87   ERROR_INVALID_PARAMETER
  8813.           Invalid parameter.
  8814.  
  8815.   88   ERROR_NET_WRITE_FAULT
  8816.           Network device fault.
  8817.  
  8818.   89   ERROR_NO_PROC_SLOTS
  8819.           No process slots available.
  8820.  
  8821.   90   ERROR_NOT_FROZEN
  8822.           System error.
  8823.  
  8824.   91   ERR_TSTOVFL
  8825.           Timer service table overflow.
  8826.  
  8827.   92   ERR_TSTDUP
  8828.           Timer service table duplicate.
  8829.  
  8830.   93   ERROR_NO_ITEMS
  8831.           No items to work on.
  8832.  
  8833.   95   ERROR_INTERRUPT
  8834.           Interrupted system call.
  8835.  
  8836.   99   ERROR_DEVICE_IN_USE
  8837.           Device in use.
  8838.  
  8839.   100   ERROR_TOO_MANY_SEMAPHORES
  8840.           User/system open semaphore limit reached.
  8841.  
  8842.   101   ERROR_EXCL_SEM_ALREADY_OWNED
  8843.           Exclusive semaphore already owned.
  8844.  
  8845.   102   ERROR_SEM_IS_SET
  8846.           DosCloseSem found semaphore set.
  8847.  
  8848.   103   ERROR_TOO_MANY_SEM_REQUESTS
  8849.           Too many exclusive semaphore requests.
  8850.  
  8851.   104   ERROR_INVALID_AT_INTERRUPT_TIME
  8852.           Operation invalid at interrupt time.
  8853.  
  8854.   105   ERROR_SEM_OWNER_DIED
  8855.           Previous semaphore owner terminated without freeing semaphore.
  8856.  
  8857.   106   ERROR_SEM_USER_LIMIT
  8858.           Semaphore limit exceeded.
  8859.  
  8860.   107   ERROR_DISK_CHANGE
  8861.           Insert drive B disk into drive A.
  8862.  
  8863.   108   ERROR_DRIVE_LOCKED
  8864.           Drive locked by another process.
  8865.  
  8866.   109   ERROR_BROKEN_PIPE
  8867.           Write on pipe with no reader.
  8868.  
  8869.   110   ERROR_OPEN_FAILED
  8870.           Open/create failed due to explicit fail command.
  8871.  
  8872.   111   ERROR_BUFFER_OVERFLOW
  8873.           Buffer passed to system call too small to hold return data.
  8874.  
  8875.   112   ERROR_DISK_FULL
  8876.           Not enough space on the disk.
  8877.  
  8878.   113   ERROR_NO_MORE_SEARCH_HANDLES
  8879.           Cannot allocate another search structure and handle.
  8880.  
  8881.   114   ERROR_INVALID_TARGET_HANDLE
  8882.           Target handle in DosDupHandle invalid.
  8883.  
  8884.   115   ERROR_PROTECTION_VIOLATION
  8885.           Invalid user virtual address.
  8886.  
  8887.   116   ERROR_VIOKBD_REQUEST
  8888.           Error on display write or keyboard read.
  8889.  
  8890.   117   ERROR_INVALID_CATEGORY
  8891.           Category for DevIOCtl not defined.
  8892.  
  8893.   118   ERROR_INVALID_VERIFY_SWITCH
  8894.           Invalid value passed for verify flag.
  8895.  
  8896.   119   ERROR_BAD_DRIVER_LEVEL
  8897.           Level four driver not found.
  8898.  
  8899.   120   ERROR_CALL_NOT_IMPLEMENTED
  8900.           Invalid function called.
  8901.  
  8902.   121   ERROR_SEM_TIMEOUT
  8903.           Time-out occurred from semaphore API function.
  8904.  
  8905.   122   ERROR_INSUFFICIENT_BUFFER
  8906.           Data buffer too small.
  8907.  
  8908.   123   ERROR_INVALID_NAME
  8909.           Illegal character or invalid file-system name.
  8910.  
  8911.   124   ERROR_INVALID_LEVEL
  8912.           Non-implemented level for information retrieval or setting.
  8913.  
  8914.   125   ERROR_NO_VOLUME_LABEL
  8915.           No volume label found with DosQueryFSInfo function.
  8916.  
  8917.   126   ERROR_MOD_NOT_FOUND
  8918.           Module handle not found with DosQueryProcAddr(),
  8919.           DosQueryModAddr().
  8920.  
  8921.   127   ERROR_PROC_NOT_FOUND
  8922.           Procedure address not found with DosQueryProcAddr().
  8923.  
  8924.   128   ERROR_WAIT_NO_CHILDREN
  8925.           DosWaitChild finds no children.
  8926.  
  8927.   129   ERROR_CHILD_NOT_COMPLETE
  8928.           DosWaitChild children not terminated.
  8929.  
  8930.   130   ERROR_DIRECT_ACCESS_HANDLE
  8931.           Handle operation invalid for direct disk-access handles.
  8932.  
  8933.   131   ERROR_NEGATIVE_SEEK
  8934.           Attempting seek to negative offset.
  8935.  
  8936.   132   ERROR_SEEK_ON_DEVICE
  8937.           Application trying to seek on device or pipe.
  8938.  
  8939.   133   ERROR_IS_JOIN_TARGET
  8940.           Drive has previously joined drives.
  8941.  
  8942.   134   ERROR_IS_JOINED
  8943.           Drive is already joined.
  8944.  
  8945.   135   ERROR_IS_SUBSTED
  8946.           Drive is already substituted.
  8947.  
  8948.   136   ERROR_NOT_JOINED
  8949.           Cannot delete drive that is not joined.
  8950.  
  8951.   137   ERROR_NOT_SUBSTED
  8952.           Cannot delete drive that is not substituted.
  8953.  
  8954.   138   ERROR_JOIN_TO_JOIN
  8955.           Cannot join to a joined drive.
  8956.  
  8957.   139   ERROR_SUBST_TO_SUBST
  8958.           Cannot substitute to a substituted drive.
  8959.  
  8960.   140   ERROR_JOIN_TO_SUBST
  8961.           Cannot join to a substituted drive.
  8962.  
  8963.   141   ERROR_SUBST_TO_JOIN
  8964.           Cannot substitute to a joined drive.
  8965.  
  8966.   142   ERROR_BUSY_DRIVE
  8967.           Specified drive is busy.
  8968.  
  8969.   143   ERROR_SAME_DRIVE
  8970.           Cannot join or substitute a drive to a directory on the same drive.
  8971.  
  8972.   144   ERROR_DIR_NOT_ROOT
  8973.           Directory must be a subdirectory of the root.
  8974.  
  8975.   145   ERROR_DIR_NOT_EMPTY
  8976.           Directory must be empty to use join command.
  8977.  
  8978.   146   ERROR_IS_SUBST_PATH
  8979.           Path specified is being used in a substitute.
  8980.  
  8981.   147   ERROR_IS_JOIN_PATH
  8982.           Path specified is being used in a join.
  8983.  
  8984.   148   ERROR_PATH_BUSY
  8985.           Path specified is being used by another process.
  8986.  
  8987.   149   ERROR_IS_SUBST_TARGET
  8988.           Cannot join or substitute a drive that has a directory that is the
  8989.           target of a previous substitute.
  8990.  
  8991.   150   ERROR_SYSTEM_TRACE
  8992.           System trace error.
  8993.  
  8994.   151   ERROR_INVALID_EVENT_COUNT
  8995.           DosWaitMuxWaitSem errors.
  8996.  
  8997.   152   ERROR_TOO_MANY_MUXWAITERS
  8998.           System limit of 100 entries reached.
  8999.  
  9000.   153   ERROR_INVALID_LIST_FORMAT
  9001.           Invalid list format.
  9002.  
  9003.   154   ERROR_LABEL_TOO_LONG
  9004.           Volume label too big.
  9005.  
  9006.   155   ERROR_TOO_MANY_TCBS
  9007.           Cannot create another TCB.
  9008.  
  9009.   156   ERROR_SIGNAL_REFUSED
  9010.           Signal refused.
  9011.  
  9012.   157   ERROR_DISCARDED
  9013.           Segment is discarded.
  9014.  
  9015.   158   ERROR_NOT_LOCKED
  9016.           Segment is not locked.
  9017.  
  9018.   159   ERROR_BAD_THREADID_ADDR
  9019.           Invalid thread-identity address.
  9020.  
  9021.   160   ERROR_BAD_ARGUMENTS
  9022.           Invalid environment pointer.
  9023.  
  9024.   161   ERROR_BAD_PATHNAME
  9025.           Invalid path name passed to exec.
  9026.  
  9027.   162   ERROR_SIGNAL_PENDING
  9028.           Signal already pending.
  9029.  
  9030.   163   ERROR_UNCERTAIN_MEDIA
  9031.           Error with INT 24 mapping.
  9032.  
  9033.   164   ERROR_MAX_THRDS_REACHED
  9034.           No more process slots.
  9035.  
  9036.   165   ERROR_MONITORS_NOT_SUPPORTED
  9037.           Error with INT 24 mapping.
  9038.  
  9039.   166   ERROR_UNC_DRIVER_NOT_INSTALLED
  9040.           Default redirection return code.
  9041.  
  9042.   167   ERROR_LOCK_FAILED
  9043.           Locking failed.
  9044.  
  9045.   168   ERROR_SWAPIO_FAILED
  9046.           Swap I/O failed.
  9047.  
  9048.   169   ERROR_SWAPIN_FAILED
  9049.           Swap in failed.
  9050.  
  9051.   170   ERROR_BUSY
  9052.           Segment is busy.
  9053.  
  9054.   171-172   Reserved.
  9055.  
  9056.  
  9057.   173   ERROR_CANCEL_VIOLATION
  9058.           A lock request is not outstanding for the specified file range, or the
  9059.           range length is zero.
  9060.  
  9061.   174   ERROR_ATOMIC_LOCK_NOT_SUPPORTED
  9062.           The file-system driver (FSD) does not support atomic lock operations.
  9063.           Versions of OS/2 prior to version 2.00 do not support atomic lock
  9064.           operations.
  9065.  
  9066.   175   ERROR_READ_LOCKS_NOT_SUPPORTED
  9067.           The file system driver (FSD) does not support shared read locks.
  9068.  
  9069.   176-179   Reserved.
  9070.  
  9071.  
  9072.   180   ERROR_INVALID_SEGMENT_NUMBER
  9073.           Invalid segment number.
  9074.  
  9075.   181   ERROR_INVALID_CALLGATE
  9076.           Invalid call gate.
  9077.  
  9078.   182   ERROR_INVALID_ORDINAL
  9079.           Invalid ordinal.
  9080.  
  9081.   183   ERROR_ALREADY_EXISTS
  9082.           Shared segment already exists.
  9083.  
  9084.   184   ERROR_NO_CHILD_PROCESS
  9085.           No child process to wait for.
  9086.  
  9087.   185   ERROR_CHILD_ALIVE_NOWAIT
  9088.           NoWait specified and child alive.
  9089.  
  9090.   186   ERROR_INVALID_FLAG_NUMBER
  9091.           Invalid flag number.
  9092.  
  9093.   187   ERROR_SEM_NOT_FOUND
  9094.           Semaphore does not exist.
  9095.  
  9096.   188   ERROR_INVALID_STARTING_CODESEG
  9097.           Invalid starting code segment, incorrect END (label) directive.
  9098.  
  9099.   189   ERROR_INVALID_STACKSEG
  9100.           Invalid stack segment.
  9101.  
  9102.   190   ERROR_INVALID_MODULETYPE
  9103.           Invalid module type - dynamic-link library file cannot be used as an
  9104.           application. Application cannot be used as a dynamic-link library.
  9105.  
  9106.   191   ERROR_INVALID_EXE_SIGNATURE
  9107.           Invalid EXE signature - file is a DOS mode program or an improper
  9108.           program.
  9109.  
  9110.   192   ERROR_EXE_MARKED_INVALID
  9111.           EXE marked invalid - link detected errors when the application was
  9112.           created.
  9113.  
  9114.   193   ERROR_BAD_EXE_FORMAT
  9115.           Invalid EXE format - file is a DOS mode program or an improper
  9116.           program.
  9117.  
  9118.   194   ERROR_ITERATED_DATA_EXCEEDS_64k
  9119.           Iterated data exceeds 64KB - there is more than 64KB of data in one
  9120.           of the segments of the file.
  9121.  
  9122.   195   ERROR_INVALID_MINALLOCSIZE
  9123.           Invalid minimum allocation size - the size is specified to be less than
  9124.           the size of the segment data in the file.
  9125.  
  9126.   196   ERROR_DYNLINK_FROM_INVALID_RING
  9127.           Dynamic link from invalid privilege level - privilege level 2 routine
  9128.           cannot link to dynamic-link libraries.
  9129.  
  9130.   197   ERROR_IOPL_NOT_ENABLED
  9131.           IOPL not enabled - IOPL set to NO in CONFIG.SYS.
  9132.  
  9133.   198   ERROR_INVALID_SEGDPL
  9134.           Invalid segment descriptor privilege level - can only have privilege
  9135.           levels of 2 and 3.
  9136.  
  9137.   199   ERROR_AUTODATASEG_EXCEEDS_64k
  9138.           Automatic data segment exceeds 64KB.
  9139.  
  9140.   200   ERROR_RING2SEG_MUST_BE_MOVABLE
  9141.           Privilege level 2 segment must be movable.
  9142.  
  9143.   201   ERROR_RELOC_CHAIN_XEEDS_SEGLIM
  9144.           Relocation chain exceeds segment limit.
  9145.  
  9146.   202   ERROR_INFLOOP_IN_RELOC_CHAIN
  9147.           Infinite loop in relocation chain segment.
  9148.  
  9149.   203   ERROR_ENVVAR_NOT_FOUND
  9150.           Environment variable not found.
  9151.  
  9152.   204   ERROR_NOT_CURRENT_CTRY
  9153.           Not current country.
  9154.  
  9155.   205   ERROR_NO_SIGNAL_SENT
  9156.           No signal sent - no process in the command subtree has a signal
  9157.           handler.
  9158.  
  9159.   206   ERROR_FILENAME_EXCED_RANGE
  9160.           File name or extension is greater than 8.3 characters.
  9161.  
  9162.   207   ERROR_RING2_STACK_IN_USE
  9163.           Privilege level 2 stack is in use.
  9164.  
  9165.   208   ERROR_META_EXPANSION_TOO_LONG
  9166.           Meta (global) expansion is too long.
  9167.  
  9168.   209   ERROR_INVALID_SIGNAL_NUMBER
  9169.           Invalid signal number.
  9170.  
  9171.   210   ERROR_THREAD_1_INACTIVE
  9172.           Inactive thread.
  9173.  
  9174.   211   ERROR_INFO_NOT_AVAIL
  9175.           File system information is not available for this file.
  9176.  
  9177.   212   ERROR_LOCKED
  9178.           Locked error.
  9179.  
  9180.   213   ERROR_BAD_DYNALINK
  9181.           Attempted to execute a non-family API in DOS mode.
  9182.  
  9183.   214   ERROR_TOO_MANY_MODULES
  9184.           Too many modules.
  9185.  
  9186.   215   ERROR_NESTING_NOT_ALLOWED
  9187.           Nesting is not allowed.
  9188.  
  9189.   217   ERROR_ZOMBIE_PROCESS
  9190.           Zombie process.
  9191.  
  9192.   218   ERROR_STACK_IN_HIGH_MEMORY
  9193.           Stack is in high memory.
  9194.  
  9195.   219   ERROR_INVALID_EXITROUTINE_RING
  9196.           Invalid exit routine ring.
  9197.  
  9198.   220   ERROR_GETBUF_FAILED
  9199.           Get buffer failed.
  9200.  
  9201.   221   ERROR_FLUSHBUF_FAILED
  9202.           Flush buffer failed.
  9203.  
  9204.   222   ERROR_TRANSFER_TOO_LONG
  9205.           Transfer is too long.
  9206.  
  9207.   224   ERROR_SMG_NO_TARGET_WINDOW
  9208.           The application window was created without the FCF_TASKLIST
  9209.           style, or the application window not yet been created or has already
  9210.           been destroyed.
  9211.  
  9212.   228   ERROR_NO_CHILDREN
  9213.           No child process.
  9214.  
  9215.   229   ERROR_INVALID_SCREEN_GROUP
  9216.           Invalid session.
  9217.  
  9218.   230   ERROR_BAD_PIPE
  9219.           Non-existent pipe or invalid operation.
  9220.  
  9221.   231   ERROR_PIPE_BUSY
  9222.           Pipe is busy.
  9223.  
  9224.   232   ERROR_NO_DATA
  9225.           No data available on non-blocking read.
  9226.  
  9227.   233   ERROR_PIPE_NOT_CONNECTED
  9228.           Pipe was disconnected by server.
  9229.  
  9230.   234   ERROR_MORE_DATA
  9231.           More data is available.
  9232.  
  9233.   240   ERROR_VC_DISCONNECTED
  9234.           Session was dropped due to errors.
  9235.  
  9236.   250   ERROR_CIRCULARITY_REQUESTED
  9237.           Renaming a directory that would cause a circularity problem.
  9238.  
  9239.   251   ERROR_DIRECTORY_IN_CDS
  9240.           Renaming a directory that is in use.
  9241.  
  9242.   252   ERROR_INVALID_FSD_NAME
  9243.           Trying to access nonexistent FSD.
  9244.  
  9245.   253   ERROR_INVALID_PATH
  9246.           Invalid pseudo device.
  9247.  
  9248.   254   ERROR_INVALID_EA_NAME
  9249.           Invalid character in name, or invalid cbName.
  9250.  
  9251.   255   ERROR_EA_LIST_INCONSISTENT
  9252.           List does not match its size, or there are invalid EAs in the list.
  9253.  
  9254.   256   ERROR_EA_LIST_TOO_LONG
  9255.           FEAList is longer than 64K-1 bytes.
  9256.  
  9257.   257   ERROR_NO_META_MATCH
  9258.           String does not match expression.
  9259.  
  9260.   259   ERROR_NO_MORE_ITEMS
  9261.           DosQueryFSAttach ordinal query.
  9262.  
  9263.   260   ERROR_SEARCH_STRUC_REUSED
  9264.           DOS mode findfirst/next search structure reused.
  9265.  
  9266.   261   ERROR_CHAR_NOT_FOUND
  9267.           Character not found.
  9268.  
  9269.   262   ERROR_TOO_MUCH_STACK
  9270.           Stack request exceeds system limit.
  9271.  
  9272.   263   ERROR_INVALID_ATTR
  9273.           Invalid attribute.
  9274.  
  9275.   264   ERROR_INVALID_STARTING_RING
  9276.           Invalid starting ring.
  9277.  
  9278.   265   ERROR_INVALID_DLL_INIT_RING
  9279.           Invalid DLL INIT ring.
  9280.  
  9281.   266   ERROR_CANNOT_COPY
  9282.           Cannot copy.
  9283.  
  9284.   267   ERROR_DIRECTORY
  9285.           Used by DOSCOPY in doscall1.
  9286.  
  9287.   268   ERROR_OPLOCKED_FILE
  9288.           Oplocked file.
  9289.  
  9290.   269   ERROR_OPLOCK_THREAD_EXISTS
  9291.           Oplock thread exists.
  9292.  
  9293.   270   ERROR_VOLUME_CHANGED
  9294.           Volume changed.
  9295.  
  9296.   271-273   Reserved.
  9297.  
  9298.  
  9299.   274   ERROR_ALREADY_SHUTDOWN
  9300.           System is already shut down.
  9301.  
  9302.   275   ERROR_EAS_DIDNT_FIT
  9303.           Buffer is not big enough to hold the EAs.
  9304.  
  9305.   276   ERROR_EA_FILE_CORRUPT
  9306.           EA file has been damaged.
  9307.  
  9308.   277   ERROR_EA_TABLE_FULL
  9309.           EA table is full.
  9310.  
  9311.   278   ERROR_INVALID_EA_HANDLE
  9312.           EA handle is invalid.
  9313.  
  9314.   279   ERROR_NO_CLUSTER
  9315.           No cluster.
  9316.  
  9317.   280   ERROR_CREATE_EA_FILE
  9318.           Cannot create the EA file.
  9319.  
  9320.   281   ERROR_CANNOT_OPEN_EA_FILE
  9321.           Cannot open the EA file.
  9322.  
  9323.   282   ERROR_EAS_NOT_SUPPORTED
  9324.           Destination file system does not support EAs.
  9325.  
  9326.   283   ERROR_NEED_EAS_FOUND
  9327.           Destination file system does not support EAs, and the source file's
  9328.           EAs contain a need EA.
  9329.  
  9330.   284   ERROR_DUPLICATE_HANDLE
  9331.           The handle already exists.
  9332.  
  9333.   285   ERROR_DUPLICATE_NAME
  9334.           The name already exists.
  9335.  
  9336.   286   ERROR_EMPTY_MUXWAIT
  9337.           The list of semaphores in a muxwait semaphore is empty.
  9338.  
  9339.   287   ERROR_MUTEX_OWNED
  9340.           The calling thread owns one or more of the mutex semaphores in the
  9341.           list.
  9342.  
  9343.   288   ERROR_NOT_OWNER
  9344.           Caller does not own the semaphore.
  9345.  
  9346.   289   ERROR_PARAM_TOO_SMALL
  9347.           Parameter is not large enough to contain all of the semaphore
  9348.           records in the muxwait semaphore.
  9349.  
  9350.   290   ERROR_TOO_MANY_HANDLES
  9351.           Limit reached for number of handles.
  9352.  
  9353.   291   ERROR_TOO_MANY_OPENS
  9354.           There are too many files or semaphores open.
  9355.  
  9356.   292   ERROR_WRONG_TYPE
  9357.           Attempted to create wrong type of semaphore.
  9358.  
  9359.   293   ERROR_UNUSED_CODE
  9360.           Code is not used.
  9361.  
  9362.   294   ERROR_THREAD_NOT_TERMINATED
  9363.           Thread has not terminated.
  9364.  
  9365.   295   ERROR_INIT_ROUTINE_FAILED
  9366.           Initialization routine failed.
  9367.  
  9368.   296   ERROR_MODULE_IN_USE
  9369.           Module is in use.
  9370.  
  9371.   297   ERROR_NOT_ENOUGH_WATCHPOINTS
  9372.           There are not enough watchpoints.
  9373.  
  9374.   298   ERROR_TOO_MANY_POSTS
  9375.           Post count limit was reached for an event semaphore.
  9376.  
  9377.   299   ERROR_ALREADY_POSTED
  9378.           Event semaphore is already posted.
  9379.  
  9380.   300   ERROR_ALREADY_RESET
  9381.           Event semaphore is already reset.
  9382.  
  9383.   301   ERROR_SEM_BUSY
  9384.           Semaphore is busy.
  9385.  
  9386.   302   Reserved
  9387.  
  9388.  
  9389.   303   ERROR_INVALID_PROCID
  9390.           Invalid process identity.
  9391.  
  9392.   304   ERROR_INVALID_PDELTA
  9393.           Invalid priority delta.
  9394.  
  9395.   305   ERROR_NOT_DESCENDANT
  9396.           Not descendant.
  9397.  
  9398.   306   ERROR_NOT_SESSION_MANAGER
  9399.           Requestor not session manager.
  9400.  
  9401.   307   ERROR_INVALID_PCLASS
  9402.           Invalid P class.
  9403.  
  9404.   308   ERROR_INVALID_SCOPE
  9405.           Invalid scope.
  9406.  
  9407.   309   ERROR_INVALID_THREADID
  9408.           Invalid thread identity.
  9409.  
  9410.   310   ERROR_DOSSUB_SHRINK
  9411.           Cannot shrink segment - DosSubSetMem.
  9412.  
  9413.   311   ERROR_DOSSUB_NOMEM
  9414.           No memory to satisfy request - DosSubAllocMem.
  9415.  
  9416.   312   ERROR_DOSSUB_OVERLAP
  9417.           Overlap of the specified block with a block of allocated memory -
  9418.           DosSubFreeMem.
  9419.  
  9420.   313   ERROR_DOSSUB_BADSIZE
  9421.           Invalid size parameter - DosSubAllocMem or DosSubFreeMem.
  9422.  
  9423.   314   ERROR_DOSSUB_BADFLAG
  9424.           Invalid flag parameter - DosSubSetMem.
  9425.  
  9426.   315   ERROR_DOSSUB_BADSELECTOR
  9427.           Invalid segment selector.
  9428.  
  9429.   316   ERROR_MR_MSG_TOO_LONG
  9430.           Message too long for buffer.
  9431.  
  9432.   317   ERROR_MR_MID_NOT_FOUND
  9433.           Message identity number not found.
  9434.  
  9435.   318   ERROR_MR_UN_ACC_MSGF
  9436.           Unable to access message file.
  9437.  
  9438.   319   ERROR_MR_INV_MSGF_FORMAT
  9439.           Invalid message file format.
  9440.  
  9441.   320   ERROR_MR_INV_IVCOUNT
  9442.           Invalid insertion variable count.
  9443.  
  9444.   321   ERROR_MR_UN_PERFORM
  9445.           Unable to perform function.
  9446.  
  9447.   322   ERROR_TS_WAKEUP
  9448.           Unable to wake up.
  9449.  
  9450.   323   ERROR_TS_SEMHANDLE
  9451.           Invalid system semaphore.
  9452.  
  9453.   324   ERROR_TS_NOTIMER
  9454.           No timers available.
  9455.  
  9456.   326   ERROR_TS_HANDLE
  9457.           Invalid timer handle.
  9458.  
  9459.   327   ERROR_TS_DATETIME
  9460.           Date or time invalid.
  9461.  
  9462.   328   ERROR_SYS_INTERNAL
  9463.           Internal system error.
  9464.  
  9465.   329   ERROR_QUE_CURRENT_NAME
  9466.           Current queue name does not exist.
  9467.  
  9468.   330   ERROR_QUE_PROC_NOT_OWNED
  9469.           Current process does not own queue.
  9470.  
  9471.   331   ERROR_QUE_PROC_OWNED
  9472.           Current process owns queue.
  9473.  
  9474.   332   ERROR_QUE_DUPLICATE
  9475.           Duplicate queue name.
  9476.  
  9477.   333   ERROR_QUE_ELEMENT_NOT_EXIST
  9478.           Queue element does not exist.
  9479.  
  9480.   334   ERROR_QUE_NO_MEMORY
  9481.           Inadequate queue memory.
  9482.  
  9483.   335   ERROR_QUE_INVALID_NAME
  9484.           Invalid queue name.
  9485.  
  9486.   336   ERROR_QUE_INVALID_PRIORITY
  9487.           Invalid queue priority parameter.
  9488.  
  9489.   337   ERROR_QUE_INVALID_HANDLE
  9490.           Invalid queue handle.
  9491.  
  9492.   338   ERROR_QUE_LINK_NOT_FOUND
  9493.           Queue link not found.
  9494.  
  9495.   339   ERROR_QUE_MEMORY_ERROR
  9496.           Queue memory error.
  9497.  
  9498.   340   ERROR_QUE_PREV_AT_END
  9499.           Previous queue element was at end of queue.
  9500.  
  9501.   341   ERROR_QUE_PROC_NO_ACCESS
  9502.           Process does not have access to queues.
  9503.  
  9504.   342   ERROR_QUE_EMPTY
  9505.           Queue is empty.
  9506.  
  9507.   343   ERROR_QUE_NAME_NOT_EXIST
  9508.           Queue name does not exist.
  9509.  
  9510.   344   ERROR_QUE_NOT_INITIALIZED
  9511.           Queues not initialized.
  9512.  
  9513.   345   ERROR_QUE_UNABLE_TO_ACCESS
  9514.           Unable to access queues.
  9515.  
  9516.   346   ERROR_QUE_UNABLE_TO_ADD
  9517.           Unable to add new queue.
  9518.  
  9519.   347   ERROR_QUE_UNABLE_TO_INIT
  9520.           Unable to initialize queues.
  9521.  
  9522.   349   ERROR_VIO_INVALID_MASK
  9523.           Invalid function replaced.
  9524.  
  9525.   350   ERROR_VIO_PTR
  9526.           Invalid pointer to parameter.
  9527.  
  9528.   351   ERROR_VIO_APTR
  9529.           Invalid pointer to attribute.
  9530.  
  9531.   352   ERROR_VIO_RPTR
  9532.           Invalid pointer to row.
  9533.  
  9534.   353   ERROR_VIO_CPTR
  9535.           Invalid pointer to column.
  9536.  
  9537.   354   ERROR_VIO_LPTR
  9538.           Invalid pointer to length.
  9539.  
  9540.   355   ERROR_VIO_MODE
  9541.           Unsupported screen mode.
  9542.  
  9543.   356   ERROR_VIO_WIDTH
  9544.           Invalid cursor width value.
  9545.  
  9546.   357   ERROR_VIO_ATTR
  9547.           Invalid cursor attribute value.
  9548.  
  9549.   358   ERROR_VIO_ROW
  9550.           Invalid row value.
  9551.  
  9552.   359   ERROR_VIO_COL
  9553.           Invalid column value.
  9554.  
  9555.   360   ERROR_VIO_TOPROW
  9556.           Invalid TopRow value.
  9557.  
  9558.   361   ERROR_VIO_BOTROW
  9559.           Invalid BotRow value.
  9560.  
  9561.   362   ERROR_VIO_RIGHTCOL
  9562.           Invalid right column value.
  9563.  
  9564.   363   ERROR_VIO_LEFTCOL
  9565.           Invalid left column value.
  9566.  
  9567.   364   ERROR_SCS_CALL
  9568.           Call issued by other than session manager.
  9569.  
  9570.   365   ERROR_SCS_VALUE
  9571.           Value is not for save or restore.
  9572.  
  9573.   366   ERROR_VIO_WAIT_FLAG
  9574.           Invalid wait flag setting.
  9575.  
  9576.   367   ERROR_VIO_UNLOCK
  9577.           Screen not previously locked.
  9578.  
  9579.   368   ERROR_SGS_NOT_SESSION_MGR
  9580.           Caller not session manager.
  9581.  
  9582.   369   ERROR_SMG_INVALID_SGID
  9583.           Invalid session identity.
  9584.  
  9585.   369   ERROR_SMG_INVALID_SESSION_ID
  9586.           Invalid session ID.
  9587.  
  9588.   370   ERROR_SMG_NOSG
  9589.           No sessions available.
  9590.  
  9591.   370   ERROR_SMG_NO_SESSIONS
  9592.           No sessions available.
  9593.  
  9594.   371   ERROR_SMG_GRP_NOT_FOUND
  9595.           Session not found.
  9596.  
  9597.   371   ERROR_SMG_SESSION_NOT_FOUND
  9598.           Session not found.
  9599.  
  9600.   372   ERROR_SMG_SET_TITLE
  9601.           Title sent by shell or parent cannot be changed.
  9602.  
  9603.   373   ERROR_KBD_PARAMETER
  9604.           Invalid parameter to keyboard.
  9605.  
  9606.   374   ERROR_KBD_NO_DEVICE
  9607.           No device.
  9608.  
  9609.   375   ERROR_KBD_INVALID_IOWAIT
  9610.           Invalid I/O wait specified.
  9611.  
  9612.   376   ERROR_KBD_INVALID_LENGTH
  9613.           Invalid length for keyboard.
  9614.  
  9615.   377   ERROR_KBD_INVALID_ECHO_MASK
  9616.           Invalid echo mode mask.
  9617.  
  9618.   378   ERROR_KBD_INVALID_INPUT_MASK
  9619.           Invalid input mode mask.
  9620.  
  9621.   379   ERROR_MON_INVALID_PARMS
  9622.           Invalid parameters to DosMon.
  9623.  
  9624.   380   ERROR_MON_INVALID_DEVNAME
  9625.           Invalid device name string.
  9626.  
  9627.   381   ERROR_MON_INVALID_HANDLE
  9628.           Invalid device handle.
  9629.  
  9630.   382   ERROR_MON_BUFFER_TOO_SMALL
  9631.           Buffer too small.
  9632.  
  9633.   383   ERROR_MON_BUFFER_EMPTY
  9634.           Buffer is empty.
  9635.  
  9636.   384   ERROR_MON_DATA_TOO_LARGE
  9637.           Data record is too large.
  9638.  
  9639.   385   ERROR_MOUSE_NO_DEVICE
  9640.           Mouse device closed (invalid device handle).
  9641.  
  9642.   386   ERROR_MOUSE_INV_HANDLE
  9643.           Mouse device closed (invalid device handle).
  9644.  
  9645.   387   ERROR_MOUSE_INV_PARMS
  9646.           Parameters invalid for display mode.
  9647.  
  9648.   388   ERROR_MOUSE_CANT_RESET
  9649.           Function assigned and cannot be reset.
  9650.  
  9651.   389   ERROR_MOUSE_DISPLAY_PARMS
  9652.           Parameters invalid for display mode.
  9653.  
  9654.   390   ERROR_MOUSE_INV_MODULE
  9655.           Module not valid.
  9656.  
  9657.   391   ERROR_MOUSE_INV_ENTRY_PT
  9658.           Entry point not valid.
  9659.  
  9660.   392   ERROR_MOUSE_INV_MASK
  9661.           Function mask invalid.
  9662.  
  9663.   393   NO_ERROR_MOUSE_NO_DATA
  9664.           No valid data.
  9665.  
  9666.   394   NO_ERROR_MOUSE_PTR_DRAWN
  9667.           Pointer drawn.
  9668.  
  9669.   395   ERROR_INVALID_FREQUENCY
  9670.           Invalid frequency for beep.
  9671.  
  9672.   396   ERROR_NLS_NO_COUNTRY_FILE
  9673.           Cannot find COUNTRY.SYS file.
  9674.  
  9675.   397   ERROR_NLS_OPEN_FAILED
  9676.           Cannot open COUNTRY.SYS file.
  9677.  
  9678.   398   ERROR_NLS_NO_CTRY_CODE
  9679.           Country code not found.
  9680.  
  9681.   398   ERROR_NO_COUNTRY_OR_CODEPAGE
  9682.           Country code not found.
  9683.  
  9684.   399   ERROR_NLS_TABLE_TRUNCATED
  9685.           Table returned information truncated, buffer is too small.
  9686.  
  9687.   400   ERROR_NLS_BAD_TYPE
  9688.           Selected type does not exist.
  9689.  
  9690.   401   ERROR_NLS_TYPE_NOT_FOUND
  9691.           Selected type is not in file.
  9692.  
  9693.   402   ERROR_VIO_SMG_ONLY
  9694.           Valid from session manager only.
  9695.  
  9696.   403   ERROR_VIO_INVALID_ASCIIZ
  9697.           Invalid ASCIIZ length.
  9698.  
  9699.   404   ERROR_VIO_DEREGISTER
  9700.           VioDeRegister not allowed.
  9701.  
  9702.   405   ERROR_VIO_NO_POPUP
  9703.           Pop-up window not allocated.
  9704.  
  9705.   406   ERROR_VIO_EXISTING_POPUP
  9706.           Pop-up window on screen (NoWait).
  9707.  
  9708.   407   ERROR_KBD_SMG_ONLY
  9709.           Valid from session manager only.
  9710.  
  9711.   408   ERROR_KBD_INVALID_ASCIIZ
  9712.           Invalid ASCIIZ length.
  9713.  
  9714.   409   ERROR_KBD_INVALID_MASK
  9715.           Invalid replacement mask.
  9716.  
  9717.   410   ERROR_KBD_REGISTER
  9718.           KbdRegister not allowed.
  9719.  
  9720.   411   ERROR_KBD_DEREGISTER
  9721.           KbdDeRegister not allowed.
  9722.  
  9723.   412   ERROR_MOUSE_SMG_ONLY
  9724.           Valid from session manager only.
  9725.  
  9726.   413   ERROR_MOUSE_INVALID_ASCIIZ
  9727.           Invalid ASCIIZ length.
  9728.  
  9729.   414   ERROR_MOUSE_INVALID_MASK
  9730.           Invalid replacement mask.
  9731.  
  9732.   415   ERROR_MOUSE_REGISTER
  9733.           Mouse register not allowed.
  9734.  
  9735.   416   ERROR_MOUSE_DEREGISTER
  9736.           Mouse deregister not allowed.
  9737.  
  9738.   417   ERROR_SMG_BAD_ACTION
  9739.           Invalid action specified.
  9740.  
  9741.   418   ERROR_SMG_INVALID_CALL
  9742.           INIT called more than once, or invalid session identity.
  9743.  
  9744.   419   ERROR_SCS_SG_NOTFOUND
  9745.           New session number.
  9746.  
  9747.   420   ERROR_SCS_NOT_SHELL
  9748.           Caller is not shell.
  9749.  
  9750.   421   ERROR_VIO_INVALID_PARMS
  9751.           Invalid parameters passed.
  9752.  
  9753.   422   ERROR_VIO_FUNCTION_OWNED
  9754.           Save/restore already owned.
  9755.  
  9756.   423   ERROR_VIO_RETURN
  9757.           Non-destruct return (undo).
  9758.  
  9759.   424   ERROR_SCS_INVALID_FUNCTION
  9760.           Caller invalid function.
  9761.  
  9762.   425   ERROR_SCS_NOT_SESSION_MGR
  9763.           Caller not session manager.
  9764.  
  9765.   426   ERROR_VIO_REGISTER
  9766.           Vio register not allowed.
  9767.  
  9768.   427   ERROR_VIO_NO_MODE_THREAD
  9769.           No mode restore thread in SG.
  9770.  
  9771.   428   ERROR_VIO_NO_SAVE_RESTORE_THD
  9772.           No save/restore thread in SG.
  9773.  
  9774.   429   ERROR_VIO_IN_BG
  9775.           Function invalid in background.
  9776.  
  9777.   430   ERROR_VIO_ILLEGAL_DURING_POPUP
  9778.           Function not allowed during pop-up window.
  9779.  
  9780.   431   ERROR_SMG_NOT_BASESHELL
  9781.           Caller is not the base shell.
  9782.  
  9783.   432   ERROR_SMG_BAD_STATUSREQ
  9784.           Invalid status requested.
  9785.  
  9786.   433   ERROR_QUE_INVALID_WAIT
  9787.           NoWait parameter out of bounds.
  9788.  
  9789.   434   ERROR_VIO_LOCK
  9790.           Error returned from Scroll Lock.
  9791.  
  9792.   435   ERROR_MOUSE_INVALID_IOWAIT
  9793.           Invalid parameters for IOWait.
  9794.  
  9795.   436   ERROR_VIO_INVALID_HANDLE
  9796.           Invalid VIO handle.
  9797.  
  9798.   437   ERROR_VIO_ILLEGAL_DURING_LOCK
  9799.           Function not allowed during screen lock.
  9800.  
  9801.   438   ERROR_VIO_INVALID_LENGTH
  9802.           Invalid VIO length.
  9803.  
  9804.   439   ERROR_KBD_INVALID_HANDLE
  9805.           Invalid KBD handle.
  9806.  
  9807.   440   ERROR_KBD_NO_MORE_HANDLE
  9808.           Ran out of handles.
  9809.  
  9810.   441   ERROR_KBD_CANNOT_CREATE_KCB
  9811.           Unable to create kcb.
  9812.  
  9813.   442   ERROR_KBD_CODEPAGE_LOAD_INCOMPL
  9814.           Unsuccessful code-page load.
  9815.  
  9816.   443   ERROR_KBD_INVALID_CODEPAGE_ID
  9817.           Invalid code-page identity.
  9818.  
  9819.   444   ERROR_KBD_NO_CODEPAGE_SUPPORT
  9820.           No code page support.
  9821.  
  9822.   445   ERROR_KBD_FOCUS_REQUIRED
  9823.           Keyboard focus required.
  9824.  
  9825.   446   ERROR_KBD_FOCUS_ALREADY_ACTIVE
  9826.           Calling thread has an outstanding focus.
  9827.  
  9828.   447   ERROR_KBD_KEYBOARD_BUSY
  9829.           Keyboard is busy.
  9830.  
  9831.   448   ERROR_KBD_INVALID_CODEPAGE
  9832.           Invalid code page.
  9833.  
  9834.   449   ERROR_KBD_UNABLE_TO_FOCUS
  9835.           Focus attempt failed.
  9836.  
  9837.   450   ERROR_SMG_SESSION_NON_SELECT
  9838.           Session is not selectable.
  9839.  
  9840.   451   ERROR_SMG_SESSION_NOT_FOREGRND
  9841.           Parent/child session is not foreground.
  9842.  
  9843.   452   ERROR_SMG_SESSION_NOT_PARENT
  9844.           Not parent of requested child.
  9845.  
  9846.   453   ERROR_SMG_INVALID_START_MODE
  9847.           Invalid session start mode.
  9848.  
  9849.   454   ERROR_SMG_INVALID_RELATED_OPT
  9850.           Invalid session start related option.
  9851.  
  9852.   455   ERROR_SMG_INVALID_BOND_OPTION
  9853.           Invalid session bond option.
  9854.  
  9855.   456   ERROR_SMG_INVALID_SELECT_OPT
  9856.           Invalid session select option.
  9857.  
  9858.   457   ERROR_SMG_START_IN_BACKGROUND
  9859.           Session started in background.
  9860.  
  9861.   458   ERROR_SMG_INVALID_STOP_OPTION
  9862.           Invalid session stop option.
  9863.  
  9864.   459   ERROR_SMG_BAD_RESERVE
  9865.           Reserved parameters are not zero.
  9866.  
  9867.   460   ERROR_SMG_PROCESS_NOT_PARENT
  9868.           Session parent process already exists.
  9869.  
  9870.   461   ERROR_SMG_INVALID_DATA_LENGTH
  9871.           Invalid data length.
  9872.  
  9873.   462   ERROR_SMG_NOT_BOUND
  9874.           Parent is not bound.
  9875.  
  9876.   463   ERROR_SMG_RETRY_SUB_ALLOC
  9877.           Retry request block allocation.
  9878.  
  9879.   464   ERROR_KBD_DETACHED
  9880.           This call is not allowed for a detached PID.
  9881.  
  9882.   465   ERROR_VIO_DETACHED
  9883.           This call is not allowed for a detached PID.
  9884.  
  9885.   466   ERROR_MOU_DETACHED
  9886.           This call is not allowed for a detached PID.
  9887.  
  9888.   467   ERROR_VIO_FONT
  9889.           No font is available to support the mode.
  9890.  
  9891.   468   ERROR_VIO_USER_FONT
  9892.           User font is active.
  9893.  
  9894.   469   ERROR_VIO_BAD_CP
  9895.           Invalid code page specified.
  9896.  
  9897.   470   ERROR_VIO_NO_CP
  9898.           System displays do not support code page.
  9899.  
  9900.   471   ERROR_VIO_NA_CP
  9901.           Current display does not support code page.
  9902.  
  9903.   472   ERROR_INVALID_CODE_PAGE
  9904.           Invalid code page.
  9905.  
  9906.   473   ERROR_CPLIST_TOO_SMALL
  9907.           Code page list is too small.
  9908.  
  9909.   474   ERROR_CP_NOT_MOVED
  9910.           Code page was not moved.
  9911.  
  9912.   475   ERROR_MODE_SWITCH_INIT
  9913.           Mode switch initialization error.
  9914.  
  9915.   476   ERROR_CODE_PAGE_NOT_FOUND
  9916.           Code page was not found.
  9917.  
  9918.   477   ERROR_UNEXPECTED_SLOT_RETURNED
  9919.           Internal error.
  9920.  
  9921.   478   ERROR_SMG_INVALID_TRACE_OPTION
  9922.           Invalid start session trace indicator.
  9923.  
  9924.   479   ERROR_VIO_INTERNAL_RESOURCE
  9925.           VIO internal resource error.
  9926.  
  9927.   480   ERROR_VIO_SHELL_INIT
  9928.           VIO shell initialization error.
  9929.  
  9930.   481   ERROR_SMG_NO_HARD_ERRORS
  9931.           No session manager hard errors.
  9932.  
  9933.   482   ERROR_CP_SWITCH_INCOMPLETE
  9934.           DosSetProcessCp is unable to set a KBD or VIO code page.
  9935.  
  9936.   483   ERROR_VIO_TRANSPARENT_POPUP
  9937.           Error during VIO pop-up window.
  9938.  
  9939.   484   ERROR_CRITSEC_OVERFLOW
  9940.           Critical section overflow.
  9941.  
  9942.   485   ERROR_CRITSEC_UNDERFLOW
  9943.           Critical section underflow.
  9944.  
  9945.   486   ERROR_VIO_BAD_RESERVE
  9946.           Reserved parameter is not zero.
  9947.  
  9948.   487   ERROR_INVALID_ADDRESS
  9949.           Invalid physical address.
  9950.  
  9951.   488   ERROR_ZERO_SELECTORS_REQUESTED
  9952.           At least one selector must be requested.
  9953.  
  9954.   489   ERROR_NOT_ENOUGH_SELECTORS_AVA
  9955.           Not enough GDT selectors to satisfy request.
  9956.  
  9957.   490   ERROR_INVALID_SELECTOR
  9958.           Not a GDT selector.
  9959.  
  9960.   491   ERROR_SMG_INVALID_PROGRAM_TYPE
  9961.           Invalid program type.
  9962.  
  9963.   492   ERROR_SMG_INVALID_PGM_CONTROL
  9964.           Invalid program control.
  9965.  
  9966.   493   ERROR_SMG_INVALID_INHERIT_OPT
  9967.           Invalid inherit option.
  9968.  
  9969.   494   ERROR_VIO_EXTENDED_SG
  9970.  
  9971.  
  9972.   495   ERROR_VIO_NOT_PRES_MGR_SG
  9973.  
  9974.  
  9975.   496   ERROR_VIO_SHIELD_OWNED
  9976.  
  9977.  
  9978.   497   ERROR_VIO_NO_MORE_HANDLES
  9979.  
  9980.  
  9981.   498   ERROR_VIO_SEE_ERROR_LOG
  9982.  
  9983.  
  9984.   499   ERROR_VIO_ASSOCIATED_DC
  9985.  
  9986.  
  9987.   500   ERROR_KBD_NO_CONSOLE
  9988.  
  9989.  
  9990.   501   ERROR_MOUSE_NO_CONSOLE
  9991.  
  9992.  
  9993.   502   ERROR_MOUSE_INVALID_HANDLE
  9994.  
  9995.  
  9996.   503   ERROR_SMG_INVALID_DEBUG_PARMS
  9997.  
  9998.  
  9999.   504   ERROR_KBD_EXTENDED_SG
  10000.  
  10001.  
  10002.   505   ERROR_MOU_EXTENDED_SG
  10003.  
  10004.  
  10005.   506   ERROR_SMG_INVALID_ICON_FILE
  10006.  
  10007.  
  10008.   507   ERROR_TRC_PID_NON_EXISTENT
  10009.  
  10010.  
  10011.   508   ERROR_TRC_COUNT_ACTIVE
  10012.  
  10013.  
  10014.   509   ERROR_TRC_SUSPENDED_BY_COUNT
  10015.  
  10016.  
  10017.   510   ERROR_TRC_COUNT_INACTIVE
  10018.  
  10019.  
  10020.   511   ERROR_TRC_COUNT_REACHED
  10021.  
  10022.  
  10023.   512   ERROR_NO_MC_TRACE
  10024.  
  10025.  
  10026.   513   ERROR_MC_TRACE
  10027.  
  10028.  
  10029.   514   ERROR_TRC_COUNT_ZERO
  10030.  
  10031.  
  10032.   515   ERROR_SMG_TOO_MANY_DDS
  10033.  
  10034.  
  10035.   516   ERROR_SMG_INVALID_NOTIFICATION
  10036.  
  10037.  
  10038.   517   ERROR_LF_INVALID_FUNCTION
  10039.  
  10040.  
  10041.   518   ERROR_LF_NOT_AVAIL
  10042.  
  10043.  
  10044.   519   ERROR_LF_SUSPENDED
  10045.  
  10046.  
  10047.   520   ERROR_LF_BUF_TOO_SMALL
  10048.  
  10049.  
  10050.   521   ERROR_LF_BUFFER_CORRUPTED
  10051.  
  10052.  
  10053.   521   ERROR_LF_BUFFER_FULL
  10054.  
  10055.  
  10056.   522   ERROR_LF_INVALID_DAEMON
  10057.  
  10058.  
  10059.   522   ERROR_LF_INVALID_RECORD
  10060.  
  10061.  
  10062.   523   ERROR_LF_INVALID_TEMPL
  10063.  
  10064.  
  10065.   523   ERROR_LF_INVALID_SERVICE
  10066.  
  10067.  
  10068.   524   ERROR_LF_GENERAL_FAILURE
  10069.  
  10070.  
  10071.   525   ERROR_LF_INVALID_ID
  10072.  
  10073.  
  10074.   526   ERROR_LF_INVALID_HANDLE
  10075.  
  10076.  
  10077.   527   ERROR_LF_NO_ID_AVAIL
  10078.  
  10079.  
  10080.   528   ERROR_LF_TEMPLATE_AREA_FULL
  10081.  
  10082.  
  10083.   529   ERROR_LF_ID_IN_USE
  10084.  
  10085.  
  10086.   530   ERROR_MOU_NOT_INITIALIZED
  10087.  
  10088.  
  10089.   531   ERROR_MOUINITREAL_DONE
  10090.  
  10091.  
  10092.   532   ERROR_DOSSUB_CORRUPTED
  10093.  
  10094.  
  10095.   533   ERROR_MOUSE_CALLER_NOT_SUBSYS
  10096.  
  10097.  
  10098.   534   ERROR_ARITHMETIC_OVERFLOW
  10099.  
  10100.  
  10101.   535   ERROR_TMR_NO_DEVICE
  10102.  
  10103.  
  10104.   536   ERROR_TMR_INVALID_TIME
  10105.  
  10106.  
  10107.   537   ERROR_PVW_INVALID_ENTITY
  10108.  
  10109.  
  10110.   538   ERROR_PVW_INVALID_ENTITY_TYPE
  10111.  
  10112.  
  10113.   539   ERROR_PVW_INVALID_SPEC
  10114.  
  10115.  
  10116.   540   ERROR_PVW_INVALID_RANGE_TYPE
  10117.  
  10118.  
  10119.   541   ERROR_PVW_INVALID_COUNTER_BLK
  10120.  
  10121.  
  10122.   542   ERROR_PVW_INVALID_TEXT_BLK
  10123.  
  10124.  
  10125.   543   ERROR_PRF_NOT_INITIALIZED
  10126.  
  10127.  
  10128.   544   ERROR_PRF_ALREADY_INITIALIZED
  10129.  
  10130.  
  10131.   545   ERROR_PRF_NOT_STARTED
  10132.  
  10133.  
  10134.   546   ERROR_PRF_ALREADY_STARTED
  10135.  
  10136.  
  10137.   547   ERROR_PRF_TIMER_OUT_OF_RANGE
  10138.  
  10139.  
  10140.   548   ERROR_PRF_TIMER_RESET
  10141.  
  10142.  
  10143.   639   ERROR_VDD_LOCK_USEAGE_DENIED
  10144.  
  10145.  
  10146.   640   ERROR_TIMEOUT
  10147.  
  10148.  
  10149.   641   ERROR_VDM_DOWN
  10150.  
  10151.  
  10152.   642   ERROR_VDM_LIMIT
  10153.  
  10154.  
  10155.   643   ERROR_VDD_NOT_FOUND
  10156.  
  10157.  
  10158.   644   ERROR_INVALID_CALLER
  10159.  
  10160.  
  10161.   645   ERROR_PID_MISMATCH
  10162.  
  10163.  
  10164.   646   ERROR_INVALID_VDD_HANDLE
  10165.  
  10166.  
  10167.   647   ERROR_VLPT_NO_SPOOLER
  10168.  
  10169.  
  10170.   648   ERROR_VCOM_DEVICE_BUSY
  10171.  
  10172.  
  10173.   649   ERROR_VLPT_DEVICE_BUSY
  10174.  
  10175.  
  10176.   650   ERROR_NESTING_TOO_DEEP
  10177.  
  10178.  
  10179.   651   ERROR_VDD_MISSING
  10180.  
  10181.  
  10182.   691   ERROR_IMP_INVALID_PARM
  10183.  
  10184.  
  10185.   692   ERROR_IMP_INVALID_LENGTH
  10186.  
  10187.  
  10188.   693   MSG_HPFS_DISK_ERROR_WARN
  10189.  
  10190.  
  10191.   730   ERROR_MON_BAD_BUFFER
  10192.  
  10193.  
  10194.   731   ERROR_MODULE_CORRUPTED
  10195.  
  10196.  
  10197.   2055   ERROR_LF_TIMEOUT
  10198.  
  10199.  
  10200.   2057   ERROR_LF_SUSPEND_SUCCESS
  10201.  
  10202.  
  10203.   2058   ERROR_LF_RESUME_SUCCESS
  10204.  
  10205.  
  10206.   2059   ERROR_LF_REDIRECT_SUCCESS
  10207.  
  10208.  
  10209.   2060   ERROR_LF_REDIRECT_FAILURE
  10210.  
  10211.  
  10212.   32768   ERROR_SWAPPER_NOT_ACTIVE
  10213.  
  10214.  
  10215.   32769   ERROR_INVALID_SWAPID
  10216.  
  10217.  
  10218.   32770   ERROR_IOERR_SWAP_FILE
  10219.  
  10220.  
  10221.   32771   ERROR_SWAP_TABLE_FULL
  10222.  
  10223.  
  10224.   32772   ERROR_SWAP_FILE_FULL
  10225.  
  10226.  
  10227.   32773   ERROR_CANT_INIT_SWAPPER
  10228.  
  10229.  
  10230.   32774   ERROR_SWAPPER_ALREADY_INIT
  10231.  
  10232.  
  10233.   32775   ERROR_PMM_INSUFFICIENT_MEMORY
  10234.  
  10235.  
  10236.   32776   ERROR_PMM_INVALID_FLAGS
  10237.  
  10238.  
  10239.   32777   ERROR_PMM_INVALID_ADDRESS
  10240.  
  10241.  
  10242.   32778   ERROR_PMM_LOCK_FAILED
  10243.  
  10244.  
  10245.   32779   ERROR_PMM_UNLOCK_FAILED
  10246.  
  10247.  
  10248.   32780   ERROR_PMM_MOVE_INCOMPLETE
  10249.  
  10250.  
  10251.   32781   ERROR_UCOM_DRIVE_RENAMED
  10252.  
  10253.  
  10254.   32782   ERROR_UCOM_FILENAME_TRUNCATED
  10255.  
  10256.  
  10257.   32783   ERROR_UCOM_BUFFER_LENGTH
  10258.  
  10259.  
  10260.   32784   ERROR_MON_CHAIN_HANDLE
  10261.  
  10262.  
  10263.   32785   ERROR_MON_NOT_REGISTERED
  10264.  
  10265.  
  10266.   32786   ERROR_SMG_ALREADY_TOP
  10267.  
  10268.  
  10269.   32787   ERROR_PMM_ARENA_MODIFIED
  10270.  
  10271.  
  10272.   32788   ERROR_SMG_PRINTER_OPEN
  10273.  
  10274.  
  10275.   32789   ERROR_PMM_SET_FLAGS_FAILED
  10276.  
  10277.  
  10278.   32790   ERROR_INVALID_DOS_DD
  10279.  
  10280.  
  10281.   32791   ERROR_BLOCKED
  10282.  
  10283.  
  10284.   32792   ERROR_NOBLOCK
  10285.  
  10286.  
  10287.   32793   ERROR_INSTANCE_SHARED
  10288.  
  10289.  
  10290.   32794   ERROR_NO_OBJECT
  10291.  
  10292.  
  10293.   32795   ERROR_PARTIAL_ATTACH
  10294.  
  10295.  
  10296.   32796   ERROR_INCACHE
  10297.  
  10298.  
  10299.   32797   ERROR_SWAP_IO_PROBLEMS
  10300.  
  10301.  
  10302.   32798   ERROR_CROSSES_OBJECT_BOUNDARY
  10303.  
  10304.  
  10305.   32799   ERROR_LONGLOCK
  10306.  
  10307.  
  10308.   32800   ERROR_SHORTLOCK
  10309.  
  10310.  
  10311.   32801   ERROR_UVIRTLOCK
  10312.  
  10313.  
  10314.   32802   ERROR_ALIASLOCK
  10315.  
  10316.  
  10317.   32803   ERROR_ALIAS
  10318.  
  10319.  
  10320.   32804   ERROR_NO_MORE_HANDLES
  10321.  
  10322.  
  10323.   32805   ERROR_SCAN_TERMINATED
  10324.  
  10325.  
  10326.   32806   ERROR_TERMINATOR_NOT_FOUND
  10327.  
  10328.  
  10329.   32807   ERROR_NOT_DIRECT_CHILD
  10330.  
  10331.  
  10332.   32808   ERROR_DELAY_FREE
  10333.  
  10334.  
  10335.   32809   ERROR_GUARDPAGE
  10336.  
  10337.  
  10338.   32900   ERROR_SWAPERROR
  10339.  
  10340.  
  10341.   32901   ERROR_LDRERROR
  10342.  
  10343.  
  10344.   32902   ERROR_NOMEMORY
  10345.  
  10346.  
  10347.   32903   ERROR_NOACCESS
  10348.  
  10349.  
  10350.   32904   ERROR_NO_DLL_TERM
  10351.  
  10352.  
  10353.   65026   ERROR_CPSIO_CODE_PAGE_INVALID
  10354.  
  10355.  
  10356.   65027   ERROR_CPSIO_NO_SPOOLER
  10357.  
  10358.  
  10359.   65028   ERROR_CPSIO_FONT_ID_INVALID
  10360.  
  10361.  
  10362.   65033   ERROR_CPSIO_INTERNAL_ERROR
  10363.  
  10364.  
  10365.   65034   ERROR_CPSIO_INVALID_PTR_NAME
  10366.  
  10367.  
  10368.   65037   ERROR_CPSIO_NOT_ACTIVE
  10369.  
  10370.  
  10371.   65039   ERROR_CPSIO_PID_FULL
  10372.  
  10373.  
  10374.   65040   ERROR_CPSIO_PID_NOT_FOUND
  10375.  
  10376.  
  10377.   65043   ERROR_CPSIO_READ_CTL_SEQ
  10378.  
  10379.  
  10380.   65045   ERROR_CPSIO_READ_FNT_DEF
  10381.  
  10382.  
  10383.   65047   ERROR_CPSIO_WRITE_ERROR
  10384.  
  10385.  
  10386.   65048   ERROR_CPSIO_WRITE_FULL_ERROR
  10387.  
  10388.  
  10389.   65049   ERROR_CPSIO_WRITE_HANDLE_BAD
  10390.  
  10391.  
  10392.   65074   ERROR_CPSIO_SWIT_LOAD
  10393.  
  10394.  
  10395.   65077   ERROR_CPSIO_INV_COMMAND
  10396.  
  10397.  
  10398.   65078   ERROR_CPSIO_NO_FONT_SWIT
  10399.  
  10400.  
  10401.   65079   ERROR_ENTRY_IS_CALLGATE
  10402.  
  10403.  
  10404. ΓòÉΓòÉΓòÉ 13. Specifications ΓòÉΓòÉΓòÉ
  10405.  
  10406. Specifications covered: 
  10407.  
  10408. Γûá API Calls Made 
  10409.  
  10410. Γûá Memory Usage 
  10411.  
  10412. Γûá IX3 File Format 
  10413.  
  10414. Γûá DBF File Format 
  10415.  
  10416. Γûá DBT File Format 
  10417.  
  10418. Γûá Custom Sort-Compare Function 
  10419.  
  10420. Γûá Custom Build-Key 
  10421.  
  10422. Γûá Custom Expression Parser 
  10423.  
  10424.  
  10425. ΓòÉΓòÉΓòÉ 13.1. OS/2 API Calls Made ΓòÉΓòÉΓòÉ
  10426.  
  10427. The following are the API calls made by Bullet. 
  10428.  
  10429.  DosAllocMem             DosClose                 DosCopy 
  10430.  DosCloseMutexSem        DosCreateDir             DosCreateMutexSem 
  10431.  DosDelete (*)           DosErrClass              DosExitList 
  10432.  DosForceDelete          DosFreeMem               DosGetDateTime 
  10433.  DosMapCase              DosOpen                  DosQueryCollate 
  10434.  DosQueryCp              DosQueryCtryInfo         DosQueryCurrentDisk 
  10435.  DosQueryFSAttach        DosQueryHType            DosQuerySysInfo 
  10436.  DosMove                 DosRead                  DosReleaseMutexSem 
  10437.  DosRequestMutexSem      DosResetBuffer           DosScanEnv 
  10438.  DosSetFileLocks         DosSetFilePtr            DosSetFileSize 
  10439.  DosSetMaxFH             DosSetRelMaxFH           DosWrite 
  10440.  
  10441.  (*) DosForceDelete is used in favor of DosDelete. 
  10442.  
  10443.  
  10444. ΓòÉΓòÉΓòÉ 13.2. Bullet Memory Usage ΓòÉΓòÉΓòÉ
  10445.  
  10446. Memory is committed when allocated, using the PAG_COMMIT and the PAG_WRITE 
  10447. flags.  This is memory allocated by Bullet itself.  Additional memory needs are 
  10448. made by your code, such as parameter pack data, key buffers, and data record 
  10449. buffers. 
  10450.  
  10451. Code 
  10452.  
  10453. Bullet uses 8 pages for code, or less than 32KB. 
  10454.  
  10455. Data 
  10456.  
  10457. Γûá  Shared Data 
  10458.  
  10459. A single page of shared memory is used by all Bullet processes. 
  10460.  
  10461. Γûá  Instance Data 
  10462.  
  10463. One page of private memory is used by each Bullet processes. 
  10464.  
  10465. Γûá  Handle Data 
  10466.  
  10467. One page of private memory is used by each open Bullet index file.  For open 
  10468. data files, one page of private memory is used for files with 121 or fewer 
  10469. fields.  Two pages are used for files with 249 or fewer fields. Thereafter, one 
  10470. page for each additional 128 fields, up to 1024 max fields. 
  10471.  
  10472. For example, if one machine is running 2 Bullet processes, each with 10 open 
  10473. data files with 12 fields each, and 10 index files (one for each data file), 
  10474. its total memory usage is: 
  10475.  
  10476.      Total code is 32KB. 
  10477.      Shared data is 4KB. 
  10478.      Instance data is 2 processes * 4KB, or 8KB (plus INIT_XB use shown 
  10479.       below). 
  10480.      DBF file data is 2 * 10 files * 4KB, or 80KB. 
  10481.      Index file data is 2 * 10 files * 4KB, or 80KB. 
  10482.  
  10483.  Total memory committed by Bullet for the above is 200KB, plus code and data of 
  10484.  your two applications (or your single application, if the same application is 
  10485.  being run twice).  With no files open, for example when starting your program, 
  10486.  only 40KB is committed.  Thereafter, 4KB per open file.  The memory is freed 
  10487.  when the file is closed. 
  10488.  
  10489.  Γûá  Temporary Data 
  10490.  
  10491.  Additional memory is allocated on a temporary basis, where the allocation is 
  10492.  requested on entry to, and is freed upon exiting from, the routine called. 
  10493.  INIT_XB's allocation can be considered permanent since its allocations are not 
  10494.  released until the program has ended or EXIT_XB is issued.  The following are 
  10495.  the routines and the single requested amount: 
  10496.  
  10497.      Routine          Memory Allocated, in KB
  10498.  
  10499.   INIT_XB             8 for 1024 MAX_FILES version; 4KB for 100 and 250 MAX_FILES versions
  10500.   BACKUP_FILE_XB      8
  10501.   CREATE_DATA_XB      4 for 1-121 fields, 8 for 122-249 fields, ...
  10502.   CREATE_INDEX_XB     4
  10503.   PACK_RECORDS_XB     adjustable, 128 default (less if file is smaller)
  10504.   REINDEX_XB          adjustable, 144 default (minimum size is 48KB)
  10505.   UPDATE_XB           varies:      40 + sum of record lengths where AP[].recNo!=0
  10506.  
  10507.  Γûá  Stack Data 
  10508.  
  10509.  Stack requirements are 8KB minimum for Bullet.  No single stack allocation 
  10510.  requests more than 4KB at a time (ie all changes to ESP (the CPU stack 
  10511.  pointer) are less than 4KB at any one time), but some routines nest and 
  10512.  require up to the minimum 8KB in total.  The minimum recommended stack size 
  10513.  for your Bullet application is 16KB.  It's likely that you need to use a much 
  10514.  larger size for your main program's stack use.  If you have any doubt about 
  10515.  stack space, double it, twice even. 
  10516.  
  10517.  
  10518. ΓòÉΓòÉΓòÉ 13.3. IX3 File Format ΓòÉΓòÉΓòÉ
  10519.  
  10520. The IX3 index file is composed of a header followed by node data.  The header 
  10521. layout is detailed below, followed by the node format. 
  10522.  
  10523. Index Header 
  10524.  
  10525. // nnn, where nnn is the offset of that item relative to the start of the file
  10526.  
  10527. CHAR fileID[4];     // 000 file id = '31ch'
  10528. ULONG nodeSize;     // 004 size of a node, in bytes
  10529. ULONG rootNode;     // 008 root node (1-based)
  10530. ULONG noKeys;       // 012 total number of keys
  10531. ULONG availNode;    // 016 next available node (link to, 0 if none, 1-based)
  10532. ULONG freeNode;     // 020 next free node
  10533. ULONG keyLength;    // 024 length of key
  10534. ULONG maxKeys;      // 028 maximum number of keys on a node
  10535. ULONG codePage;     // 032 code page from CreateIndexFile
  10536. ULONG countryCode;  // 036 country code from CreateIndexFile
  10537. ULONG sortFunction; // 040 system (1-9) or custom (10-19)
  10538.                     //     high word has flags: bit0=1 dups allowed
  10539.                     //                          bit1-15 rez
  10540.  
  10541. // Translated key expression as done by Parser during CreateIndex and Reindex.
  10542. // More details on this is in the Custom Expression Parser Specifications.
  10543. // For each key part in KH.expression a 4-byte structure is used in XLATEX:
  10544.  
  10545. typedef struct _XLATEX {
  10546.  CHAR  ftype;   // field type (C,N,L, etc.),if bit7=1 and C then do UPPER key
  10547.  CHAR  length;  // bytes to use starting at offset (never > 64)
  10548.  SHORT offset;  // byte offset into data record that length bytes are to be used
  10549. } XLATEX;
  10550.  
  10551. ULONG xlateCount;         // 044 number of key fields (64/4=16 max fields)
  10552. XLATEX xlateExpression[16]; // 048 key construct info (16 dword's worth)
  10553. CHAR  miscWorkspace[236]; // 112-347 B-tree workspace
  10554. CHAR  expression[160];    // 348 key expression, user (0-Terminated)
  10555. ULONG CTsize;             // 508 size of collate table following
  10556. CHAR  collateTable[256];  // 512 collate table, fill at CreateIndexXB
  10557. CHAR  rez[256];           // 768 to 1023 reserved (header size=1024 bytes)
  10558.  
  10559. Node Data 
  10560.  
  10561. Directly after the header the node data starts.  Each node is either 512, 1024, 
  10562. or 2048 bytes long.  Each node contains a key count, indicating the number of 
  10563. active keys on the node, followed by key data. 
  10564.  
  10565. // nnn, where nnn is the offset of that item relative to the start of the node
  10566.  
  10567. CHAR  keyCount;         // 000 1 to maxKeys (in header above)
  10568. ULONG backNode;         // 001 previous node page, or 0 if this node is a leaf
  10569. XNODE node[maxKeys];    // 005...
  10570.  
  10571. For each key on the node: 
  10572.  
  10573. typedef struct _XNODE {
  10574. CHAR  keyValue[keyLength]; // 005   actual key   (keyLength from header)
  10575. ULONG recordNo;            // 005+keyLength   record number for key
  10576. ULONG fwdNode;             // 005+keyLength+4   next node page, or 0 if leaf
  10577. } XNODE;
  10578.  
  10579. backNode and fwdNode are node numbers.  The first node is 1, and is located 
  10580. directly after the header.  The last node used is at header:freeNode-1.  Each 
  10581. fwdNode of a key is also the next key's backNode.  If the node has had all keys 
  10582. removed, its node number is placed on the top of the header:availNode list, and 
  10583. the first 4 bytes of the node are used as a link to the previous list top. 
  10584.  
  10585.  
  10586. ΓòÉΓòÉΓòÉ 13.4. DBF File Format ΓòÉΓòÉΓòÉ
  10587.  
  10588. The DBF data file is composed of a header, field descriptors, one per field, 
  10589. and the actual record data.  The header layout is detailed below, followed by 
  10590. the field descriptor layout and then the description of the data record. The 
  10591. standard DBF file has a record length limit of 4000 bytes.  Creating record 
  10592. lengths greater than 4000 is allowed in Bullet, but these files may not be 
  10593. recognized by other applications if you do so. 
  10594.  
  10595. DBF Header 
  10596.  
  10597. // nnn, where nnn is the offset of that item relative to the start of the file
  10598.  
  10599. CHAR  fileID;           // 000 file id byte
  10600. CHAR  lastUpdateYR;     // 001 binary year-1900
  10601. CHAR  lastUpdateMO;     // 002 binary month (1-12)
  10602. CHAR  lastUpdateDA;     // 003 binary day (1-31)
  10603. ULONG noRecords;        // 004 total number of records
  10604. SHORT headerLength;     // 008 length of data header
  10605. SHORT recordLength;     // 010 record length
  10606. SHORT nada;             // 012 reserved
  10607. CHAR  xactionFlag;      // 014 flag indicating incomplete dBASE transaction (n/a)
  10608. CHAR  encryptFlag;      // 015 flag indicating encrypted (n/a)
  10609. CHAR  filler[16];       // 016 fill to 32 bytes
  10610.  
  10611. Field Descriptors 
  10612.  
  10613. For each field, a descriptor is stored in the DBF.  The first descriptor starts 
  10614. directly after the header, at file offset 32 (the 33rd byte).  Each descriptor 
  10615. is 32 bytes.  After the last descriptor, a byte with ASCII value 13 (0x0D) is 
  10616. stored.  Following this byte, the record data starts. 
  10617.  
  10618. // nnn, where nnn is offset of item relative to the start of the descriptor
  10619.  
  10620. CHAR  fieldName[11];    // 000 ASCII, UPPER, underscore, zero-filled, (0T)
  10621. CHAR  fieldType;        // 011 UPPER C,N,D,L,M
  10622. ULONG fieldDA;          // 012 not used
  10623. CHAR  fieldLength;      // 016 1-255 bytes, depending on fieldType
  10624. CHAR  fieldDC;          // 017 places right of decimal point
  10625. SHORT altFieldLength;   // 018 alternate field length when fieldLength==0
  10626. CHAR  filler[12];       // 020 not used
  10627.  
  10628. // altFieldLength is proprietary to Bullet, and can be used if Xbase
  10629. // compatibility is not required and fields need to be larger than 255 bytes.
  10630. // To use it, set fieldLength=0 and altFieldLength to > 255 bytes.
  10631.  
  10632. Record Data 
  10633.  
  10634. The DBF data are free-form, fixed-length records.  Each data record starts with 
  10635. a one-byte 'tag' field, which is implicitly defined for all records (hence, it 
  10636. is not a formal field and has no descriptor).  Following the tag field is the 
  10637. first field of the record, and following that field (whose length is described 
  10638. in the field's descriptor) is the next field, and so on.  No separators are 
  10639. used between fields.  After the very last data record in the file, DBF 
  10640. specification dictates that an end of file marker be placed, so at the end of 
  10641. the file is a byte of value ASCII 26 (0x1A). 
  10642.  
  10643. Record layout is as you define in your application.  It must match the layout
  10644. as described in the field descriptors, byte-for-byte.
  10645.  
  10646. Increasing DBF Performance 
  10647.  
  10648. Records are stored in the order they were written.  To improve performance, 
  10649. especially indexed-sequential access, the data file may be sorted, or 
  10650. clustered, by reading each record in primary key order, then writing that 
  10651. record to a new DBF data file.  Repeat for each record.  After all records have 
  10652. been written, reindex the newly created DBF data file (and all related index 
  10653. files).  After this, delete the old files (data and index), and rename the new 
  10654. ones to the filenames required.  This technique maximizes cache efficiency, and 
  10655. can easily offer 10x performance increase in access speed. 
  10656.  
  10657.  
  10658. ΓòÉΓòÉΓòÉ 13.5. DBT File Format ΓòÉΓòÉΓòÉ
  10659.  
  10660. The DBT memo file is composed of a header followed by memo data, stored in one 
  10661. or more blocks.  The header layout is detailed below, followed by the memo 
  10662. record. 
  10663.  
  10664. DBT Header 
  10665.  
  10666. // nnn, where nnn is the offset of that item relative to the start of the file
  10667.  
  10668. ULONG memoAvailBlock;   // 000 next available block (header is block 0)
  10669. ULONG memoRez;          // 004 not used
  10670. CHAR  memoFilename[8];  // 008 filename proper (first 8 of filename proper)
  10671. ULONG memoRez2;         // 016 not used (apparently)
  10672. ULONG memoBlockSize;    // 020 block size, must be at least 24
  10673.  
  10674. // the rest of the header block (to block size bytes) is unused
  10675.  
  10676. Memo Record 
  10677.  
  10678. // nnn, where nnn is offset of item relative to the start of the memo record
  10679.  
  10680. ULONG memoAvail;        // 000 next available link
  10681. ULONG memoSize;         // 004 size of data (including this and memoAvail)
  10682. CHAR  memoData;         // 008 for as many bytes as memoSize, less 8
  10683.  
  10684. A memo may use one or more blocks (each block is a fixed size), but allocations 
  10685. are always contiguous.  Unused bytes after the memo data (to the end of the 
  10686. last block allocated to that memo record) are undefined.  memoAvail is 0x8FFFF 
  10687. for all active memo records.  For deleted memo records, memoAvail is used as a 
  10688. link in the memoAvail list.  memoSize is the total bytes used by the memo, 
  10689. including the memoAvail and memoSize data, so it is the size of the real data + 
  10690. 8 bytes. 
  10691.  
  10692. Removing Memo Records 
  10693.  
  10694. A similar technique to that above could be used to remove memo records from a 
  10695. DBT.  Instead of using PACK_RECORDS_XB, read each DBF record in sequence, and 
  10696. if not to be deleted, write that record to a new DBF data file and its memo 
  10697. records to a new DBT memo file.  If the record read is to be deleted, skip it 
  10698. (and its memo record(s)) and continue with the next DBF data record.  Repeat 
  10699. while more records. Delete or archive the old DBF/DBT pair, and use the new 
  10700. files in their place.  Reindex.  Also see compact.c on the distribution disk 
  10701. for an example technique of compacting a database. 
  10702.  
  10703.  
  10704. ΓòÉΓòÉΓòÉ 13.6. Custom Sort-Compare Function ΓòÉΓòÉΓòÉ
  10705.  
  10706. Bullet provides 10 custom sort-compare functions, in addition to the 6 
  10707. intrinsic sort-compare functions (ASCII, NLS, and the four integer compares). 
  10708. The custom function you supply is not actually a sort function, as the name 
  10709. implies, but a compare function.  Basically, two strings are supplied and your 
  10710. function determines string1's relation to string2 (<, >, or ==). 
  10711.  
  10712. The strings supplied (via pointers) are not C strings, and they are not 
  10713. (necessarily) 0-terminated.  A count value is passed, indicating the number of 
  10714. bytes to compare.  The handle of the index file for which this compare is being 
  10715. done is also supplied, so that you can interrogate the index file state 
  10716. (STAT_INDEX_XB) for any additional information required. 
  10717.  
  10718. In addition to the compare function this routine performs, a special-case call 
  10719. is made to this routine requesting a pointer to a string of HIGH-VALUES for 
  10720. this sort compare.  The pointer must be to a static memory area that exists for 
  10721. as long as the index file is open, and must be at least as long as count.  This 
  10722. special-case call is indicated by both string pointers==NULL. 
  10723.  
  10724. To use a custom sort-compare function, first use SET_SYSVARS_XB to assign the 
  10725. custom sort ID (10 to 19) with the function's address pointer.  Once assigned, 
  10726. an index file may be created with its CIP.sortFunction set to the sort ID 
  10727. (10-19).  Also, any previously created index file with a custom sort ID may now 
  10728. be opened (but only after you used SET_SYSVARS_XB to assign the sort-compare 
  10729. function pointer).  During the index file create, the sort ID you specified for 
  10730. the create is stored in the index file.  When that index file is later opened, 
  10731. that same sort ID is used, and so requires that the custom sort-compare 
  10732. function already be assigned (with SET_SYSVARS_XB) before opening the index 
  10733. file.  This means that you need to be consistent in your custom sort ID 
  10734. numbering, since each index created forever uses that sort ID you specified. 
  10735.  
  10736. It's simple to create a custom sort-compare function.  The calling convention 
  10737. is APIENTRY (DOSX32 = __cdecl, OS/2= _syscall, Win32=_stdcall), and the 
  10738. parameters are passed to your function on the stack (by Bullet).  A sample 
  10739. prototype for a custom sort-compare function follows: 
  10740.  
  10741. LONG APIENTRY YourCustomSort10(PVOID str1,
  10742.                                PVOID str2,
  10743.                                ULONG count,
  10744.                                ULONG handle);
  10745.  
  10746. If the pointers are not NULL, your routine is to compare str1 to str2, for 
  10747. count bytes, and is to return: 
  10748.  
  10749.         -1 if str1 is less than str2
  10750.          0 if str1 is equal to str2
  10751.          1 if str1 is greater than str2
  10752.  
  10753. str is not a C string, but is of type void.  Cast as required,
  10754. depending on the data expected.
  10755.  
  10756. If str1 and str2 are both NULL, your routine must return a pointer to a static 
  10757. object that contains HIGH-VALUES for the object type.  For example, if the 
  10758. sort-compare is for IEEE floating-point, then the function is to return a 
  10759. pointer to a static data area filled with the highest floating-point value. 
  10760. Depending on your sort-compare routine's functionality, you may need just a 
  10761. single high-value, or multiple high-values, one after the other (e.g., if you 
  10762. are supporting compound key values for binary keys).  The count parameter 
  10763. indicates the total bytes needed, so divide by the object size to get the 
  10764. number of objects required.  Be aware that the object size (in count) is +2 
  10765. bytes for the enumerator if DUPS_ALLOWED was specified when the index file was 
  10766. created.  This high-values object is used in the REINDEX_XB routine, and also 
  10767. the LAST_KEY_XB and GET_LAST_XB routines. 
  10768.  
  10769.  
  10770. ΓòÉΓòÉΓòÉ 13.7. Custom Build-Key ΓòÉΓòÉΓòÉ
  10771.  
  10772. Bullet provides an internal build-key routine that constructs the key from the 
  10773. data record supplied.  The internal routine can be overloaded by your custom 
  10774. build-key routine if you need additional functionality.  It may be used in 
  10775. conjunction with a custom sort-compare function, or an intrinsic Bullet 
  10776. sort-compare. 
  10777.  
  10778. Developing a custom build-key routine requires delving into the internal Bullet 
  10779. data structures.  It is more complicated than a custom sort-compare function, 
  10780. but not really any more complex.  The handle of the index file is passed, and 
  10781. using this, STAT_INDEX_XB is called to get the SIP.herePtr pointer.  This is 
  10782. the pointer to the internal Bullet data structure for this index file.  What 
  10783. needs to be accessed in this structure is the translated key expression.  From 
  10784. this, you have the starting offset in the data record, and the byte count to 
  10785. use, for each key component (up to 16 components per key).  The offset value as 
  10786. stored in the XLATEX structure does not include the tag field byte.  Therefore, 
  10787. to locate to the correct offset, add 1 to the value in offset.  For example, 
  10788. XLATEX.offset=0 means to use the first field, which is the first byte after the 
  10789. tag field byte, but the physical offset, as referenced to recPtr, is not at 
  10790. offset=0, but is at offset=1. 
  10791.  
  10792. This translated key expression structure is: 
  10793.  
  10794. // (This is an excerpt from the IX3 header format)
  10795.  
  10796. // Translated key expression as done by Parser during CreateIndex and Reindex.
  10797. // More details on this is in the Custom Expression Parser Specifications.
  10798. // For each key part in KH.expression a 4-byte structure is used:
  10799.  
  10800. typedef struct _XLATEX {
  10801.  CHAR  ftype;   // field type (C,N,L, etc.),if bit7=1 and C then do UPPER key
  10802.  CHAR  length;  // bytes to use starting at offset (never > 64)
  10803.  SHORT offset;  // byte offset into data record that length bytes are to be used
  10804. } XLATEX;       // (note that offset does not count tag field byte)
  10805.  
  10806. ULONG xlateCount;           // 044 number of key fields (64/4=16 max fields)
  10807. XLATEX xlateExpression[16]; // 048 key construct info (16 dword's worth)
  10808.  
  10809. xlateExpression is at offset +48 relative the IX3 index header.  However, 
  10810. SIP.herePtr points to -384 relative the IX3 index header start.  Therefore, to 
  10811. locate to xlateExpression, you must add 384 to 48.  This means that 
  10812. xlateExpression[0].ftype is located at SIP.herePtr+432.  The number of valid 
  10813. key components in xlateExpression is stored in xlateCount (at SIP.herePtr+428). 
  10814.  
  10815. The calling convention for your custom build-key function is APIENTRY (or 
  10816. _System, or __syscall for some compilers), and the parameters are passed to 
  10817. your function on the stack (by Bullet).  A sample prototype for a build-key 
  10818. function follows: 
  10819.  
  10820. ULONG APIENTRY YourBuildKey(ULONG handle,
  10821.                             PVOID recordPtr,
  10822.                             PVOID keyPtr,
  10823.                             PULONG keyLenPtr
  10824.                             PULONG sortFuncPtr);
  10825.  
  10826. Using the data from xlateExpression, you are to build a key from the data 
  10827. record located at the passed pointer, recordPtr, and are store the built key in 
  10828. the buffer located at keyPtr.  For each key component, you copy from the data 
  10829. record xlateExpression[].length bytes starting at xlateExpression[].offset+1 
  10830. (given the 1-byte tag field which is not accounted for otherwise), and build 
  10831. other key components after previously build parts.  If the index file allows 
  10832. duplicate keys (DUPS_ALLOWED is flagged in SIP.sortFunction), then append an 
  10833. enumerator to the end of the key proper.  The handle of the index file is 
  10834. passed, which is used when calling STAT_INDEX_XB (to get SIP.herePtr).  The 
  10835. return is 0 if successful, or an appropriate Bullet error code (EXB_) should be 
  10836. used.  In addition, the key length is placed in the ULONG data pointed to by 
  10837. keyLenPtr (SIP.keyLength may be used), and the sort-compare function is placed 
  10838. in the ULONG data pointed to by sortFuncPtr (SIP.sortFunction may be used). 
  10839.  
  10840. The routine is also to check if the tag field of the data record matches the 
  10841. skip-tag value, as set by SET_SYSVARS_XB.  If the tag field matches, 
  10842. WRN_SKIP_KEY is to be returned as the 'error' code.  The key is built 
  10843. regardless of a match. 
  10844.  
  10845.  
  10846. ΓòÉΓòÉΓòÉ 13.8. Custom Expression Parser ΓòÉΓòÉΓòÉ
  10847.  
  10848. Bullet provides an internal key expression parser routine that constructs the 
  10849. translated key expression stored in the index file header.  The internal 
  10850. routine can be overloaded by your custom expression parser routine if you need 
  10851. additional functionality.  It may be used in conjunction with a custom 
  10852. sort-compare function, with a custom build-key routine, or with an intrinsic 
  10853. Bullet sort-compare. 
  10854.  
  10855. Developing a custom expression parser routine requires delving into the 
  10856. internal Bullet data structures.  It is more complicated than a custom 
  10857. sort-compare function, and it is also much more complex.  Unlike the custom 
  10858. sort-compare and build-key functions, no handle is passed to the parser.  This 
  10859. is because, rather than using the handle to get the SIP.herePtr, this pointer 
  10860. is passed directly to this routine.  This is the pointer to the internal Bullet 
  10861. data structure for this index file.  What needs to be accessed in this 
  10862. structure is the translated key expression location, as well as the text 
  10863. version of the key expression, as supplied by the programmer/user.  To the 
  10864. XLATEX data you place the starting offset in the data record, and the byte 
  10865. count to use, for each key component you parse from the key expression (up to 
  10866. 16 components per key).  The offset value as stored in the XLATEX structure 
  10867. does not include the tag field byte.  Therefore, the correct offset to store is 
  10868. the physical offset within the record, minus 1.  For example, XLATEX.offset=0 
  10869. should be used for the offset of the first field, which is the first byte after 
  10870. the tag field byte.  For each component parsed, an XLATEX data structure is 
  10871. added to the xlateExpression data area (up to 16).  Unused XLATEX components 
  10872. must be set to 0.  When all components have been stored, the xlateCount value 
  10873. is set to the number of key components stored. 
  10874.  
  10875. DHDptr is the data header pointer.  It is -352 bytes relative the DBF data 
  10876. header.  However, rather than using absolute addressing to locate field 
  10877. descriptor data (needed for parsing), it's recommended that the DBF handle be 
  10878. obtained from the KHptr structure.  Since no file handles are passed, you must 
  10879. read the xbLink handle value from the index file header.  The xbLink handle is 
  10880. stored at KHptr+12.  With this handle, you call the GET_DESCRIPTOR_XB routine 
  10881. to obtain field descriptor info for each field. 
  10882.  
  10883. This translated key expression structure, and text expression location, is at: 
  10884.  
  10885. // (This is an excerpt from the IX3 header format)
  10886.  
  10887. // Translated key expression as done by Parser during CreateIndex and Reindex.
  10888. // For each key part in KH.expression a 4-byte structure is used:
  10889.  
  10890. typedef struct _XLATEX {
  10891.  CHAR  ftype;   // field type (C,N,L, etc.),if bit7=1 and C then do UPPER key
  10892.  CHAR  length;  // bytes to use starting at offset (never > 64)
  10893.  SHORT offset;  // byte offset into data record that length bytes are to be used
  10894. } XLATEX;       // (note that offset does not count tag field byte)
  10895.  
  10896. ULONG xlateCount;           // 044 number of key fields (64/4=16 max fields)
  10897. XLATEX xlateExpression[16]; // 048 key construct info (16 dword's worth)
  10898.       :                     // 112-347   :
  10899. CHAR  expression[160];      // 348 key expression, user (0-Terminated)
  10900.  
  10901. xlateExpression is at offset +48 relative the IX3 index header.  However, 
  10902. KHptr, passed to this routine, points to -384 relative the IX3 index header 
  10903. start.  Therefore, to locate to xlateExpression, you must add 384 to 48.  This 
  10904. means that xlateExpression[0].ftype is located at KHptr+432.  The number of 
  10905. valid key components in xlateExpression is stored in xlateCount (at KHptr+428). 
  10906. To text key expression string, which you are to parse, is located at KHptr+732. 
  10907. This is identical to the expression passed during CREATE_INDEX_XB (and it is 
  10908. CREATE_INDEX_XB that calls this parser routine). 
  10909.  
  10910. The calling convention for your custom key expression parser function is 
  10911. APIENTRY (or _System, or __syscall for some compilers), and the parameters are 
  10912. passed to your function on the stack (by Bullet).  A sample prototype for a 
  10913. build-key function follows: 
  10914.  
  10915. ULONG APIENTRY YourKeyExpressionParser(PVOID DHDptr,
  10916.                                        PVOID KHptr,
  10917.                                        PULONG keyLenPtr);
  10918.  
  10919. You are to parse the text key expression at KHptr+732 and store the key 
  10920. component XLATEX structure values to the XLATEX structure, one for each key 
  10921. component parsed.  In addition, the key length (the sum of the XLATEX.length 
  10922. fields) is placed in the ULONG data pointed to by keyLenPtr.  The keylength may 
  10923. not exceed 64 bytes.  If DUPS_ALLOWED is flagged, add two to the sum of the 
  10924. XLATEX.length fields for the enumerator word. 
  10925.  
  10926. Note:  The key expression has been mapped to upper-case and 0-filled by the 
  10927. time this routine is called. 
  10928.  
  10929. This is probably the most difficult part of customizing Bullet.  However, the 
  10930. difficulty lies not with Bullet, but how you parse.  The idea is simple -- you 
  10931. are to generate a xlateCount value, and for each key component (ie 
  10932. non-contiguous, non-same-type run in the data record), an XLATEX variable 
  10933. describing the method to build that key component out of the data record (type, 
  10934. length, and starting offset) is stored.  The text key expression is available 
  10935. in the index header, and the destination to write to is there, also.  You do 
  10936. need to read the index header at KHptr+12 (ULONG) to obtain the DBF handle for 
  10937. this index file before you can parse the expression.  This because you need to 
  10938. know about the record field names, types, and lengths before you can parse the 
  10939. key expression.  The matter not covered here is that of parsing the expression, 
  10940. which is left to the programmer.  Any lexical parser algorithm may be used, or 
  10941. you may even do no parsing at all, and simply hard-code values into the XLATEX 
  10942. structures. 
  10943.  
  10944. If you've gotten this far, you may find the following data structures useful. 
  10945. The numbers at // nnn are offsets relative the SIP.herePtr and SDP.herePtr 
  10946. pointers.  For example, at SIP.herePtr+352 is a ULONG of the number of key 
  10947. searches requested.  These could be monitored in a separate thread. 
  10948.  
  10949. Relative SIP.herePtr: 
  10950.  
  10951. ULONG fType;            // 000 bit0=0 for index file, btree
  10952. ULONG flags;            // 004 bit0=1 is dirty
  10953.                         //     bit1=1 full lock (count stored in KH.lockCount)
  10954.                         //     bit2=1 shared lock (if bit1=1)
  10955.                         //     bit3-14 reserved (=0)
  10956.                         //     bit15=1 no coalesce on key delete
  10957.                         // 006 BYTE, progress of reindex (0,1-99)
  10958.                         // 007 BYTE, 0
  10959. PVOID morePtr;          // 008 ptr to additional header info, if ever needed
  10960. ULONG xbLink;           // 012 related XB data file handle
  10961. ULONG asMode;           // 016 access-sharing-cache mode of open
  10962. CHAR  filename[260];    // 020 filename at open (0T)
  10963. ULONG currKeyRecNo;     // 280 current rec number assigned to KH.currKey
  10964. CHAR  currKey[64];      // 284 current key value
  10965. ULONG rez0;             // 348 allow for 0-terminated string
  10966. ULONG searches;         // 352 keys searched for
  10967. ULONG seeks;            // 356 nodes seeked
  10968. ULONG hits;             // 360 seeks satisfied without disk access
  10969. ULONG keysDeleted;      // 364 keys deleted since last zeroed
  10970. ULONG keysStored;       // 368 keys added since last zeroed
  10971. ULONG nodesSplit;       // 372 splits needed on insert since last zeroed
  10972. ULONG nodesMadeAvail;   // 376 nodes made available from deleting keys
  10973. ULONG lockCount;        // 380 active full-lock count
  10974.  
  10975. // the IX3 index header follows at 384+
  10976.  
  10977. Relative SDP.herePtr: 
  10978.  
  10979. ULONG fType;            // 000 bit0=1 for DBF data file, XB
  10980. ULONG flags;            // 004 bit0=1 is dirty
  10981.                         //     bit1=1 full lock
  10982.                         //     bit2=1 shared lock (if bit1=1)
  10983.                         //     bit3-15 reserved (=0)
  10984.                         // 006 BYTE, progress of pack (0,1-99)
  10985.                         // 007 BYTE, 0
  10986. PVOID morePtr;          // 008 ptr to additional header info, if ever needed
  10987. ULONG noFields;         // 012 number of fields in this data file
  10988. ULONG asMode;           // 016 access-sharing-cache mode of open
  10989. CHAR  filename[260];    // 020 filename at open (0T)
  10990. ULONG lockCount;        // 280 only when dec'ed to 0 do full unlock
  10991. ULONG memoAvailBlock;   // 284 next available block (header is block 0)
  10992. ULONG memoUnk1;         // 288 not used
  10993. CHAR  memoFilename[8];  // 292 filename proper (first 8 of filename proper)
  10994. ULONG memoUnk2;         // 300 not used (apparently)
  10995. ULONG memoBlockSize;    // 304 block size, must be at least 24 to cover header!
  10996. ULONG memoHandle;       // 308 handle of open memo file
  10997. ULONG memoFlags;        // 312 bit0=1 is dirty
  10998. ULONG memoLastNo;       // 316 last accessed memo number (if not 0)
  10999. ULONG memoLastLink;     // 320 link data for last accessed memo
  11000. ULONG memoLastSize;     // 324 size of last accessed memo (in bytes, w/OH)
  11001. ULONG align32[6];       // 328 (align to even32)
  11002.  
  11003. // the DBF data header follows at +352
  11004.  
  11005.  
  11006. ΓòÉΓòÉΓòÉ 14. Bullet Is... ΓòÉΓòÉΓòÉ
  11007.  
  11008. Bullet is a thread-safe, multi-process capable database engine toolkit for 
  11009. OS/2, DOSX32, and Win32.  It provides pre-built and tested access methods to 
  11010. data and index files for application programmers.  It is not an end-user 
  11011. Database Management System (DBMS), but it is a tool that could be used to 
  11012. develop one.  Bullet is compact, efficient, and very fast.  It can be 
  11013. configured to use custom key-build, sort-compare functions, and expression 
  11014. parser routines to extend the built-in functionality, and even 
  11015. programmer-supplied OS API calls to replace the internal ones. 
  11016.  
  11017. The standard data format is DBF (dBASE 3+ and later).  The supported memo 
  11018. format is DBT (dBASE 4 and later).  Index-only support can be enabled and with 
  11019. this any data file format may be used (the data maintained by the programmer 
  11020. then).  Also, the DBF standard may be extended by using binary field values and 
  11021. fields larger than 255 bytes.  Index files are NLS-compatible and use an 
  11022. efficient b-tree structure.  Files may be any size supported by the OS, up to 
  11023. 4GB.  Up to 1024 files may be opened and in use by any one process, with any 
  11024. number of processes active. 
  11025.  
  11026. The Bullet API consists of a wide assortment of routines, from low-level OS 
  11027. calls to high-level transaction-list routines that can process hundreds of 
  11028. files per transaction, with roll-back on error.  Network support is included, 
  11029. and makes use of operating system features such as atomic re-locking, and 
  11030. shared locks that allow other processes read-access to region-locked files. 
  11031.  
  11032. Bullet is simple to use, and may easily be modified by using function wrappers 
  11033. around groups of related Bullet routines.  If you don't like working with the 
  11034. parameter packs, use a wrapper and call as you like.  Bullet works the way you 
  11035. are used to working. 
  11036.  
  11037. This online manual is a complete introduction and programmer reference for 
  11038. Bullet.  Sample code is included, with more still on disk. 
  11039.  
  11040.  
  11041. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11042.  
  11043. A foreign key is a column value in one table used as a primary key in a second 
  11044. table.  For example, if one table has two fields:  employee name (primary key) 
  11045. and department code, and a second table has two fields:  department code 
  11046. (primary key) and department name, then department code in the first table is 
  11047. considered a foreign key, since it may be used as the primary key value when 
  11048. searching the second table.  Joins and views make use of foreign keys. 
  11049.  
  11050.  
  11051. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11052.  
  11053. Null pack
  11054.  
  11055.  
  11056. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11057.  
  11058. typedef struct _ACCESSPACK {
  11059. ULONG func;
  11060. ULONG stat;
  11061. ULONG handle;         /* I, handle of Bullet file to access */
  11062. LONG  recNo;          /* IO, record number */
  11063. PVOID recPtr;         /* I, programmer's record buffer */
  11064. PVOID keyPtr;         /* I, programmer's key buffer */
  11065. PVOID nextPtr;        /* I, NULL if not xaction, else next AP in list */
  11066. } ACCESSPACK; /* AP */
  11067. typedef ACCESSPACK *PACCESSPACK;
  11068.  
  11069.  
  11070. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11071.  
  11072. typedef struct _CALLBACKPACK {
  11073. ULONG sizeIs;         /* structure size (current 16 bytes) */
  11074. ULONG callMode;       /* 0=from reindex; 1=from DBF pack */
  11075. ULONG handle;         /* file handle */
  11076. ULONG data1;          /* for callMode=0/1: progress percent (1-99,0) */
  11077. } CALLBACKPACK; /* CBP */
  11078. typedef CALLBACKPACK *PCALLBACKPACK;
  11079.  
  11080.  
  11081. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11082.  
  11083. typedef struct _COPYPACK {
  11084. ULONG func;
  11085. ULONG stat;
  11086. ULONG handle;         /* I, handle of Bullet file to copy */
  11087. PSZ   filenamePtr;    /* I, filename to use (drv:path must exist if used) */
  11088. } COPYPACK; /* CP */
  11089. typedef COPYPACK *PCOPYPACK;
  11090.  
  11091.  
  11092. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11093.  
  11094. typedef struct _CREATEDATAPACK {
  11095. ULONG func;
  11096. ULONG stat;
  11097. PSZ   filenamePtr;    /* I, filename to use */
  11098. ULONG noFields;       /* I, 1 to 254 */
  11099. PFIELDDESCTYPE fieldListPtr;   /* I, descriptor list, 1 per field */
  11100. ULONG fileID;         /* I, 0x03 for std DBF, 0x8B for DBF+DBT */
  11101. } CREATEDATAPACK; /* CDP */
  11102. typedef CREATEDATAPACK *PCREATEDATAPACK;
  11103.  
  11104.  
  11105. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11106.  
  11107. typedef struct _CREATEINDEXPACK {
  11108. ULONG func;
  11109. ULONG stat;
  11110. PSZ   filenamePtr;    /* I, filename to use */
  11111. PSZ   keyExpPtr;      /* I, e.g., "SUBSTR(LNAME,1,4)+SSN" */
  11112. LONG  xbLink;         /* I, opened data file handle this indexes */
  11113. ULONG sortFunction;   /* I, 1-9 system, 10-19 custom */
  11114. ULONG codePage;       /* I, 0=use process default */
  11115. ULONG countryCode;    /* I, 0=use process default */
  11116. PVOID collatePtr;     /* I, NULL=use cc/cp else use passed table for sort */
  11117. ULONG nodeSize;       /* I, 512, 1024, or 2048 */
  11118. } CREATEINDEXPACK; /* CIP */
  11119. typedef CREATEINDEXPACK *PCREATEINDEXPACK;
  11120.  
  11121.  
  11122. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11123.  
  11124. typedef struct _FIELDDESCTYPE {
  11125. BYTE  fieldName[11];  /* IO, upper A-Z and _; 1-10 chars, 0-filled, 0-term */
  11126. BYTE  fieldType;      /* IO, C,D,L,N, or M */
  11127. LONG  fieldDA;        /* x, offset within record (run-time storage option) */
  11128. BYTE  fieldLen;       /* IO, C=1-255,D=8,L=1,N=1-19,M=10 */
  11129. BYTE  fieldDC;        /* IO, fieldType=N then 0-15 else 0 */
  11130. USHORT altFieldLength;/* IO, 0 */
  11131. BYTE  filler[12];     /* I, 0 */
  11132. } FIELDDESCTYPE; /* nested in DESCRIPTORPACK */
  11133. typedef FIELDDESCTYPE *PFIELDDESCTYPE;
  11134.  
  11135.  
  11136. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11137.  
  11138. typedef struct _DESCRIPTORPACK {
  11139. ULONG func;
  11140. ULONG stat;
  11141. ULONG handle;         /* I, handle of DBF file */
  11142. ULONG fieldNumber;    /* IO, first field is 1 */
  11143. ULONG fieldOffset;    /* O, offset of field within record (delete tag=offset 0) */
  11144. FIELDDESCTYPE FD;  /* IO FD.fieldName, O rest of FD */
  11145. } DESCRIPTORPACK; /* DP */
  11146. typedef DESCRIPTORPACK *PDESCRIPTORPACK;
  11147. };
  11148.  
  11149.  
  11150. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11151.  
  11152. typedef struct _DOSFILEPACK {
  11153. ULONG func;
  11154. ULONG stat;
  11155. PSZ   filenamePtr;    /* I, filename to use */
  11156. ULONG handle;         /* IO, handle of open file */
  11157. ULONG asMode;         /* I, access-sharing-cache mode */
  11158. ULONG bytes;          /* IO, bytes to read, write, length of */
  11159. LONG  seekTo;         /* IO, seek to offset, current offset */
  11160. ULONG method;         /* I, seek method (0=start of file, 1=current, 2=end) */
  11161. PVOID bufferPtr;      /* I, buffer to read into or write from */
  11162. ULONG attr;           /* I, attribute to create file with */
  11163. PSZ   newNamePtr;     /* I, name to use on rename */
  11164. } DOSFILEPACK; /* DFP */
  11165. typedef DOSFILEPACK *PDOSFILEPACK;
  11166.  
  11167.  
  11168. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11169.  
  11170. typedef struct _EXITPACK {
  11171. ULONG func;
  11172. ULONG stat;
  11173. } EXITPACK; /* EP */
  11174. typedef EXITPACK *PEXITPACK;
  11175.  
  11176.  
  11177. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11178.  
  11179. typedef struct _HANDLEPACK {
  11180. ULONG func;
  11181. ULONG stat;
  11182. ULONG handle;         /* I, handle of Bullet file */
  11183. } HANDLEPACK; /* HP */
  11184. typedef HANDLEPACK *PHANDLEPACK;
  11185.  
  11186.  
  11187. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11188.  
  11189. typedef struct _INITPACK {
  11190. ULONG func;
  11191. ULONG stat;
  11192. ULONG JFTsize;        /* I, max opened files (20-1024+) */
  11193. ULONG versionDOS;     /* O, e.g., 230 for 2.30 */
  11194. ULONG versionBullet;  /* O, e.g., 2019 for 2.019 */
  11195. ULONG versionOS;      /* O, e.g., 4=OS/2 32-bit */
  11196. PVOID exitPtr;        /* O, function pointer to EXIT_XB routine */
  11197. } INITPACK; /* IP */
  11198. typedef INITPACK *PINITPACK;
  11199.  
  11200.  
  11201. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11202.  
  11203. typedef struct _LOCKPACK {
  11204. ULONG func;
  11205. ULONG stat;
  11206. ULONG handle;         /* I, handle of Bullet file to lock */
  11207. ULONG xlMode;         /* I, index lock mode (0=exclusive, 1=shared) */
  11208. ULONG dlMode;         /* I, data lock mode (0=exclusive, 1=shared) */
  11209. LONG  recStart;       /* I, if data, first record # to lock, or 0 for all */
  11210. ULONG recCount;       /* I, if data and recStart!=0, # records to lock */
  11211. PVOID nextPtr;        /* I, NULL if not xaction, else next LP in list */
  11212. } LOCKPACK; /* LP */
  11213. typedef LOCKPACK *PLOCKPACK;
  11214.  
  11215.  
  11216. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11217.  
  11218. typedef struct _MEMODATAPACK {
  11219. ULONG func;
  11220. ULONG stat;
  11221. ULONG dbfHandle;      /* I, handle of DBF file to which this memo file belongs */
  11222. ULONG memoBypass;     /* I, memo bypass function to do, if any */
  11223. PVOID memoPtr;        /* I, ptr to memo record buffer */
  11224. ULONG memoNo;         /* IO, memo record number (aka block number) */
  11225. ULONG memoOffset;     /* I, position within record to start read/update */
  11226. ULONG memoBytes;      /* IO, number of bytes to read/update */
  11227. } MEMODATAPACK; /* MDP */
  11228. typedef MEMODATAPACK *PMEMODATAPACK;
  11229.  
  11230.  
  11231. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11232.  
  11233. typedef struct _MEMORYPACK {
  11234. ULONG func;
  11235. ULONG stat;
  11236. ULONG memory;         /* O, not used in OS/2 */
  11237. } MEMORYPACK; /* MP */
  11238. typedef MEMORYPACK *PMEMORYPACK;
  11239.  
  11240.  
  11241. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11242.  
  11243. typedef struct _OPENPACK {
  11244. ULONG func;
  11245. ULONG stat;
  11246. ULONG handle;         /* O, handle of file opened */
  11247. PSZ   filenamePtr;    /* I, Bullet file to open */
  11248. ULONG asMode;         /* I, access-sharing-cache mode */
  11249. LONG  xbLink;         /* I, if index open, xbLink=handle of its opened DBF */
  11250. } OPENPACK; /* OP */
  11251. typedef OPENPACK *POPENPACK;
  11252.  
  11253.  
  11254. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11255.  
  11256. typedef struct _QUERYSETPACK {
  11257. ULONG func;
  11258. ULONG stat;
  11259. ULONG item;           /* I, Bullet sysvar item to get/set */
  11260. ULONG itemValue;      /* IO, current/new value */
  11261. } QUERYSETPACK; /* QSP */
  11262. typedef QUERYSETPACK *PQUERYSETPACK;
  11263.  
  11264.  
  11265. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11266.  
  11267. typedef struct _REMOTEPACK {
  11268. ULONG func;
  11269. ULONG stat;
  11270. ULONG handle;         /* I, handle of file, or if 0, use RP.drive */
  11271. ULONG drive;          /* I, drive (1=A,2=B,3=C,...0=current) to check */
  11272. ULONG isRemote;       /* O, =1 of handle/drive is remote, =0 if local */
  11273. ULONG flags;          /* O, 0 */
  11274. ULONG isShare;        /* O, 1 */
  11275. } REMOTEPACK; /* RP */
  11276. typedef REMOTEPACK *PREMOTEPACK;
  11277.  
  11278.  
  11279. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11280.  
  11281. struct StatDataPack {
  11282. typedef struct _STATDATAPACK {
  11283. ULONG func;
  11284. ULONG stat;
  11285. ULONG handle;         /* I, handle to check */
  11286. ULONG fileType;       /* O, bit0=1 data file */
  11287. ULONG flags;          /* O, bit0=1 dirty, bit1=1 full-lock, bit2=1 shared */
  11288. ULONG progress;       /* O, 0,1-99% pack progress */
  11289. PVOID morePtr;        /* O, 0 */
  11290. ULONG fields;         /* O, fields per record */
  11291. ULONG asMode;         /* O, access-sharing-cache mode */
  11292. PSZ   filenamePtr;    /* O, filename used in open */
  11293. ULONG fileID;         /* O, first byte of DBF file */
  11294. ULONG lastUpdate;     /* O, high word=year,low byte=day, high byte=month */
  11295. ULONG records;        /* O, data records (including "deleted") */
  11296. ULONG recordLength;   /* O, record length */
  11297. ULONG xactionFlag;    /* O, 0 */
  11298. ULONG encryptFlag;    /* O, 0 */
  11299. PVOID herePtr;        /* O, this file's control address */
  11300. ULONG memoHandle;     /* O, handle of open memo file (0 if none) */
  11301. ULONG memoBlockSize;  /* O, memo file block size */
  11302. ULONG memoFlags;      /* O, bit0=1 dirty */
  11303. ULONG memoLastRecord; /* O, last accessed memo record (0 if none) */
  11304. ULONG memoLastSize;   /* O, size of last accessed memo record (in bytes, +8) */
  11305. ULONG lockCount;      /* O, number of full-locks in force */
  11306. } STATDATAPACK; /* SDP */
  11307. typedef STATDATAPACK *PSTATDATAPACK;
  11308.  
  11309.  
  11310. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11311.  
  11312. typedef struct _STATHANDLEPACK {
  11313. ULONG func;
  11314. ULONG stat;
  11315. ULONG handle;         /* I, handle to check */
  11316. LONG  ID;             /* O, bit0=1 data file, bit0=1 index file */
  11317. } STATHANDLEPACK; /* SHP */
  11318. typedef STATHANDLEPACK *PSTATHANDLEPACK;
  11319.  
  11320.  
  11321. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11322.  
  11323. typedef struct _STATINDEXPACK {
  11324. ULONG func;
  11325. ULONG stat;
  11326. ULONG handle;         /* I, handle to check */
  11327. ULONG fileType;       /* O, bit0=0 index file */
  11328. ULONG flags;          /* O, bit0=1 dirty, bit1=1 full-lock, bit2=1 shared */
  11329. ULONG progress;       /* O, 0,1-99% reindex progress */
  11330. PVOID morePtr;        /* O, 0 */
  11331. ULONG xbLink;         /* O, XB file link handle */
  11332. ULONG asMode;         /* O, access-sharing-cache mode */
  11333. PSZ   filenamePtr;    /* O, pointer to filename used in open */
  11334. ULONG fileID;         /* O, "31ch" */
  11335. PSZ   keyExpPtr;      /* O, pointer to key expression */
  11336. ULONG keys;           /* O, keys in file */
  11337. ULONG keyLength;      /* O, key length */
  11338. ULONG keyRecNo;       /* O, record number of current key */
  11339. PVOID keyPtr;         /* O, ptr to current key value (valid to keyLength) */
  11340. PVOID herePtr;        /* O, this file's control address */
  11341. ULONG codePage;       /* O, code page at create time */
  11342. ULONG countryCode;    /* O, country code at create time */
  11343. PVOID CTptr;          /* O, collate table ptr, NULL=no collate table present */
  11344. ULONG nodeSize;       /* O, node size */
  11345. ULONG sortFunction;   /* O, sort function ID */
  11346. ULONG lockCount;      /* O, number of full-locks in force */
  11347. } STATINDEXPACK; /* SIP */
  11348. typedef STATINDEXPACK *PSTATINDEXPACK;
  11349.  
  11350.  
  11351. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11352.  
  11353. typedef struct _XERRORPACK {
  11354. ULONG func;
  11355. ULONG stat;           /* I, error to check */
  11356. ULONG errClass;       /* O, class of error */
  11357. ULONG action;         /* O, action recommended for error */
  11358. ULONG location;       /* O, location of error */
  11359. } XERRORPACK; /* XEP */
  11360. typedef XERRORPACK *PXERRORPACK;
  11361.  
  11362.  
  11363. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11364.  
  11365.  Access-Mode (required)
  11366.   READONLY        0x00000000   read-only access open
  11367.   WRITEONLY       0x00000001   write-only access open
  11368.   READWRITE       0x00000002   read/write access open
  11369.  
  11370.  Share-Mode (required)
  11371.   DENYREADWRITE   0x00000010   no other process may share file
  11372.   DENYWRITE       0x00000020   no other process may share file for write
  11373.   DENYREAD        0x00000030   no other process may share file for read
  11374.   DENYNONE        0x00000040   any process may share file
  11375.  
  11376.  Inherit
  11377.   NOINHERIT       0x00000080   child process does not inherit file handles
  11378.  
  11379.  Cache
  11380.   NO_LOCALITY     0x00000000  locality is not known
  11381.   SEQ_LOCALITY    0x00010000  access will be mainly sequential
  11382.   RND_LOCALITY    0x00020000  access will be mainly random
  11383.   MIX_LOCALITY    0x00030000  access will be random with some sequential
  11384.   SKIP_CACHE      0x00100000  I/O is not to go through the cache
  11385.   WRITE_THROUGH   0x00400000  control returns only after disk is written to
  11386.  
  11387. Access- and Share-Mode values not explicitly listed are not valid.  The file 
  11388. access mode is a combination of ACCESS + SHARE + INHERIT + CACHE.  Typical data 
  11389. and index asMode is 0x00000042, though locality may be set accordingly (e.g., 
  11390. 0x00020042 for mostly random access to the file).  All values are mapped to the 
  11391. appropriate flags for the OS being used. 
  11392.  
  11393. The Cache mode options are valid for OPEN_DATA_XB and OPEN_INDEX_XB only; for 
  11394. OPEN_FILE_DOS, the Cache values must be right-shifted by 8.  The 'Skip Cache' 
  11395. and 'Write Through' options are not inherited. 
  11396.  
  11397.  
  11398. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11399.  
  11400. The enumerator is a big-endian 16-bit value that serves to differentiate up to 
  11401. 65536 "identical", non- unique keys.  It is attached to all keys of 
  11402. DUPS_ALLOWED flagged index files (set at CREATE_INDEX_XB), and occupies the 
  11403. last two bytes of the key.  The first key of the type uses \0\0, the second 
  11404. uses \0\1, and so on.  This ordering of bytes is the reverse of x86 Intel 
  11405. words, which uses little-endian format. 
  11406.  
  11407.  
  11408. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  11409.  
  11410. HIGH-VALUES signifies a sort value that is the highest possible (sorts last). 
  11411. HIGH-VALUES for a character key would be 0xFF for each byte, or the 256th byte 
  11412. of the collate-sequence table if an NLS sort (which is 0xFF also).  For 16-bit 
  11413. signed integer values, 0x7FFF is the highest.  And so on...