Category : Paradox DBMS
Archive   : CROUTES.ZIP
Filename : TABLE.DOC

 
Output of file : TABLE.DOC contained in archive : CROUTES.ZIP


Paradox "C" Language Table Routines

1. Overview
-----------

These routines define a simple interface to allow non-indexed Paradox
tables to be accessed from outside of the Paradox environment.

Terminology: instead of "file", "table"; and instead of "record", "row".

Calls are provided to open or create (and automatically open) a table.
These calls return a pointer to a structure of type TABLE, which
contains basic information about the table. This pointer is then used in
all subsequent calls to the other table routines. The user names a
table by providing an optional pathname followed by a one to eight
character table name that meets DOS naming conventions. The extensions
used (such as .db) are hidden. In the create call the user defines the
name of the table, the number of the fields, and for each field its
type (one of D, $, N, S, or Annn) and name. Fields are numbered
from one.

Once a table is opened, calls are provided to position to a row, called
the current row, and then get or put fields in that row. Rows are
numbered from one to the number of rows in the table. Row numbers
are longs, not ints. New rows are created by appending a row with empty
fields to the end of the table. That row then becomes the current row.
Rows may not be inserted or deleted. Changed fields are automatically
written to the table.

The data in the fields is seen by the user in display representation
(that is, a null terminated ascii string). The underlying data structure
is deliberately hidden with the exception of four routines that allow
the user to translate between Paradox numeric formats and "C" numeric
formats.

In the event of an error return the global int tError contains
a detailed error code. The codes are documented in table.h.
The routine tErrMsg returns an ascii interpretation of the error number.
The tError variable is set after every call to a table routine where 0
indicates no error.

At this time indexed and encrypted files are not supported. The create
call has a parameter reserved for the number of indexed fields, allowing
for eventual indexed file support. Encryption will be supported through
a separate call once the table is open.

2. Synopsis of routines
-----------------------

----------------------------- tExist -----------------------------------

tExist tells whether a table exists. It is useful as an error check
before defining a new table. tExist returns TRUE if table exists;
FALSE if it does not or there was an error.

int tExist(tName);
char *tName; ** asciiz table name, optionally preceded
** by a path name.

----------------------------- tDelete -----------------------------------

tDelete deletes a table. tDelete returns TRUE if table was successfully
deleted; FALSE if there was an error.

int tDelete(tName);
char *tName; ** asciiz table name, optionally preceded
** by a path name.

----------------------------- tEmpty -----------------------------------

tEmpty deletes all records in a table but retains the table's structure.
tEmpty returns TRUE if table was successfully emptied; FALSE if there was
an error. The table MUST NOT be open when this function is called.

int tEmpty(tName);
char *tName; ** asciiz table name, optionally preceded
** by a path name.

----------------------------- tCreate ----------------------------------

tCreate creates and opens a table named by tName.
The user must specify the number of fields, their names, and their data
types. Any existing table with the same name is deleted.

Field names are represented as asciiz strings with up to twenty-five
characters that meet the Paradox rules for a field name.

Field types must also meet Paradox rules; they are one of "D",
"$", "N", "S", or "Annn" where "nnn" is 1 to 255.

tCreate returns a pointer to a structure of type TABLE or NULL (for
an error condition).

TABLE *tCreate(tName,nFields,nameList,typeList,nIdxFields);
char *tName; ** asciiz table name, optionally preceded
** by a path name.
int nFields; ** number of fields (1 to 255)
char *nameList[]; ** array of pointers to field names
char *typeList[]; ** array of pointers to field types
int nIdxFields; ** number index fields, 0 for now


