DataStoreDataError DataStoreNewRecord( word dsToken); /* session token to opened datastore */
Creates a new (empty) record and makes it the current record. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
Warnings: A new record becomes a permanent part of the datatstore only after it is saved (with
DataStoreSaveRecord()
).
Include: datastor.h
DataStoreError DataStoreOpen( TCHAR *dsNamePtr, optr notifyObject, DataStoreOpenFlags openFlag, word *dsTokenPtr);
Opens the datastore referenced by
dsNamePtr
and writes the session token to
dsTokenPtr
. Passing DSOF_EXCLUSIVE in
openFlag
opens the datastore with access restricted to the caller; if another application already has the datastore open, returns DSE_ACCESS_DENIED. Passing NullOptr in
notifyObject
means no object will receive GWNT_DATASTORE_CHANGE notifications. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h
DataStoreError DataStoreRecordEnum( word dsToken, RecordNum *startRecordPtr, DataStoreRecordEnumFlags flags, void *enumDataPtr, Boolean _pascal (*CallbackRoutine) ( RecordHeader record, void *enumDataPtr));
Enumerates through the records of a datastore in storage order. When CallbackRoutine returns TRUE, stops enumeration, updates
startRecordPtr
with the
RecordNum
of the last record examined, and returns DSE_NO_ERROR. (To continue enumeration, increment
startRecordPtr
.) Returns DSE_NO_MORE_RECORDS if first or last record is reached.
Takes the following arguments:
RecordNum
at which to start enumeration (unless DSREF_START_AT_END is passed [in flags] in which case this argument is ignored).
DataStoreRecordEnumFlags
to pass. Passing DSREF_BACKWARDS causes enumeration to go backwards. Passing DSREF_START_AT_END with DSREF_BACKWARDS causes enumeration to go backwards starting at the last record. (Passing DSREF_START_AT_END without DSREF_BACKWARDS causes enumeration to start at the first record, ignoring whatever value is in startRecordPtr.)
RecordHeader
of the current record and enumDataPtr. Returning TRUE ends enumeration.Warnings: Callback can modify data passed in enumDataPtr but cannot modify any actual data in the record.
Datastore cannot be modified during enumeration.
Include: datastor.h
See Also: DataStoreFieldEnum()
,DataStoreStringSearch()
.
DataStoreDataError DataStoreRemoveFieldFromRecord( word dsToken, /* session token to opened datastore */ TCHAR *fieldNamePtr, FieldID fieldID);
Deletes the passed field from the current record. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
If referencing field by name, pass "0" in
fieldID
; if referencing field by
FieldID
, pass NULL in
fieldNamePtr
.
Include: datastor.h
See Also: DataStoreDeleteField()
.
DataStoreError DataStoreRename( TCHAR *oldNamePtr, TCHAR *newNamePtr);
Changes the name of a datastore from
oldNamePtr
to
newNamePtr
. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h
DataStoreStructureError DataStoreRenameField( word dsToken, /* session token to opened datastore */ TCHAR *newNamePtr, TCHAR *oldNamePtr, FieldID fieldID);
Changes the name of a field from
oldNamePtr
to
newNamePtr
. Returns a
DataStoreStructureError
value (DSSE_NO_ERROR if successful).
If referencing field by name, pass "0" in
fieldID
; if referencing field by
FieldID
, pass NULL in
oldNamePtr
.
Warnings: Returns DSSE_FIELD_NAME_TOO_LONG if new name exceeds MAX_FIELD_NAME_LENGTH ( i.e. , 40 * sizeof(TCHAR)).
Include: datastor.h
DataStoreDataError DataStoreSaveRecord( word dsToken, void *dataPtr, sword _pascal (*CallbackRoutine) ( RecordHeader *Rec1Ptr, RecordHeader *Rec2Ptr, word dsToken, void *dataPtr), RecordNum *recordNumPtr, RecordID *recordIDPtr);
Writes the current record to the datastore (saving any changes made to the record) and flushes the record from the buffer. If CallbackRoutine is "0", inserts saved record to the key (if a key exists) or appends the record to the end of the datastore if no key exists. Writes the
RecordNum
and
RecordID
of the saved record to recordNumPtr and recordIDPtr, respectively. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful). Takes the following arguments:
RecordHeader
s of two records to compare. Caller can also pass extra data with dataPtr. The function should return:
RecordNum
of saved record.
RecordID
of saved record.Include: datastor.h
See Also: DataStoreDiscardRecord()
.
DataStoreError DataStoreSetExtraData( word dsToken, /* session token to opened datastore */ void *extraDataPtr, /* data to write to file header */ word extraDataSize);
Writes
extraDataSize
bytes of extra data to the datastore file header, replacing any existing extra data. Passing "0" in
extraDataSize
deletes any existing extra data. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h