FoamDBAddFieldToRecord()

 FieldID FoamDBAddFieldToRecord(
        VMFileHandle       file, 
        MemHandle       record, 
        byte       *fieldName, 
        word       fieldType);

Adds a field to the record record and gives it the name fieldName. A unique FieldID is assigned to the new field and returned. The Foam Database uses the fieldType to determine the sort order of the records (i.e., a field of type "3" will be inserted after all the existing fields of type "3", but before the fields of type "4"). If you are using this routine within the context of a ContDB, then fieldType should be one of the ContdbFieldType values (see below). Otherwise, you may set your own field type.

	/*
 	* The standard field types in the contact database
 	*/
	typedef ByteEnum ContdbFieldType;
	#define CFT_NAME        0
	#define CFT_COMPANY     1
	#define CFT_TITLE       2
	#define CFT_ADDRESS     3
	#define CFT_PHONE       4
	#define CFT_FAX         5
	#define CFT_EMAIL       6
	#define CFT_DTMF        7
	#define CFT_NOTES       8
	/* Only available in Communicator products after Feb 1997: */
	#define CFT_URL         9
	#define CFT_PASSWORD    10
	#define CFT_TEL_FAX     11
	#define CFT_TEL_DATA    12

Include: foamdb.h

FoamDBBinarySearch()

RecordID   FoamDBBinarySearch(
		VMFileHandle file,
		MemHandle record,
		PCB(int, callback,		
			(void * passedRecord,	 /* Callback routine */
			void * curRecord )));

This routine performs a binary search of the Foam database file to determine the index of record. The database is sorted according to an application-defined callback routine, so FoamDBBinarySearch() can find record in a divide-and-conquer method using a callback routine based on the same sorting scheme. If this routine finds record, it returns the RecordID of this record in the database; otherwise, it returns where this record would belong in the database.

(PCB is a GEOS macro that defines a callback routine.) The prototype for this callback routine should be of the form:

      int  _pascal  MyCallBackRoutine(void * passedRecord, void * curRecord);

The callback routine should return +1 if the record passedRecord comes after curRecord, -1 if passedRecord comes before curRecord, and 0 if the items match.

Include: foamdb.h

FoamDBClose()

word FoamDBClose(
        VMFileHandle    file);

Closes the file. It is the same as VMClose(). If successful, returns non-zero; if an error occurred, then it returns FALSE and the error value must be retrieved by ThreadGetError().

Include: foamdb.h

FoamDBCreateEmptyRecord()

MemHandle FoamDBCreateEmptyRecord(
        VMFileHandle    file);

Creates a new record in the database, gives it a unique ID, and returns the handle of the record data. This record will contain no fields or data. This record does not get saved to the database unless FoamDBSaveRecord() is called.

Warning: If you want to free the memory associated with a record, do not use MemFree(); instead call FoamDBDiscardRecord() to discard any record changes or FoamDBSaveRecord() to commit them to the the database.

Include: foamdb.h

FoamDBDeleteFieldFromRecord()

void FoamDBDeleteFieldFromRecord(
        VMFileHandle    file,
        MemHandle       record,
        FieldID            id);     /* Field to delete */

Deletes field ID id from the record of the database file. id is the ID of the field as returned from FoamDBAddFieldToRecord(). While it's not a pretty solution, you can also get the FieldID of a field from the FH_id part of the FieldHeader struct.

Include: foamdb.h

FoamDBDeleteRecord()

Boolean FoamDBDeleteRecord(
	VMFileHandle 	file, 
	MemHandle 	record);    /* Record to terminated */

This routine frees up the record data in record, and, if the record exists in the database, deletes it from the database as well.

Returns non-zero if the record did not exist in the database.

Include: foamdb.h

FoamDBDiscardRecord()

void FoamDBDiscardRecord(
	VMFileHandle 	file, 
	MemHandle 	record);

This routine discards any changes to the passed record record and frees up the record data stored in the passed handle, but does nothing to the data stored in the database file.

Include: foamdb.h

FoamDBDuplicateRecord()

MemHandle FoamDBDuplicateRecord(
        VMFileHandle    file,
        MemHandle       record);

Duplicates an existing record record of FoamDB file, assigns a new ID to it, and returns the handle of the duplicate.

Warning: As with FoamDBCreateEmptyRecord(), the record must eventually be saved or destroyed by calling FoamDBDiscardRecord() or FoamDBSaveRecord().

Include: foamdb.h

FoamDBFieldEnum()

Boolean FoamDBFieldEnum(
        MemHandle record, 
        void *enumData,
        PCB(Boolean, callback,  /* Non-zero to stop enum */
                (FieldHeader *field,  void *callbackEnumData)));      /* Callback routine */

This routine essentially "walks" through each field in the specified record and invokes the specified callback routine for each field. enumData can point to the initial value of an application-defined buffer or data structure if one is used by the callback routine, otherwise it can be ignored. This pointer is passed to the callback routine.

The callback routine accepts two parameters; a pointer to the current field field, and some application-defined data callbackEnumData. callbackEnumData may be used to store information between different calls to the callback routine such as storing the longest string yet found or performing complex filtering on the record (in which case callbackEnumData could point to an array of field IDs gathered from the field pointer). To end the enumeration before reaching the last field in the record, return TRUE (or any non-zero value) from the callback routine.

To use the callback routine:

/*
 * Prototype of callback routine
 */
Boolean _pascal ExampleCallback (FieldHeader *field, void *callbackEnumData);
...
/* 
 * Call FoamDBFieldEnum() 
 */
ok = FoamDBFieldEnum(recordHandle, &someDataStruct, ExampleCallback);

See Also: FoamDBLockedRecordEnum().

Include: foamdb.h