FoamDBGetCurrentRecordID()

RecordID FoamDBGetCurrentRecordID(
	VMFileHandle 	file);

Returns the RecordID that would be set for the next record in the database file.

Include: foamdb.h

FoamDBGetFieldData()

 word FoamDBGetFieldData(
        VMFileHandle    file, 
        MemHandle       record, 
        FieldID             id, 
        char            *dest,      /* Buffer to store data */
        word            maxBytesToGet);      /* # bytes of data */

Copies the data from the specified field of record into the buffer dest. maxBytesToGet specifies the maximum number of bytes to copy into the buffer.

Returns the number of bytes actually copied.

Warning: The standard and most efficient way to store string data is without a null terminator, so when working with string data be sure to use the returned data size.

Include: foamdb.h

FoamDBGetFieldName()

Boolean FoamDBGetFieldName(
	VMFileHandle    file, 
	MemHandle       record, 
	FieldID            id, 
	TCHAR   *dest,     /* Buffer to put name (null-terminated) */
	word            maxBytesToGet);     /* Number of characters to get */

Copies the name of the field ID id into the buffer dest.

Returns zero if field exists, non-zero if it doesn't.

Warning: Field names are null-terminated.

Include: foamdb.h

FoamDBGetFieldType()

 Boolean FoamDBGetFieldType(
        VMFileHandle    file, 
        MemHandle       record, 
        FieldID            id, 
        byte            *type);

Gets the type of field ID id and puts it into type. Note that this type is a ContdbFieldType.

Returns zero if field exists, non-zero if it does not.

Include: foamdb.h

FoamDBGetNextPrevRecord()

dword FoamDBGetNextPrevRecord(
	VMFileHandle 	file, 
	RecordID 	record,
	word 		count);

This routine returns the index into the huge array of a record count records away from the record with the RecordID record. count can be negative or positive, so this routine lets you move forwards or backwards through the database. Should the requested record be invalid, either because there is no record with RecordID record or the requested index is beyond the bounds of the database, this routine will return record.

Include: foamdb.h

FoamDBGetNumVisibleRecords()

dword	FoamDBGetNumVisibleRecords(
	VMFileHandle 	file);

This routine returns the number of visible records in the database file. This is often used when providing a list of records to a user.

Include: foamdb.h

FoamDBGetRecordFromID()

MemHandle FoamDBGetRecordFromID(
	VMFileHandle 	file, 
	RecordID 	id);

This routine looks for a record in the database with the ID id, copies it into memory, and returns the handle. If no record in the database had the passed ID, this routine returns NullHandle.

Warning: The handle returned should be freed using FoamDBDeleteRecord(), FoamDBDiscardRecord(), or FoamDBSaveRecord().

Include: foamdb.h

FoamDBGetRecordID()

RecordID FoamDBGetRecordID(
        MemHandle       record);

Given a record handle, returns the RecordID of the record.

Include: foamdb.h

FoamDBGetVisibleRecord()

MemHandle FoamDBGetVisibleRecord(
	VMFileHandle 	file, 
	dword 	index);

This routine finds the visible record with the index of index, copies the data into memory, and returns the handle of the block to the caller. If index is out of bounds, FoamDBGetVisibleRecord() returns NullHandle.

Warning: The handle returned should be freed using FoamDBDeleteRecord(), FoamDBDiscardRecord(), or FoamDBSaveRecord().

Include: foamdb.h

FoamDBLockedRecordEnum()

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

This routine calls a callback routine for each field in a locked down record. The callback routine is used the same way as in FoamDBFieldEnum(). It should be of the prototype

/*
 * Prototype of callback routine
 */
Boolean _pascal ExampleCallback (FieldHeader *field, void *callbackEnumData);

Include: foamdb.h

FoamDBMapNameToToken()

Boolean FoamDBMapNameToToken(
	VMFileHandle 	file, 
	TCHAR 	*nameToLookFor, 
	word 	*token);

This routine looks up the field named nameToLookFor in the database file and checks to see if any fields have that name.

Returns TRUE (-1) if found, FALSE (0) if not found. token will be the index to the element within the FieldName element array. This is not something that will normally be used by an application.

Include: foamdb.h

FoamDBMapTokenToName()

Boolean FoamDBMapTokenToName(
	VMFileHandle file, 
	word nameToken, 
	word maxBytesToCopy, 
	TCHAR *dest);

This routine finds the field name associated with the token nameToken in the database file file, and copies at maximum maxBytesToCopy bytes of that name into the buffer dest. The routine returns non-zero if the token was out of bounds.

Warning: Field names are null-terminated.

Include: foamdb.h

FoamDBOpen()

VMFileHandle  FoamDBOpen(
        char *filename,         
        word mapBlockSize, 
        word majorProtocol,    /* Existing file protocol must match major and minor protocols */
        word minorProtocol);

Opens an existing database file filename, or creates a new one if it does not currently exist. Returns the handle of the database file or NullHandle if the file could not be opened. ThreadGetError() can be called to return the error type, which is the error returned from VMOpen(), or -1 if there was a protocol mismatch.

mapBlockSize is used to specify the size of the map block for the database. The default (minimum) size is sizeof(FoamDBMap), but more space can be allocated if the application needs to store extra data in the map block.

When creating a new file, the new file will be assigned the protocol number passed in majorProtocol and minorProtocol. When opening an existing file, the protocol number of the file is compared against the protocol number passed in majorProtocol and minorProtocol, and if they do not match, an error of -1 is returned.

Include: foamdb.h

FoamDBResortDatabase()

void FoamDBResortDatabase(
	VMFileHandle file, 
	PCB(sword, callback,
		(RecordHeader *record1, RecordHeader *record2)));   /* Callback Routine */

This routine resorts the database file using the application-defined callback function to determine record order. As with the routine FoamDBSaveRecord(), the callback routine should return -1 if record1 should come before record2, or +1 if record1 should come after record2 in the database. The prototype for the callback routine should look like:

sword _pascal MyCallBackRoutine(RecordHeader *record1, RecordHeader *record2);

Include: foamdb.h

FoamDBResumeNotifications()

void FoamDBResumeNotifications(
	VMFileHandle 	file);

This routine resumes the generation of notifications for the database file. These notifications are FoamDBActionTypes.

See Also: FoamDBSuspendNotifications().

Include: foamdb.h