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

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

INCENTIVE DISK

This README contains update information about The Programmer's
Library Incentive Disk. Note that the files on this disk are
supplemental and assume that you still have the previous version
available. Check for additional "readme" files in the
various subdirectories on the distribution disk. The major points
are summarized here:

1. Summary of Additional Functions

2. Documentation Errors

3. New Error Messages

4. Compiler Variations

5. Notes on Recompiling The Programmer's Library

6. Pre-Parsing of CFUNC Parameters

7. Documentation Pages for New Functions

1. Summary of Additional Functions

The following functions have been added:

ARAND Fill an array with random #'s
ASAVE Save the contents of an array to disk
ARESTORE Restore an array from a disk file
CHI A chi-square statistic function
CLRWINDOW Clear a section of the screen
FDUMPARRAY Dump array contents to text file
GETPASS Get a password from the user
GETSIZE Get the size of an array
MEMSTAT Return memory status (Lattice version only)
PEEK Examine a memory location
POKE Place a value in a memory location
PUTWINDOW Put a window around an area of the screen
RNARRAY Rename an array
SETBELL Set a flag to ring the bell on error
SOUND Generate a sound of specific frequency
& duration

Acknowledgement and our thanks are due Frank Fedele of Essential Software,
Inc., who provided the following C routines:

getpass, peekpoke, sound, curback, curfwd, getkey, segmov,
checkkey, savwindo, rstwindo, wnd2disk, wndfrdsk, memtoscr,
scrtomem, getkeycl, gdosint.

The above routines were excerpted from the C Utility Library, published
by Essential Software. Source code is provide for some, but not all,
of the above functions. The entire library of over 300 C functions,
including complete source code, is available from:

Essential Software, Inc.
P. O. Box 1003
Maplewood, NJ 07040
(914) 762-6605

2. DOCUMENTATION NOTE: The parameter for all of the statistics
functions is an optional parameter. The documentation did not
reflect this, but the help lines in this version have been updated.


3. New Error Messages: Two new error messages are possible with
this version:

11 Invalid calling syntax for this function
This error message appears if the syntax used for the
command is incorrect. For example, the order of the
parameters may be incorrect, or required parameters
may be missing.

12 I/O Error
An I/O error has occurred during a disk operation,
probably during an ARESTORE or ASAVE function. This could
be caused by several things. For example, a file might
be write protected or non-existent, there may be no more
room on the disk, etc.


4. Compiler Variations

Beginning with Version 1.4 of dBASE Tools For C: The Programmer's
Library, the following C Compilers are supported:

Lattice Version 3.x
Microsoft Version 4.0
Aztec C Prime (Manx Systems)

The following differences apply to versions of the product produced
with the above compilers:

MEMSTAT works only with the Lattice versions

STARRAY reports available memory only with Lattice versions.

Remember that both Lattice versions and the Microsoft version
use the LARGE memory model, while Aztec C Prime is the small
model.

Array limits in the AZTEC version are different from the other
compiler versions. See the README files for further details.

The program size and array sizes are different for the
various versions. Therefore, the total amount of memory
consumed by each version is different. When the program is
run, the total number of pages being kept resident in
memory appears in parenthesis after the 'Installing ....'
message.

The random number generators vary among the compilers. Note
in particular that the Microsoft rand() function generates
integers, while the other compilers can generate fractions
between 0 and 1. The degree of 'randomness' varies as well,
with the Lattice versions appearing to have the most
sophisticated algorithms.

