SoftC's philosophy is consistent with the C outlook that more is less. There is no one-to-one correspondence between lines of dBASE or Clipper code, as you would expect from a true Clipper emulator. The SoftC DBL is not a function library trying to look like a fourth-generation language, nor is it a replacement for Clipper (or, presumably, your own favorite xBase dialect). It looks, feels, and smells like C code. Essentially you are back to the old tradeoff of C versus higher-level languages; you will put in a fair amount of extra work in return for much tighter and possibly faster code.

As an example, there is no SoftC function that replicates the functionality of the dBASE USE statement. Instead, you would step through this process:

1. Open the DBF file with scddopenx and return a database handle in the handle parameter. You can open the file with shared or exclusive access, and read/write or read-only usage. You can determine whether or not to buffer groups of records with a scddopenx parameter, and adjust the size of that buffer with scddbfrsz.

2. For each index file you wish to use, invoke the proper function of the scd?openx family. For Clipper indexes use scdcopenx; for FoxBase use scdiopenx; and for dBASE use scdnopenx. Each one of these also returns an index file handle in the handle parameter. Buffering options are similar to those for DBF files.

3. Now invoke scddrinfo to determine how many fields are in the database and how long your I/O buffer will have to be. (SoftC DBL will handle the I/O buffer, if you want.)

4. Given the number of fields in the database, you now malloc or (in C++) new an array of that many SC_FIELDINFO. One call to scddfinfo fills that array with field descriptions including field name, type, length, and decimal positions.

5. If you want to use any fields of memo type, you have to open the memo files separately with functions for that purpose. On the other hand, if you aren't interested in any memo fields that may exist, you can safely ignore them.

Reading a database record into the SoftC DBL internal buffers requires only one call to scddrget, but that doesn't load individual fields without use of the scddfget or scddfgets functions. Nor does it get the correct record number in an index situation without a call to scd?knext family of functions, which like scd?openx correspond to the dBase dialect with which you want to conform.

The advantage to this minimalist approach is that the SoftC DBL does only the work you need to get the job done. If you are interested in the values of only one or two fields in a database containing over 100 fields you can see the utility of this kind of low-level organization. Clipper programmers in particular will love seeing useful work done in executables less than 50K in size.

These two code fragments accomplish the same thing:

/*---- one way ----*/
scddfgets (handle, recno);
if (scecode())
 printf ("Error!\n");

/*---- another way ----*/
if (scddfgets (handle, recno) != SC_SUCCESS)
  printf ("Error!\n");

For example, you might want to load a database record by index key and print the value of the first field. This code would do the job:

sceclr()
scdckfind (ntx_handle, keyvalue, &recno, SC_EXACT);
scddrget (dbf_handle, recno);
scddfgets (dbf_handle, 0, buffer);
if (scecode())
 printf ("Error code was %d.\n", scecode());
else
 printf ("Field 1: %s\n", buffer);

The function scemsg always returns a pointer to a string describing the problem associated with the current value of scecode. I have found it useful to write error-handling code like this:

if (scddrget (handle, recno) != SC_SUCCESS) {
 fprintf (stderr,
  "Couldn't open file %s!\n"
  "SoftC returns error (%d) %s\n",
scecode(), scemsg());
 }

if (scddrget (handle, recno) != SC_SUCCESS) {
 MessageBox (hwnd,
  (LPSTR) scemsg(),
  (LPSTR) "SoftC Error",
  MB_OK);
 }

The scddfgets and scddfputs functions differ from their relatives scddfget and scddfput (without the S) by automatically converting field values to and from strings. This makes data-dump or browsing utilities much simpler to write, as you can pretend that all fields are of character type when that is convenient for you.

I really like the way the SoftC DBL handles character-to-logical conversion. For one particular application I needed to do a type-safe replacement for the Clipper APPEND FROM command. Specifically, given two arbitrary dBASE files (with or without memos) I wanted to zap one and copy into it all records from the other. (Fields with matching names of course would copy over.) The problem with Clipper's APPEND FROM command is that if a field appears in both the source and destination files with different types you will get a type mismatch error.

One nice touch appeared when I converted part of a Clipper application that now uses all Y and N character fields where logicals should have been used. The SoftC scddfgets and scddfputs functions handled this without a hitch; they sensibly took a Y value to be equivalent to TRUE, and a N or blank value to be a FALSE. This is a detail that could have been left out in a true bare-metal implementation, but I definitely appreciated it. If it violates SoftC's minimalist spirit, I guess I can live with that.

There is a reasonably good suite of date and time manipulation functions such as scddi2s, which converts year, month, and day integer values into a character string matching the currently selected date format, and sccdl2dow, which returns the day of week for a given date parameter. These functions do validate dates and correctly interpret leap years.

When using recursion with the SoftC DBL, it is necessary to find a record in the index all over again to bring the index's internal buffers back to the same consistent state. Just re-reading the record with a scddrget call is not enough. An extra call to scdckfind is required for the following scdcknext call to point to an incorrect next record.

This is a gotcha that was obvious only when found, although in hindsight there is no reason to expect that reading a data file record should magically update an index file record pointer. With higher-level languages such as Clipper the details of positioning the index pointer are taken care of, but manipulating databases in C or C++ is the application programmer's responsibility.

If your development is for an audience with existing Clipper, dBASE, or FoxBase applications you will find most worthwhile the extra attention that was given to compatibility issues. Many libraries can handle the dBASE DBF data file format, but few actually correctly use the various index file formats that exist. The SoftC DBL scores high marks for compatibility, at least as far as I can verify with Clipper.

I found that writing Windows 3.0 code with the SoftC DBL presents no special problems. Since most commercial Windows development is still done in C or C++, it is the kind of environment where the SoftC DBL might be particularly useful.

As I've said, the SoftC DBL is not a replacement for Clipper or any other dBASE-derived language. It is still another C function library, using C data types and C syntax. If you are looking for a complete @ ... SAY ... GET interface or the slick Clipper functions like DBEDIT you will be disappointed. The SoftC DBL is not an easy tool for porting existing, nontrivial applications from Clipper to C if that is what you have in mind. On the other hand, if you are interested in the features that make C such a great development language — such as tight executable code, freedom to manipulate underneath the database structures when you want to, portability to many environments, and C++ compatibility — you may want to investigate the SoftC Database Library.

Product Information:
Product: SoftC Database Library
Price: $195.00
Soft C Ltd.
16820 3rd St. NE
Anoka, MN 55304
(612) 434-6968

System Requirements:
MS-DOS 2.0 or later
MS-Windows 3.0 or later
UNIX/XENIX SVR4
OS/2 v1.1
6MB disk space