CPDB.Net

err = CPDB_AddRecord(UInt8 iHandle)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

Description :
Add a record to the database.
Copy the current record and his modifications if a read operation or modifications
have been previously made.

Use CPDB_Clear before call CPDB_AddRecord to add a blank record.

Return 0 if no error occured.
Return CPDB_ERR_WRITEFAILED if write failed.
Return CPDB_ERR_MEMORYERROR if the system refused the adding.

err = CPDB_Clear(UInt8 iHandle)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

Description :
Use CPDB_Clear before a use of CPDB_AddRecord, CPDB_UpdateRecord
or the modification functions to be sure to work on a blank record.

Return 0 if no error occured.

err = CPDB_Close(UInt8 iHandle)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

Description :
Close the database. To open a Database use CPDB_Open.

Return 0 if no error occured.

err = CPDB_CoundRecord(UInt8 iHandle, UInt16 *piValue)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.
UInt16 *piValue : pointer on a UInt16 value, where the number of records will be written.

Description :
Use CPDB_CoundRecord to get the number of record of the opened database.

Return 0 if no error occured.

err = CPDB_CreateDatabase(UInt16 iCardNo, const Char *sName, UInt32 iCreator,
                         const Char *sDescription)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.
UInt16 iCardNo : Number of the memory card of the Palm, use 0 for RAM.
const Char *sName : Name of the database to create
UInt32 iCreator : Creator ID, example : 'CPDB'
const Char *sDescription : Description mask of the database structure

Description :
Create a new database. If the database already exist, the function failed.

Description mask format :
NAMEFIELD1=TYPE[SIZE];NAMEFIELD2=TYPE[SIZE];...

Types :
SHORTINT       : Short Int / 1 octet
INT            : Int / 2 octets
LONGINT        : Long Int / 4 octets
STRING[SIZE]   : String

Each field est separated by a ';' and described by a name, the sign '=', a type and the size
between [] if type is STRING. The size his a "C" size, with the AsciiZ included.
Warning : the sized if only provided for STRING fields.

Return 0 if no error occured.
Return CPDB_ERR_INVALID the mask is invalid.
Return CPDB_ERR_DATABASEALREADYEXIST if the database already exist.
Return CPDB_ERR_CARDNOTPRESENT if iCardNo is not a valid memory card.
Return CPDB_ERR_RAMONLYCARD if the specified card has no storage RAM.
Return CPDB_ERR_NOTENOUGHSPACE if there is not enough memory.

err = CPDB_DatabaseExist(const Char *sName)

Parameters :
const Char *sName : Database name.

Description :
Return 0 if the database exist or CPDB_ERR_NOEXIST if the database doesn't exist.

err = CPDB_SupprimeEnregistrement(UInt8 iHandle)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

Description :
Delete the current record in the database.

Return 0 if no error occured.
Return CPDB_ERR_NOPREVREAD if there is no current record.

err = CPDB_IsFound(UInt8 iHandle, Boolean *piFlag)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

Boolean *piFlag : pointer on a boolean value, where result of the last search operation
will be written.

Description :
After a browse operation, use CPDB_IsFound is used to get the search result.
After execution piFlag value is 'true' if the search is successfull.

Return 0 if no error occured.

err = CPDB_IsOut(UInt8 iHandle, Boolean *piFlag)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.
Boolean *piFlag : pointer on a boolean value, where result will be written.

Description :
After a search operation, use CPDB_IsOut is used to get the database cursor state.
The "cursor" is the position of the last reading operation.

After execution piFlag value is 'true' if the cursor is successfully positionned.

CPDB_IsOut is very helpfull to browse a database or to verify the availability 
of the database cursor.

Return 0 if no error occured.

err = CPDB_ListField(UInt8 iHandle,  MemHandle *phListe)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.
MemHandle *phListe : pointer on a free memhandle.

Description :
Use CPDB_ListField to get the field list of a database.

The list is a simple string, this string is allocated by CPDB, you need to free the 
memhandle after use.

The string format is :
FIELDNAME=FIELDTYPE;FIELDNAME=FIELDTYPE;FIELDNAME=FIELDTYPE;...

FIELDTYPE description :
enum __cpdb_FieldType {

 CPDB_TYPESTRING = 0,

 CPDB_TYPESHORTINT = 1,

 CPDB_TYPEINT = 2,

 CPDB_TYPELONGINT = 3

 };

Return 0 if no error occured.

err = CPDB_Open(UInt16 cardNo, const Char* pnameP, UInt16 mode, UInt8 *piHandle)

