home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / blt2rx_o.zip / bltrexx.doc next >
Text File  |  1996-10-14  |  6KB  |  144 lines
  1.  
  2.  Bullet/REXX v2.105 (Gamma-Omega Release)
  3.  14-Oct-1996
  4.  Copyright (C)1996 Cornel Huth
  5.  All rights reserved
  6.  
  7.  
  8. Contents:
  9.  
  10.   I. Description
  11.  II. Installation
  12. III. Using Bullet/REXX
  13.  IV. Documentation
  14.   V. Quick Start
  15.  
  16.  
  17. I.  Description
  18.  
  19. Bullet/REXX is an interface to the database engine called Bullet.  It closely
  20. follows the compiler-version of Bullet in programming so any Bullet programmer
  21. can be up and using Bullet/REXX in just a few minutes -- as long as it takes
  22. to read this file.  New Bullet programmers will have to learn Bullet first, but
  23. REXX makes this as easy as possible.  If you need a database engine,  you'll
  24. want to check out this product.  One thing Bullet is more than anything else
  25. is fast.  There's nothing faster!  For example, the compiled version of Bullet
  26. is up to 700 times faster than MS's Access DBMS on inserts, and even the REXX
  27. version can reindex files at the rate of 1 million records/minute using a
  28. typical desktop PC.
  29.  
  30.  
  31. II.  Installation
  32.  
  33. Bullet/REXX is a two-DLL package:
  34.  
  35.  o BREXXI2.DLL is the interface between REXX and the
  36.    database engine BREXX2.DLL.
  37.  
  38.  o BREXX2.DLL is the database engine itself, a
  39.    special-version Bullet made exclusively for Bullet/REXX.
  40.  
  41. Place these two DLLs in a directory located in the LIBPATH= config.sys
  42. string.  Once used, these DLLs stay loaded until the window session is
  43. exited.
  44.  
  45.  
  46. III.  Using Bullet/REXX
  47.  
  48. Included with this package are several sample REXX scripts.  These are:
  49.  
  50.  o 01init.cmd   - minimal example to get you familar with the Bullet style
  51.  o 02crd.cmd    - shows how to create data files
  52.  o 03cri.cmd    - shows how to create index files
  53.  o 04midd.cmd   - shows how to use mid-level data manipulation routines
  54.  o 05midm.cmd   - shows how to use mid-level memo manipulation routines
  55.  o 06midk.cmd   - shows how to use mid-level key manipulation routines
  56.  o 07hll.cmd    - shows how to use the HLL, transaction-based routines
  57.  o 08cp.cmd     - shows the CP-level calls supported by Bullet/REXX
  58.  
  59. These examples use a pre-defined data record layout, as defined in each
  60. of the scripts.  Bullet/REXX may also be used to read and manipulate data
  61. files generated by other sources (blt_GetDescriptor() is very useful for
  62. doing this).  For an example of this in C, see the main Bullet documentation.
  63. These sample scripts serve only to illustrate calling Bullet/REXX.
  64.  
  65.  
  66. IV.  Documentation
  67.  
  68. Calls to the database engine in Bullet/REXX are very similar to those in
  69. Bullet.  The documentation in BULLET2.INF is generally language-neutral
  70. (any standard compiler can use the compiler version of Bullet) and that
  71. should be used as a reference.  This section describes the differences
  72. between the compiler Bullet and the REXX Bullet.  See BULLET2.INF for
  73. detailed reference material.
  74.  
  75.  1.  Pointers - Bullet/REXX does not use pointers.  Any place where you pass
  76.      a pointer in Bullet, in Bullet/REXX you either pass a REXX string or
  77.      you pass nothing at all.  For example, instead of passing AP.keyPtr
  78.      pointing to a key buffer to be filled, Bullet/REXX creates a variable
  79.      called blt_AP.keyData and places the key in this for you to interrogate
  80.      after the call returns.  Or, if you are passing data to Bullet, you
  81.      place a key in the named variable for Bullet/REXX to use.
  82.  
  83.      The sample scripts exercise all Bullet/REXX calls, so you should be able
  84.      to learn Bullet/REXX from them by example.
  85.  
  86.  
  87.  2.  The transaction routines:  blt_Insert(), blt_Update(), blt_Reindex(),
  88.      blt_Lock(), blt_Unlock(), and blt_Relock() use slightly different-
  89.      named structure packs.  Bullet/REXX uses blt_TAP.nnn. as the base name
  90.      of transaction-based packs (TLP for locks), with the T added and the
  91.      number of the pack .1. to .256. in the middle.
  92.  
  93.      To manage the linked-list format of Bullet, Bullet/REXX creates vars
  94.      such as blt_TAP.1.stat up to blt_TAP.256.stat (where .stat is the
  95.      member named, the same as in compiled Bullet).  The sample scripts
  96.      show this much better than can be explained in words.
  97.  
  98.  
  99.  3.  The compiler Bullet has redundant shutdowns so that in all but
  100.      the worst of hardware crashes the Bullet data files are properly
  101.      closed.  If Bullet/REXX is run from the command line, it's possible
  102.      a REXX syntax error or other error can cause the interpreter to halt
  103.      all processing of the script, leaving files possibly open and subject
  104.      to corruption (headers not being written).  A simple way to fix this
  105.      is to prefix all REXX scripts with a call to blt_Exit().  This closes
  106.      out any still-running Bullet/REXX process.  Another way is to use the
  107.      registered exit DLL routine, BulletRexxExit(), which is registered with
  108.      RexxRegisterExitDll() during Bullet/REXX initialization.
  109.  
  110.  
  111.  4.  Bullet/REXX has an added pack member in EP:  blt_EP.rxAllocsLeft.  This
  112.      should always return 0 (the net sum of memory allocations and frees).
  113.      Due to the interface requirements, Bullet/REXX makes a substantial number
  114.      of internal OS calls for memory allocation (REXX string copying), and
  115.      this added var is used to verify that no memory leaks exist.
  116.  
  117.  
  118.  5.  Bullet/REXX is limited to a maxiumn of 5 currently open files and 2
  119.      concurrently running Bullet/REXX processes.  The compiler-version
  120.      limits are covered in BULLET2.INF.
  121.  
  122.  
  123.  6.  Bullet/REXX is copyrighted by Cornel Huth, but is available for use,
  124.      by any person, FREE of charge.  The license terms are the same as those
  125.      in the compiler Bullet, covered in BULLET2.INF.  You are granted a
  126.      single license to use Bullet/REXX if and only if you agree to abide by
  127.      the license restrictions listed in the LICENSE AGREEMENT in BULLET2.INF.
  128.      You may distribute the two DLLs listed in the Installation section.  You
  129.      may not redistribute any other files in this package.
  130.  
  131.  
  132. V.  Quick Start
  133.  
  134.     1. Copy the DLLs to a path on LIBPATH
  135.     2. Run 01init.cmd
  136.  
  137.     You may want to redirect output of the sample scripts to a file so
  138.     that you can see what would otherwise scroll off the screen.
  139.  
  140.     If you have any errors and cannot resolve them, contact info@40th.com
  141.     for limited support.  Registered Bullet users only may contact Bullet
  142.     tech support at support@40th.com.  For current versions visit the
  143.     40th Floor BBS at 1-210-684-8065 or visit http://www.40th.com.
  144.