Category : C Source Code
Archive   : DBTOOL-C.ZIP
Filename : README2

CHANGE SUMMARY: Initial Release Update

THE dBASE TOOLS FOR C: the Programmer's Library, Version 1.4


This README file contains update information about The
Programmer's Library. Check for additional "readme"
files in the various subdirectories on the distribution
disk. The major points are summarized here:

1. New Organization of the Distribution Disk

2. Memory Allocation by DCT1

3. Changes in the syntax if running from within dBASE

4. Notes on Arrays: limits of array sizes and valid array types,
invalid array checking in the COUNT function

5. Accommodations for logical and date arrays are explained.

6. Error messages may be left on the screen by pressing the
ESC key.

7. Some structure changes have been made for those who wish to
add their own C functions.

8. The DUMPARRAY function has been enhanced.

9. The use of character return variables is clarified below.

10. Compiler support is clarified.


These changes are explained more fully in the following paragraphs.
___________________________________________________________________

1. New organization of distribution disk
The files are distributed slightly differently than with previous
versions. The following directory gives an explanation of where to
find particular files:

Directory Contents

\DBDIR All files necessary to use The Programmer's Library
if you do not plan to make your own modifications
using one of the supported C compilers.

\SOURCE All compiler-independent source files.

\LC2 All files required by the Lattice C compiler,
version 2.15, which cannot be recreated from
the files in \SOURCE.

\LC3 All files required by the Lattice C compiler,
version 3.0, which cannot be recreated from
the files in \SOURCE.

\MS All files required by the Microsoft C compiler,
version 3.0, which cannot be recreated from
the files in \SOURCE.

\AZ All files required by the Aztec C Prime compiler,
which cannot be recreated from the files in \SOURCE.


Each of the above directories may also contain a README file,
which contains updates to the documentation and/or other relevant
information.


2. Install the Tools BEFORE running dBASE

DCT1 should be run BEFORE loading dBASE, not from within dBASE
as described in the manual. Further, the amount of memory you
expect to need for arrays should be specified in increments of
1024 bytes immediately after the program name (0 to 120KB). For
example, the following command line:

DCT1 32

installs the Programmer's Library, and allocates approximately
32KB of memory for use with arrays. The actual amount of memory
allocated will depend upon the compiler being used.

If the amount of memory needed is not specified, a default of
16KB is used with both Lattice versions and with the Microsoft
version, 10KB with the Aztec C Prime version. If you do not expect to
use arrays at all, and want to use the minimum amount of memory
required by DCT1, you should specify 0 bytes of array usage as
follows:

DCT1 0

If you specify more than the maximum amount of memory allowed for
arrays, the system will allocate its maximum of 120KB.

What the above means is that the TOTAL amount of storage useable
by arrays is limited to the amount specified on the command line,
or the default values. With the version compiled with the LATTICE
Large Memory Model (\DBDIR\DCT1.EXE on the distribution disk),
a maximum of 120K can be allocated for arrays in this manner.

The actual maximum size for each of your arrays can be computed
by knowing the type of array (Character or Numeric) and the total
amount of storage available. Numeric arrays require 8 bytes of
storage for each value plus approximately 100 bytes overhead per
array. Character arrays require 2 bytes of storage for each value
plus the total of all the lengths of the elements to be stored in
the array (each character element has a null terminator which
also must be counted in its length). Due to alignment restrictions
by the various compilers, these figures may vary by up to 8 bytes
per allocation.

For example, if you specified 32KB, you could have a single
numeric array with approximately 4000 values, or two numeric
arrays each with 2000 values, or a character array big enough to
hold a little less than 100 character variables each 32 bytes
long, or any similar combination. (See note 3 below.)

The function STARRAY now also reports the total amount of
memory remaining available to the array functions (LATTICE
versions only).


3. Change in the syntax if running from within dBASE

