DataStore Library: 2.2 Creating a DataStore: Adding Records

GEOS SDK TechDocs

2.1 Adding Fields

2.3 Deleting Records

DataStoreOpen(), DataStoreNewRecord(), DataStoreSetField(), DataStoreSaveRecord()

To manage synchronization between applications accessing the same datastore, the DataStore Manager creates a "session" each time an application opens a datastore with DataStoreOpen() . Each session has its own "record buffer;" to modify a record, you must load it into the record buffer first. The loaded record is called the "current record." There can only be one record loaded in the buffer at a time. DataStoreNewRecord() adds a new record and makes that record the "current record."

To write to a record, call DataStoreSetField() . When you write to a record, you are actually writing to a copy of the record loaded in the record buffer. Any changes made to this copy do not become permanent until you call DataStoreSaveRecord() . To cancel changes, call DataStoreDiscardChanges() . Both routines flush the current record from the buffer.

Most routines that access fields (such as DataStoreSetField() ) take both a FieldID and a field name as parameters. You can reference the field by either parameter. To reference a field by its name, pass its name in the name parameter and zero in the FieldID parameter. To reference a field by its FieldID , pass its FieldID in the FieldID parameter andNULL in the name parameter. Fields are numbered from zero. (There are routines for obtaining the FieldID corresponding to a given field name and vice versa; see DataStoreFieldNameToID() and DataStoreFieldIDToName() in the C Reference Book.)

The following code example shows how to open an existing datastore, add a new record, and write data to two of its fields.

Code Display 9-2 Adding a Record to a DataStore

	/* Opening a datastore returns a token. */
	word			dsToken;

	/*
	 * Saving changes to a record returns both the record's RecordNum
	 * and RecordID
	 */
	RecordID			recordID;
	RecordNum			recordNum;

	/* 
	 * Open the "Exchange Rates" datastore with sharable access
	 * (i.e., no flag passed). "Oself" refers to the object which is to
	 * receive change notifications; in this case, assume oself refers to
	 * the process class.
	 */
	if(DataStoreOpen("Exchange Rates", oself, 0, &dsToken) == DSE_NO_ERROR)
	{
		/* Add a new record. */
		if(DataStoreNewRecord(dsToken) == DSDE_NO_ERROR)
		{
			/* 
			 * Write data to the country and exchange rate fields.
			 * You can refer to a field by its name or FieldID;
			 * the examples below show both methods. 
			 */
			TCHAR			countryBuffer[] = "Albania";

			/* refer to a field by its name */
			DataStoreSetField(dsToken, "country", 0, countryBuffer,
							strlen(countryBuffer));

			FloatNum			rateBuffer = .9234;

			/* refer to a field by its FieldID */
			DataStoreSetField(dsToken, NULL, 3, &rateBuffer,
							sizeof(rateBuffer));

			/* Save the record. */
			DataStoreSaveRecord(dsToken, 0, 0, &recordNum, &recordID);
		}
		/* Close the datastore. */
		DataStoreClose(dsToken);
	}

DataStoreSaveRecord() writes the RecordNum and RecordID of the saved record to the passed variables. A record's RecordNum is its relative place in the datastore; this value may change when records are added or deleted. A record's RecordID is its unique identifier and does not change. RecordNums are numbered from zero; RecordIDs are numbered from one.

You can use a callback function with DataStoreSaveRecord() to specify where in the datastore the record is to be saved. The calling routine passes the record to be inserted (rec1) and a record from the datastore (rec2) to the callback; the callback decides which of the two records comes before the other. (The callback cannot modify the records, however.)

The callback should return a value greater than zero if rec1 comes before rec2; otherwise, a value less than zero. Declaration of Callback Function in DataStoreSaveRecord() shows the declaration of the callback.

Code Display 9-3 Declaration of Callback Function in DataStoreSaveRecord()

sword SortCallback(RecordHeader *rec1, RecordHeader *rec2,
						word dsToken, void *cbData);

The actual data in the record follows the RecordHeader . Use DataStoreGetFieldPtr() or DataStoreFieldEnum() to access fields within the records.

typedef struct {
	RecordID	RH_uniqueID;
	byte	RH_fieldCount; /* # of fields */
	word	RH_size; /* # of bytes */
} RecordHeader;

If you do not specify a callback routine in DataStoreSaveRecord() , it will insert the record according to values in the key field(s). If two records have matching values in one key field, they will be inserted according to the first non-matching key field value. Records with matching key field(s) values are stored in the order they are added. Records with empty key fields are inserted at the beginning of the file.

If there is no callback or key, records are added to the end of the file.

GEOS SDK TechDocs

2.1 Adding Fields

2.3 Deleting Records