It is recommended that you examine the conditional
compilation statements (#ifdef and #ifndef) in the source
code to gain a bettter understanding of the differences
among the different compiler versions.

WARNING TO USERS OF AZTEC AND MICROSOFT VERSIONS:
The amount of space to be allocated to arrays (as specified by
default or on the command line) MUST NOT be exceeded by any
function call. Since the program is resident, and has a fixed
amount of space available to it, any requests for memory beyond
that space will interfere with dBASE's use of the memory pool,
and the system will almost certainly lock up or behave in
an unpredictable manner. Typically, the system will behave as
if your request for more space was accepted, and then give
errors, or not work at all, with subsequent function calls.

Pay particular attention when using character arrays: It is
possible to create an empty array of legitimate size and then
overstep the bounds of protected memory when placing values into
it. This can occur because the array is initially sized only with
index pointers for character arrays, but the ultimate size of
the array also includes the size of each character element.

The Lattice versions use the sizmem() function to determine
if requests for allocation would exceed the available memory
pool, and thus are able to accurately report the amount of memory
actually available to the program, which is always checked
against memory requests. An equivalent function is not
provided by the Microsoft or Aztec libraries. Functions which
are particularly prone to this problem are ARESTORE, CRARRAY,
and PUTARRAY.


5. Notes on Recompiling The Programmer's Library

The files on this disk are a complete replacement for the files
delivered with your previous version of dBASE Tools for C,
with the exception of CFUNC.BIN, which is not contained on this
disk, and any .PRG files (such as DCT1.prg) you may want to keep.

From the \SOURCE Directory:

DCTMAIN.H The main header file for your programs
INTREGS.H Header file used with PEEKPOKE.C
DCT1.C Contains the "main" and all functions
DBARRAY.C The array package
DBFIN.C The financial functions
DBSTAT.C The statistics functions
DCTMSG.C Message functions used to display errors, etc.
PUTWINDO.C Low-level function used by PUTWINDOW
GETPASS.C Low-level function used by GETPASS
PEEKPOKE.C Low-level functions used by PEEK and POKE
SAVWINDO.C These last two source files contain routines
RSTWINDO.C used by DCTMSG to do windowing.

Note that some of the above files are replacements for the previous
file of the same name (from the original package), while others are
completely new.

You will be able to create the object files and libraries that you
need from the source files listed above, with the exception of the
two following library files found in the subdirectories on your disk:

DCTMISC.LIB "Miscellaneous" proprietary routines.
xx_CATCH.LIB Compiler-specific 'interrupt catching' functions

where xx_CATCH.LIB is one of the following:

L2_CATCH.LIB For Lattice version 2.15
L3_CATCH.LIB For Lattice version 3.0
MS_CATCH.LIB For Microsoft version 3.0
AZ_CATCH.LIB For Aztec C PRIME from Manx Software

Both DCTMISC.LIB and xx_CATCH.LIB are compiler-specific; i.e.,
you will need to copy the version of the libraries located in
the directory for your particular compiler.


6. Pre-Parsing of CFUNC Parameters

In addition to the GetFunc, GetNext, and GetString macros, this
version provides the arrays ArgVal[0]...ArgVal[MAXARGS], which
are characters arrays that are filled with the parameters of
each function call. For example, the RAND function call:
CALL cfunc WITH 'RAND 1,100'
causes the following values to be placed in the ArgVal arrays:
ArgVal[0] = 'RAND'
ArgVal[1] = '1'
ArgVal[2] = '100'
This pre-parsing makes it much simpler to write setup functions,
and also results in a significant savings in code size, since
each setup function no longer has to parse its own values. Almost
all of the setup functions in DCT1.C use this convention, except
for functions that need to parse a multiple-word string (such
as PUTARRAY when used with character arrays). Note that the old
GetFunc, GetNext, and GetString macros can still be used as
before, if desired.

7. Documentation Pages for New Functions

The new functions are fully documented in the following pages:


NAME
ARAND - Fill an array with random #'s

SYNTAX
CALL cfunc WITH 'ARAND [, ,,]'

PARAMETERS
Name of array to fill
Mutliply each random fraction by this #
Begin filling at this offset
End filling at this offset

DESCRIPTION
Fills the to elements of the array with the
result of a random fraction multplied by . If
is not given, the default factor of 1 is used. If is not
given, the entire array is filled.

RETURNS
Nothing

EXAMPLES
* Create an array, and fill it with 100 random numbers
* between 0 and 10

CALL cfunc WITH 'CRARRAY randarray,100,n'
CALL cfunc WITH 'ARAND randarray,10'

NOTES
An explicit factor of 0 will, in fact, multiply each random # by
0. This is a convenient way of initializing a range of elements
in an array to zero. Note that this should not be seen as
'clearing' an array since the count will not be set to 0. Note
also that implying a factor of 0 by omitting the
parameter is not the same as an explicit 0, and will instead
default to a value of 1 as described above.

and values, if included, must be positive.


NAME
ARESTORE Restore the elements of an array from a disk file

SYNTAX
CALL cfunc WITH 'ARESTORE , [, , ]'

PARAMETERS
array name
name of disk file (created with ASAVE)
offset at which to start restoring to
last offset to restore to

DESCRIPTION
ARESTORE restores the contents of from the disk file
, which is assumed to be a file created by the
ASAVE function. If is given, the elements will be restored
to beginning with the offset . If is given,
the restoration will stop at the element of or with
the last element actually present in the file, whichever comes first.
If is not given, is assumed to be the largest offset
in the array. Note that the offsets and are for
, not for . That is, if the command

CALL CFUNC WITH 'ARESTORE SAVEIT SAVEIT.ARR 5 10'

is given, the first element in SAVEIT.ARR will be read into offset
5 of the SAVIT array (which will correspond to the 6th position), and
subsequent values stored in the file will be read into consecutive
positions, until the sixth value in the file is restored to offset
10 (11th position) in the array. If and are both
omitted, all the elements previously stored in the file will be
inserted in the array. The file remains unmodified.

and values, if included, must be positive.
RETURNS
Returns + the number of elements restored.
Return variable is c_n_result.

EXAMPLES
Restore the array members saved in the ASAVE example:

. CALL cfunc WITH 'ARESTORE USERSTUF,USERSTUF.SAV'


NAME
ASAVE Save the elements of an array to a disk file

SYNTAX
CALL cfunc WITH 'ASAVE , [, , ]'

PARAMETERS
array name
name of disk file to create
offset from which to start saving
last element to save

DESCRIPTION
ASAVE stores the contents of to disk. can
be any legal DOS file name, including disk and path
designators (for example: "A:\ARRAYS\TEMP\MYSTUFF.SAV"). If
the file already exists on the disk, its original
contents will be lost and replaced with the new values in
. If is given, the contents will be saved
beginning with the offset specified by , and ending
with the offset specified by the optional , if present,
or until all elements of the array are written to the file,
if is not present. If and are not given,
all the elements of the array are saved.

RETURNS
Returns the actual number of elements stored.
Return variable is c_n_result.

EXAMPLES
Save the first 10 elements of the array USERSTUF to disk:

. CALL cfunc WITH 'ASAVE USERSTUF,USERSTUF.SAV,10'

NOTES
ASAVE stores numbers to six decimal places.
and , if included, must be positive.


NAME
CHI Calculate chi-square statistic

SYNTAX
CALL cfunc WITH 'CHI , [,]

PARAMETERS
Array of expected values
Array of observed values
Size of arrays

DESCRIPTION
Calculates the chi-square statistic, according to
the following formula:

V = (expected[0]-observed[0])^2 / expected[0]
+ (expected[1]-observed[1])^2 / expected[1]

.
.
.

+ (expected[n-1]-observed[n-1])^2 / expected[n-1]

RETURNS
Returns the chi-square statistic to the dBASE
numeric variable.

Return variable is c_n_result.

EXAMPLES
* The following example uses Don Knuth's results of dice-throwing
* in volume 2 of "The Art of Computer Programming: Seminumerical
* Algortithms," pages 39-42.

call cfunc with 'crarray expected,11,n'
call cfunc with 'crarray observed,11,n'
call cfunc with 'putarray expected, 0, 4'
call cfunc with 'putarray expected, 1, 8'
call cfunc with 'putarray expected, 2, 12'
call cfunc with 'putarray expected, 3, 16'
call cfunc with 'putarray expected, 4, 20'
call cfunc with 'putarray expected, 5, 24'
call cfunc with 'putarray expected, 6, 20'
call cfunc with 'putarray expected, 7, 16'
call cfunc with 'putarray expected, 8, 12'
call cfunc with 'putarray expected, 9, 8'
call cfunc with 'putarray expected, 10, 4'

call cfunc with 'putarray observed, 0, 2'
call cfunc with 'putarray observed, 1, 4'
call cfunc with 'putarray observed, 2, 10'
call cfunc with 'putarray observed, 3, 12'
call cfunc with 'putarray observed, 4, 22'
call cfunc with 'putarray observed, 5, 29'
call cfunc with 'putarray observed, 6, 21'
call cfunc with 'putarray observed, 7, 15'
call cfunc with 'putarray observed, 8, 14'
call cfunc with 'putarray observed, 9, 9'
call cfunc with 'putarray observed, 10, 6'

call cfunc with 'chi expected, observed, 11'
? 'chi-square = ', c_n_result


NAME
CLRWINDOW Clear a section of the screen

SYNTAX
CALL cfunc WITH 'CLRWINDOW ,,,[,]'

PARAMETERS
, Coordinates of upper left corner of window
, Coordinates of lower right corner of window
Optional flag to clear interior

DESCRIPTION
Clears the area defined by the given coordinates to spaces. If
is non-zero, only the borders of the window
are cleared. If is zero or omitted, clears the
border and its contents. and refer to column numbers,
and and refer to row numbers.

RETURNS
Nothing

EXAMPLES
* Clear the first 4 lines of the screen:
call cfunc with 'clrwindow 0,0,3,79'

NOTES
See PUTWINDOW.


NAME
FDUMPARRAY Dump array contents to text file

SYNTAX
CALL cfunc WITH 'FDUMPARRAY ,,,'

PARAMETERS
Array name
File Name
Begin at this offset
End at this offset

DESCRIPTION
Dumps the contents of to the text file , beginning
at offset and ending at offset . If already
exists, it is overwritten. FDUMPARRAY includes the index numbers
of the array elements.

RETURNS
Returns the actual count of elements in the array to the
c_n_result variable.

NOTE
and values must be positive.


NAME
GETPASS Get a password from the user

SYNTAX
CALL cfunc WITH 'GETPASS'

PARAMETERS
None

DESCRIPTION
Gets an 8-character password from the user. The character '#'
is echoed for each character entered from the keyboard. Only
alphanumeric characters can be entered, and invalid characters
will produce a beep. The backspace key can be used to delete
characters.

RETURNS
Returns the password to the c_c_result variable.




NAME
GETSIZE Get the size of an array

SYNTAX
CALL cfunc WITH 'GETSIZE '

PARAMETERS
Name of an array created eariler with CRARRAY

DESCRIPTION
Gets the size that was created with.

RETURNS
Returns the size to the c_n_result variable.




NAME
MEMSTAT Get the status of available memory

SYNTAX
CALL cfunc WITH 'MEMSTAT'

PARAMETERS
NONE

DESCRIPTION
Calculates the amount of memory available for arrays.

RETURNS
Returns the available memory to the c_n_result variable

NOTE
Valid only for the LATTICE version.


NAME
PEEK - Examine the contents of a memory location

SYNTAX
CALL cfunc WITH 'PEEK , '

PARAMETERS
Decimal address of memory offset
Decimal address of memory segment

DESCRIPTION
Returns the byte located at the indicated segment and
offset.

RETURNS
Returns the contents of the memory location to c_n_result.





NAME
POKE - Place a value in a memory location

SYNTAX
CALL cfunc WITH 'POKE , , '

PARAMETERS
Decimal value to place in memory
Decimal address of memory offset
Decimal address of memory segment

DESCRIPTION
Writes the value of to the memory location
specified by and . Valid numbers for
are -128 through +127.

RETURNS
Nothing





NAME
PUTWINDOW Draw a window on the screen

SYNTAX
CALL cfunc WITH 'PUTWINDOW ,,,,,'

PARAMETERS
, Coordinates of upper left corner of window
, Coordinates of lower right corner of window
Non-zero if window should be filled with spaces
0 for single-line window, non-zero for double-line

DESCRIPTION
Draws a window over the specified coordinates.

RETURNS
Nothing

NOTES
If coordinates outside the screen boundary are passed, or if the
numbers passed for the first corner are larger than the numbers
passed for the second corner, unexpected results may be seen.

See CLRWINDOW.



NAME
RNARRAY Rename an array

SYNTAX
CALL cfunc WITH 'RNARRAY , '

PARAMETERS
Current name of array
New name to use for array


DESCRIPTION
Renames the array to . This is
equivalent to saving the contents of , freeing
the array , creating a new array called
that is the same size as , and restoring the
contents to .

RETURNS
Nothing.


NAME
SETBELL Set error bell on/off

SYNTAX
CALL cfunc WITH 'SETBELL '

PARAMETERS
0 (OFF) or non-zero (ON)


DESCRIPTION
Normally, errors produce a bell sound and an error message. SETBELL
can be used to turn this bell off (or back on). If is 0 or
any expression that evaluates to zero (such as any non-numeric
string), the bell is turned off. If is a non-zero number, it
is turned on. The flag is set to ON upon start-up.

RETURNS
Nothing.


NAME
SOUND Generate a sound on the speaker

SYNTAX
CALL cfunc WITH 'SOUND , '

PARAMETERS
Frequency of sound in MHz
Duration in clock ticks

DESCRIPTION
Generates a sound of the specified frequency and
duration. is in clock ticks, and must be
between 0 and 65535. There are approxiately 18.2
clock ticks per second.

RETURNS
Nothing

EXAMPLES
* Produce a glissando (sliding scale)

i = 440
do while i <= 1000
call cfunc with 'sound '+str(i)+',1'
i = i+5
enddo
do while i >= 440
call cfunc with 'sound '+str(i)+',1'
i = i-5
enddo