2. Synopsis of routines (cont'd)
--------------------------------


----------------------------- tOpen ------------------------------------

tOpen opens an existing table named by tName and returns a pointer
to a structure of type TABLE or NULL (for an error condition).
The current row is set to 1.

TABLE *tOpen(tName);
char *tName; ** asciiz table name, optionally preceded
** by a path name.

----------------------------- tNextRow ---------------------------------

tNextRow moves the current row in the table associated with tablePtr
to the next row. Trying to move past the last row in the table
is an error. The new row number or (long)ERROR is returned.

long tNextRow(tablePtr);
TABLE *tablePtr;

----------------------------- tPrevRow ---------------------------------

tPrevRow moves the current row in the table associated with tablePtr
to the previous row. Trying to move before the first row in the table
is an error. The new row number or (long)ERROR is returned.

long tPrevRow(tablePtr);
TABLE *tablePtr;

----------------------------- tTell ---------------------------------

tTell gets the current row number in the table associated with tablePtr.
tTell returns the current row number, zero if the table is empty, or
(long)ERROR.

long tTell(tablePtr);
TABLE *tablePtr;

----------------------------- tNumRows ---------------------------------

tNumRows gets the number of rows in the table associated with tablePtr.
The number of rows (including zero for an empty table) or (long)ERROR
is returned.

long tNumRows(tablePtr);
TABLE *tablePtr;

----------------------------- tAppend ---------------------------------

tAppend creates an empty row after the last row in the table associated
with tablePtr, and moves the current row in the table to that row.
The new row number or (long)ERROR is returned.

tAppend is the only way provided to create new rows.

long tAppend(tablePtr);
TABLE *tablePtr;

2. Synopsis of routines (cont'd)
--------------------------------


----------------------------- tSeek ------------------------------------

tSeek moves the current row in the table associated with tablePtr
to a new row that is offset rows from origin. Origin must be one
of the following constants:

Origin Definition
------ --------------------

0 Beginning of table (first row in table)
1 Current row in table
2 End of table (last row in table)

The new row number or (long)ERROR is returned.

long tSeek(tablePtr,offset,origin);
TABLE *tablePtr;
long offset; ** number of rows from origin
int origin; ** initial position

----------------------------- tClose -----------------------------------

tClose closes the table associated with tablePtr. If the close was
successful, 0 is returned; otherwise ERROR.

int tClose(tablePtr);
TABLE *tablePtr;

----------------------------- tNumFlds -------------------------------

tNumFlds returns the number of fields in the table associated with
tablePtr or ERROR.

int tNumFlds(tablePtr);
TABLE *tablePtr;

----------------------------- tFldType ---------------------------

tFldType copies the type of field fieldNum in the table associated
with tablePtr to the variable fieldType. Values will be one of "D",
"$", "N", "S", or "Annn" where "nnn" is 1 to 255.

tFldType returns a pointer to fieldType, or NULL (for an error).

char *tFldType(tablePtr,fieldNum,fieldType);
TABLE *tablePtr;
int fieldNum; ** filed number, from one
char *fieldType; ** user supplied array for field type;
** must be at least 5 bytes

2. Synopsis of routines (cont'd)
--------------------------------


----------------------------- tFldName ---------------------------

tFldName copies the name of field fieldNum in the table associated
with tablePtr to the variable fieldName.

tFldName returns a pointer to fieldName, or NULL (for an error).

char *tFldName(tablePtr,fieldNum,fieldName);
TABLE *tablePtr;
int fieldNum; ** filed number, from one
char *fieldName; ** user supplied array for field name;
** must be at least 26 bytes

----------------------------- tFldNum ---------------------------

tFldNum returns the field number for the field name in fieldName,
in the table associated with tablePtr, or ERROR.

tFldNum allows the user to identify the fields in a table by name
instead of number.

int tFldNum(tablePtr,fieldName);
TABLE *tablePtr;
char *fieldName; ** user supplied field name;

----------------------------- tFldPut ---------------------------

tFldPut puts the value specified in fieldVal into field fieldNum in the
table associated with tablePtr. If the routine fails, FALSE is
returned; else TRUE.

tFldPut first validates the data, and then translates it into the Paradox
data representation.

int tFldPut(tablePtr,fieldNum,fieldVal);
TABLE *tablePtr;
int fieldNum; ** field number for the value
char *fieldVal; ** user supplied value as asciiz string.

----------------------------- tFldValidate ---------------------------

tFldValidate validates the value specified in fieldVal against the
type specified in fieldType. If successful, TRUE is returned, else
FALSE.

int tFldValidate(fieldVal,fieldType);
char *fieldVal; ** user supplied value as asciiz string.
char *fieldType; ** user supplied field type


2. Synopsis of routines (cont'd)
--------------------------------


----------------------------- tFldGet ---------------------------

tFldGet gets the value from field fieldNum into fieldVal in the
table associated with tablePtr. If the routine fails, FALSE is
returned; else TRUE.

The value is returned as an asciiz string; the user must ensure
that the array fieldVal is large enough. See the routine tMaxTypeSize
below.

int tFldGet(tablePtr,fieldNum,fieldVal);
TABLE *tablePtr;
int fieldNum; ** field number for the value
char *fieldVal; ** user supplied value as asciiz string.

----------------------------- tMaxTypeSize ----------------------

tMaxTypeSize returns the maximum size in the internal representation
for a given type, or ERROR.

int tMaxTypeSize(fieldType);
char *fieldType; ** field type; i.e. "D", "$", "N", "S",
** or "Annn"

----------------------------- tErrMsg ---------------------------

tErrMsg places an ascii interpretation of the current error number
in tError into errMsg and returns a pointer to errMsg.

The caller must ensure that errMsg has a size of at least 65 bytes.

char *tErrMsg(errMsg);
char *errMsg; ** user supplied array with size >= 65 bytes

----------------------------- tShortPut -----------------------------

tShortPut puts the value specified in shortVal into field fieldNum
in the table associated with tablePtr. If the routine fails, FALSE
is returned, otherwise TRUE.

tShortPut checks to see that the field specified by fieldNum is a
Paradox short (S) field. If it is, the value in shortVal is stored in
the field and TRUE is returned. If fieldNum is not a short field, no
values are updated and FALSE is returned.

int tShortPut(tablePtr,fieldNum,shortVal);
TABLE *tablePtr;
int fieldNum; ** field number for the value
int shortVal; ** user supplied data value


2. Synopsis of routines (cont'd)
--------------------------------

----------------------------- tNumPut -----------------------------

tNumPut puts the value specified in doubleVal into field fieldNum
in the table associated with tablePtr. If the routine fails, FALSE
is returned, otherwise TRUE.

tNumPut checks to see that the field specified by fieldNum is a
Paradox number (N) or dollar ($) field. If it is, the value in
doubleVal is stored in the field and TRUE is returned. If fieldNum is
neither a number nor a dollar field, no values are updated and FALSE
is returned.

int tNumPut(tablePtr,fieldNum,doubleVal);
TABLE *tablePtr;
int fieldNum; ** field number for the value
double doubleVal; ** user supplied data value

----------------------------- tShortGet -----------------------------

tShortGet gets the value from field fieldNum in the table associated
with tablePtr into shortVal. If the routine fails, FALSE is returned.
If the routine succeeds but the value in field fieldNum is null, ERROR
is returned, otherwise TRUE.

tShortGet checks to see that the field specified by fieldNum is a
Paradox short (S) field. If it is, the value in field fieldNum is
stored in shortVal and TRUE is returned. If fieldNum is not a short
field or contains a null value, shortVal remains unchanged and FALSE
or ERROR, respectively, is returned.

int tShortGet(tablePtr,fieldNum,shortVal);
TABLE *tablePtr;
int fieldNum; ** field number for the value
int *shortVal; ** user supplied data area

----------------------------- tNumGet -----------------------------

tNumGet gets the value from field fieldNum in the table associated
with tablePtr into doubleVal. If the routine fails, FALSE is
returned. If the routine succeeds but the value in field fieldNum is
null, ERROR is returned, otherwise TRUE.

tNumGet checks to see that the field specified by fieldNum is a
Paradox number (N) or dollar ($) field. If it is, the value in field
fieldNum is stored in doubleVal and TRUE is returned. If fieldNum is
neither a number nor a dollar field or it contains a null value,
doubleVal remains unchanged and FALSE or ERROR, respectively, is
returned.

int tNumGet(tablePtr,fieldNum,doubleVal);
TABLE *tablePtr;
int fieldNum; ** field number for the value
double *doubleVal; ** user supplied data area


3. Sample code fragment
-----------------------

The sample code below shows the creation of a data base
that contains average weekly cookie consumptions for selected Ansa
employees.

static char *names[] = {
"Employee Name",
"Cookies/Week"
};

static char *types[] = {
"A25",
"N"
};

TABLE *cookie;

/* symbolic field definitions */

#define EMPLOYEE 1
#define COOKIES 2

if ( (cookie = tCreate("cookie",2,names,types,0)) == NULL)
errorExit();

tAppend(cookie);
tFldPut(cookie,EMPLOYEE,"Gorman");
tFldPut(cookie,COOKIES,"17");

tAppend(cookie);
tFldPut(cookie,EMPLOYEE,"Nielsen");
tFldPut(cookie,COOKIES,"19");

.
.

tClose(cookie);


Compilers supported
-------------------

Library name Compiler
------------ --------

TABLETS.LIB* Turbo "C" verrsion 1.5 small model
TABLETL.LIB* Turbo "C" verrsion 1.5 large model

TABLETS2.LIB Turbo "C" verrsion 2.0 small model
TABLETL2.LIB Turbo "C" verrsion 2.0 large model

TABLEMS.LIB Microsoft "C" version 4.0 small model
TABLEML.LIB Microsoft "C" version 4.0 large model

TABLEMS5.LIB Microsoft "C" version 5.0 small model
TABLEML5.LIB Microsoft "C" version 5.0 large model


* not compatible with Turbo "C" 2.0 libraries


  3 Responses to “Category : Paradox DBMS
Archive   : CROUTES.ZIP
Filename : TABLE.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/