Parameters :
UInt16 cardNo : card number, 0 if no additional card.

const Char* pnameP : cpdb database name.

UInt16 mode : opening mode.

UInt8 *piHandle : pointer on an Int8 value, where the handle will be written. 

Description :
Use CPDB_Open to open a cpdb database and get a handle on it.

pmode description :
  dmModeReadWrite : Read-write access. 

  dmModeReadOnly : Read-only access. 

  dmModeWrite : Write-only access. 

  dmModeExclusive : Don't let anyone else open this database.

Note : the dmModeReadWrite mode is required if you want to use the CPDB_Sort functionnality.

Return 0 if no error occured.

err = CPDB_ReadFirst(UInt8 iHandle, const Char *sName)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

const Char *sName : field name.

Description :
Read the first record of the database.

Return 0 if no error occured.

err = CPDB_ReadInt(UInt8 iHandle, const Char* sName, Int16 *piValue)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

const Char *sName : field name.

Int16 *piValue : pointer on an Int16 value, where the field value will be written.


Description :
Read an Integer field of the database.

Example :
 Int16 cust_year;
 err = CPDB_ReadInt(handleCustomers, "year", &cust_year); 

Return 0 if no error occured.

err = CPDB_ReadLast(UInt8 iHandle, const Char *sName)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

const Char *sName : field name.

Description :
Read the last record of the database.

Return 0 if no error occured.

err = CPDB_ReadLongInt(UInt8 iHandle, const Char* sName, Int32 *piValue)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

const Char *sName : field name.

Int32 *piValue : pointer on an Int32 value, where the field value will be written.



Description :
Read a Long Integer field of the database.

Example :
 Int32 cust_number;
 err = CPDB_ReadLongInt(handleCustomers, "number", &cust_number); 

Return 0 if no error occured.

err = CPDB_ReadNext(UInt8 iHandle, const Char *sName)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

const Char *sName : field name.

Description :
Read the next record of the database.

Return 0 if no error occured.

err = CPDB_ReadPosition(UInt8 iHandle, UInt16 *piValue)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

UInt16 *piValue : pointer on a UInt16 value, where the database position will be written.

Description :
Use CPDB_readPosition to get the cursor position of the opened database.

You can use this value with CPDB_SeekDirect. The first position is 1.

Return 0 if no error occured.

err = CPDB_ReadPrevious(UInt8 iHandle, const Char *sName)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

const Char *sName : field name.

Description :
Read the previous record of the database.


Return 0 if no error occured.

err = CPDB_ReadShortInt(UInt8 iHandle, const Char* sName, Int8 *piValue)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

const Char *sName : field name.

Int8 *piValue : pointer on an Int8 value, where the field value will be written.


Description :
Read a Short Integer field of the database.

Example :
 Int8 cust_age;

 err = CPDB_ReadShortInt(handleCustomers, "age", &cust_age); 

Return 0 if no error occured.

err = CPDB_ReadString(UInt8 iHandle, const Char* sName, MemHadle*phValue)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

const Char *sName : field name.

MemHandle *phValue : pointer on a Memhandle, where the field value will be written.


Description :
Read an string field of the database. The memhandle is allocated by CPDB, you need to 
free the handle after use.

Example :
 MemHandle hcust_name;

 Char *scust_name;

 err = CPDB_ReadString(handleCustomers, "name", &hcust_name);

 scust_name = MemHandleLock(hcust_name);

 ... 

Return 0 if no error occured.

err = CPDB_ReadVersion(MemHandle *phVersion)

Parameters :
MemHandle *phVersion : pointer on a Memhandle, where the version value will be written.

Description :
Read the CPDB library version. The version is a string value.
The MemHandle is allocated by CPDB, you need to free the handle after use.

Return 0 if no error occured.

err = CPDB_Search(UInt8 iHandle, const Char *sName, const Char*sValue, UInt8 iMode)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

const Char *sName : field name.

const Char*sValue : value to search in the field.

UInt8 iMode : search modes, see description.

Description :
Search a value in a database field. If the field is numeric, a conversion is made.

iMode values :
CPDB_SEARCH_REVERSE : the database is browsed in reverse way.
CPDB_SEARCH_FROMCURRENT : the search is made from the current record.
CPDB_SEARCH_UNTIL : find the value greater or egal (lower if CPDB_SEARCH_REVERSE)

For string field only :
CPDB_SEARCH_WITHIN : search inside the string (default mode : "begin with")
CPDB_SEARCH_CASELESS : no case sensitive (default mode : case sensitive)

