RecFile operations

Description

Record set files must be opened to use any functions on them:
b_isRecSetFile() – returns true if the file is of type record set file.
getVersion() – returns the version number of the file or 0 if none has been given.
getRec() – returns the index number of the current record set.
badRecs() – returns the number of invalid records within this file.
goodRecs() – returns the number of declared valid records in this file.
available() – returns the number of remaining bytes till the end of the current record.
availableRecs() – returns the remaining number of records that can be created before the file is full.
sizePerRecord() – returns the number of bytes per record as set during creation of the file (=size arg. in create() function)
totalRecords() – returns the total number of records that the file could hold (= nb_of_records argument in create() function)
newRec() – finalizes the current record, creates a new one at the end of the file and sets the write position to the beginning of this new record.
finalizeRec() – finalizes the current record so it is read-only now and it is safe to cut power without losing its data.
goFirstRec() – finalize the current record, goes to the first valid record of this file and sets the write/read position to its beginning.
goNextRec() – finalize the current record, goes to the next valid record and sets the write/read index to the beginning of it.
goLastRec() – finalize the current record, goes to the last valid record of this file and sets the write/read position to its beginning.
goPrevRec() – finalize the current record, goes to the previous valid record and sets the write/read index to the beginning of it.
sizeInFlash() – size that is reserved in the flash chip for this file (use size() on recSet files for the actual content size)
eraseTotal() – erases the entire content of the file including the RecSet header. This makes it a normal file.
close() – marks all open record sets valid and closes the file (the power could now safely be switch off)
Note: common file operations can be used on RecSet-files as well.

Syntax

if( file.b_isRecSetFile() ) file.getVersion(); file.getRec(); file.badRecs(); file.goodRecs(); file.available() file.availableRecs() file.sizePerRecord();
file.totalRecords();
file.newRec();
file.finalizeRec(); file.goFirstRec(); file.goNextRec();
file.goLastRec();
file.gpPrevRec(); file.sizeInFlash(); file.eraseTotal(); file.close();

Parameters

none

Returns

bool b_isRecSetFile() – true if it is a record set file; false if it is a normal file
uint32_t getVersion() – the file version number given during the create() command. 0 if none was given.
uint32_t getRec() – the number of the current record for read/write operations.
uint32_t badRecs() – the number of corrupted records in this file (e.g. cause by sudden power loss without closing() the file).
uint32_t goodRecs() – number of valid, successfully written records in this file.
uint32_t available() – number of remaining bytes from the current r/w-index ( see position() ) until the end of the record is reached.
uint32_t availableRecs() – number of remaining records that can be created within this file before the reserved space is full.
uint32_t sizePerRecord() – the number of bytes per record. As defined by the create() command.
uint32_t totalRecords() – the total number of records that the file could hold when full (includes the bad records as well).
uint32_t newRec() – 1: the new record could be created – 0: if no new record could be created (e.g. if the file is full).
uint32_t finalizeRec() – 1: record could successfully be closed (marked good) – 0: if was not a RecSet file, no open record etc.
uint32_t goFirstRec() – 1: OK, the first valid record is now the current – 0: error e.g. if no record was created yet.
uint32_t goNextRec() – 1: OK, the next valid record is now the current – 0: error e.g. if there are no further valid records in the file.
uint32_t goLastRec() – 1: OK, the last valid record is now the current – 0: error e.g. if there are no valid records in the file.
uint32_t goPrevRec() – 1: OK, gone backwards to the previous valid record which is now the current – 0: error e.g. if there are no previous valid records.
uint32_t sizeInFlash() – the total space in [bytes] that this file occupies in the flash chip (no matter if it holds real data yet or not).
void eraseTotal() – nothing (void)
void close()- nothing (void)

Example Code

#include "SerialFlash.h"
void setup()
{
  char c;
  while(!Serial);
  SerialFlash.begin();
  // create a RecSet file with 10 records of 15 bytes each; file version 123
  if( SerialFlash.create("myRecSetFile.txt", 15, 10,123) )
    Serial.println("RecSet file created");

  SerialFlashFile file = SerialFlash.open("myRecSetFile.txt");
  while(file.read(&c, 1) > 0)
    Serial.write(c);
  Serial.println("\n - EOF -");

  if( file.newRec() ) 
  {
    c = 0x30 + file.getRec();
    while( file.write(&c, 1) ); // write until the end of the record
  }
  file.close();
  while(1){ yield(); };
}
void loop () 
{ }

^{see examples in the Arduino menu: File -> Examples -> SerialFlash}

Notes and Warnings

Record-set files have to be closed() in order to mark all successfully written records in the file as valid before shutting down the device.