The »CB_RandomFiles« Pacckage
=============================

The CB_RandomFiles package provides support for random access files in 
ACE Basic v2.3.7. The package consists of the following files:

CB_RandomFiles.h:    The header file for ACE Basic
CB_RandomFiles.doc:  This file
Salaries.b:          A sample source
Salaries:            A sample program

1. Installation
---------------

The file "CB_RandomFiles.h" has to be copied to the "ACEinclude:" drawer.

Ensure that you have copied the BMAP files supplied with ACE 2.3.7 to the
"ACEbmaps:" drawer. Some library function names have been changed, so the
header file cannot be compiled if you use the old BMAP files.

2. Features
-----------

The package offers the following functions:

  1 OpenRandomFile():    Opens a random access file
  2 CloseRandomFile():   Closes a random access file
  3 CloseAllRandomFiles  Closes all random access files
  4 PutRandomRecord():   Writes a record
  5 GetRandomRecord():   Reads a record
  6 RandomSeek():        Seek to desired record (For internal use only)

All functions use the "dos.library". The OpenRandomFile() function needs a
buffer to enable the ???RandomRecord() functions to read / write a record.
It is recommended to use either a fixed length string or a structure, but
you may also allocate some extra memory for the buffer.

The random access files may have the same numbers as your sequential files.

If an error occurs, the functions generate an error message, and the program
terminates immediately.

3. How to use the package
-------------------------

(1)  Include the file <CB_RandomFiles.h> at the beginning of your program.

(2)  Set up the record structure (see below)

(3)  Open the random access file(s). You are now able to read and write
     records using the functions listed above.

(4)  Close the random access file(s) using the CloseRandomFile() function.
     You may also use CloseAllRandomFiles to close all random access files
     at once.

(5)  Close all libraries using the "LIBRARY CLOSE" command.

4. Setting up the record structure
----------------------------------

(1)  Define a structure like this:

       STRUCT RR
         STRING Name SIZE 40
         SINGLE salary
       END STRUCT

(2)  Declare the record variable.

     The "dos.library" needs chip memory for the record variable. Thus,
     you have to declare the record variable like this:

       DECLARE STRUCT RR *RRecord
       RRecord = ALLOC(SIZEOF(RR), 0)

     Please refer to ACE.doc for details.

5. How to get further information
---------------------------------

(1)  Have a look at the sample program for a tutorial.

(2)  Have a look at the header file for a detailed description of each
     function.

6. Using the package with an ACE 2.0 - 2.3.5
--------------------------------------------

In this case you have to rename the library function names. Perform the
following steps:

(1)  Call a text editor (I suggest to use MEmacs.)

(2)  Load the file "ACEinclude:CB_RandomFiles.h"

(3)  Call the Search/Replace function and replace the following strings:

     Search for:            replace with:

     _Open                  xOpen
     _Close                 xClose
     _Read                  xRead
     _Write                 xWrite

(4)  Save the file and quit the editor.

7. Copyright / Distribution
---------------------------

© 1994 - 1996 by FR-SoftWorks.

The package may be freely distributed. Ensure that you always distribute the
whole package. You are allowed to use package in commercial software, too.

8. How to contact the author
----------------------------

Write bug reports and / or suggestions to:

  Frank Reibold
  Ottberger Weg 13

  31737 Rinteln

  GERMANY

*** Have fun!!! ***