Example :
err = CPDB_Search(handleCustomers, "contry", "france", CPDB_SEARCH_WITHIN 
+ CPDB_SEARCH_CASELESS);

Return 0 if no error occured.

err = CPDB_SearchNumeric(UInt8 iHandle, const Char *sName, const Int32 iValue, UInt8 iMode)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

const Char *sName : field name.

const Int32 iValue : value to search in the field.

UInt8 iMode : search modes, see description.

Description :
Search a numeric value in a database field. If the field type is less than Int32, a 
conversion is made, so beware of data loss.

iMode values :
CPDB_SEARCH_REVERSE : the database is browsed in reverse way.
CPDB_SEARCH_UNTIL : find the value greater or egal (lower if CPDB_SEARCH_REVERSE)

CPDB_SEARCH_FROMCURRENT : the search is made from the current record.

(other modes ignored)

Example :
 // Search next customer with field "year" = 2001.

 err = CPDB_SearchNumeric(handleCustomers, "year", 2001, CPDB_SEARCH_FROMCURRENT);

Return 0 if no error occured.

err = CPDB_SeekBackward(UInt8 iHandle, UInt16 piOffset)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

UInt16 piOffset : number of records to seek.

Description :
Use CPDB_SeekBackward to change the cursor position in backward, the "jump" is 

relative to the current position.

Return 0 if no error occured.

err = CPDB_SeekDirect(UInt8 iHandle, UInt16 piPosition)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

UInt16 piPosition : new database cursor position.

Description :
Use CPDB_SeekDirect to change the cursor position.
The first position of a database is 1.


Return 0 if no error occured.

err = CPDB_SeekForward(UInt8 iHandle, UInt16 piOffset)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

UInt16 piOffset : number of records to seek.

Description :
Use CPDB_SeekForward to change the cursor position in forward, the "jump" is 
relative to the current position.


Return 0 if no error occured.

err = CPDB_Sort(UInt8 iHandle, const Char *sName, UInt8 iDirection)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

const Char *sName : field name.

UInt8 iDirection : sort direction, see description.

Description :
Sort the database on a field. Big databases can take time to be sorted.

iDirection possible values:
CPDB_SORT_ASC

CPDB_SORT_DESC


Note : the sort operation is a database modification, the database must be open 
in write mode.

Return 0 if no error occured.

err = CPDB_UpdateRecord(UInt8 iHandle)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

Description :
Update the current record in the database.
Valid the modifications made to the current record.

Return 0 if no error occured.
Return CPDB_ERR_WRITEFAILED if write failed.
Return CPDB_ERR_NOPREVREAD if there if no current record.

err = CPDB_WriteString(UInt8 iHandle, const Char* sName, const Char *sValue)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

const Char *sName : Field name.

const Char *sValue : Value to write in the record.

Description :
Write a string field value in the current record.

Example :
 err = CPDB_WriteString(handle, "name", "CPDB.NET"); 

If the string size if too long, the string is troncated.

Return 0 if no error occured.
Return CPDB_ERR_WRITEFAILED if write failed.

err = CPDB_WriteInt(UInt8 iHandle, const Char* sName, Int16 iValue)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

const Char *sName : Field name.

Int16 iValue : Value to write in the record.

Description :
Write a Int field value in the current record.

Exemple :
 Int16 year = 2002;
 err = CPDB_WriteInt(handle, "year", year); 

Return 0 if no error occured.
Return CPDB_ERR_WRITEFAILED if write failed.

err = CPDB_WriteLongInt(UInt8 iHandle, const Char* sName, Int16 iValue)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

const Char *sName : Field name.

Int16 iValue : Value to write in the record.

Description :
Write a Long Int field value in the current record.

Exemple :
 Int32 num = 12345678;
 err = CPDB_WriteLongInt(handle, "number", num); 

Return 0 if no error occured.
Return CPDB_ERR_WRITEFAILED if write failed.

err = CPDB_WriteShortInt(UInt8 iHandle, const Char* sName, Int8 iValue)

Parameters :
UInt8 iHandle : CPDB database handle, returned by CPDB_Open.

const Char *sName : Field name.

Int8 iValue : Value to write in the record.

Description :
Write a Short Int field value in the current record.

Exemple :
 Int8 num = 123;
 err = CPDB_WriteShortInt(handle, "number", num); 

Return 0 if no error occured.
Return CPDB_ERR_WRITEFAILED if write failed.