If for any reason it becomes desirable to install the Tools
from within dBASE (as earlier versions did), note that
the syntax of the RUN command is slightly different from the
manual. You will need to RUN a separate copy of COMMAND.COM to
invoke DCT1 from within dBASE, as follows:

. RUN COMMAND /C DCT1

where is the amount of memory to reserve for arrays (in
kilobytes). (Be sure that COMSPEC is set to a directory which
contains a valid copy of COMMAND.COM, or that the path includes
such a directory.)

For example,

. RUN COMMAND /C DCT1 16

installs the Programmer's Library and allocates approximately
16KB of memory for use with arrays. The actual amount of memory
allocated will depend upon the compiler being used.

When using the AZTEC compiled version of the Programmer's
Library, it possible to cause memory allocation problems by
attempting to fill arrays beyond the allocated memory space. For
this reason, pay careful attention to only create arrays that
will not overrun the allocated memory. See the table in note 3
below to determine maximum array sizes.


4. The maximum amount of space that can be consumed by a single
array is 64KB. The maximum size of individual arrays is a function
of the type of array and the memory model being used. The following
table summarizes the restrictions on array sizes:

Memory Model Array Type Amount of Memory Max # elements

Large Numeric # elements * 8 8000
Small Numeric # elements * 8 3000
Large Character # elements * 4 16000
Small Character # elements * 2 12000

Note also that the amount of memory consumed by each CRARRAY may
vary from the above rules by 8 or fewer bytes, due to internal
alignment restrictions imposed by the various compilers.

The COUNT function returns -1 if the parameter is an
invalid array.

5. Only array types of N (Numeric) and C (Character) are valid
array types. If arrays of logical or date variables are needed,
we recommend the use of numeric arrays with 0's (for FALSE) and
1's (TRUE) to simulate logical arrays, and the use of character
arrays to hold the character values of dates, which can then be
converted, if necessary, using the dBASE CTOD function.


6. Pressing the ESC key instead of the return key when dct1 displays
a message will leave the message on the screen, rather than
restoring the previous contents of the screen.


7. The structure of the dispatch table, ci_DT, in dctmain.h, has
been modified slightly. The fields F_Type and F_ArgFmt are no
longer used, and have been omitted from the structure definitions
in dctmain.h, and from the initializations in dct1.c.

Strings of the form "this is a test" would be parsed as
"thisisatest". This has been changed, and a new macro, GetString,
has been added, which should be used instead of GetFunc or
GetNext when the parameter could be a multiple-word string.


8. Pressing any key during a DUMPARRAY display will now abort the
display.


9. An anomaly exists when using character return variables. If the
length of the string to be returned is less than the length of a
pre-existing value in the dBASE character variable, the new
value will be 'stuffed' into the first part of the variable, and
old characters past the length of the new string will remain. For
example, if C_C_RESULT contains the string "ABCDEFG", and the
value "XYZ" is obtained from a character array with GETARRAY,
C_C_RESULT will then contain "XYZDEFG". Unfortunately, there is
no way to inform dBASE of the new length of the string from
within DCT1. The proper way to avoid this problem is to be sure
to reinitialize C_C_RESULT each time the length of its value may
vary. For example, if you expect the lengths of the character
elements to vary, the following dBASE code will return the values
of the first 10 elements from the array STRINGS:

i = 0
do while i < 10
c_c_result = space(50)
call cfunc with 'setdvar c'
call cfunc with c_c_result
call cfunc with 'getarray strings, '+str(i)
? i, c_c_result
i = i+1
enddo


10. Revised compiler support
This version of dBASE Tools for C supports the following C
compilers:

Lattice version 3.x (Large model)
Microsoft 4.0 (Large model)
Aztec C Prime (Small model)

The DCT1.EXE file located in the \DBDIR directory on your
distribution disk was created with Lattice version 3.2. If
you want to modify the library or create your own library,
you will need to follow the instructions given in the README
file in the appropriate directory (see change #1 for
information on the organization of the distribution disk.)

Before creating a new DCT1.LIB library file, delete DCT1.LIB
if one was previously created.