create() – di-ce.de

Description

create() this function must be called to create a new file. Once created, files can never be renamed or deleted. The file’s size can never change. Writing additional data can NOT grow the size of file. The actual space taken on flash is determined by the automatic increase of size to the nearest number of erasable blocks, resulting in a file that may be 4K to 128K larger than requested.
Hints:
Use recreate() – reclaims the memory space if the file existed before.
Simulate writing ( getWriteCounter() ) to determine the actually required size of the file before creating it

Syntax

create( filename, length ); – creates a ‘normal’ file.
create( filename, length, nb_of_records ); – creates a ‘record set’ file consisting of nb_of_records x length p. record.
create( filename, length, nb_of_records, file_version ); – creates a ‘record set’ file and gives it a version number

Parameters

char* filename – pointer a zero-terminated char array holding the file name
uint32_t length – size of the file (normal) or the size of each ‘record’ (for record-set file)
uint32_t nb_of_records – number of records each of length bytes. (this parameter >0 makes it a RecSet type file)
uint32_t file_version – a version number (or 0) of the file

Returns

bool:
– true if the file could be created
– false if not

Example Code

#include "SerialFlash.h"
void setup()
{
  while(!Serial);
  SerialFlash.begin();
  if( SerialFlash.create("myFile.txt", 1024) == false )
    Serial.println("Normal file could NOT be created");

  if( SerialFlash.create("myFileRecSet.txt", 16, 1000, 123) == false )
    Serial.println("RecSet file could NOT be created");
}
void loop () 
{ }

^{see example ‘File -> Examples -> SerialFlash -> ListFileDetails’ for the result of the example code above}

Notes and Warnings

By applying a third parameter (nb_of_records > 0) a file of type record-set will be created (instead of a normal file). This type can be helpful if the actual size of the file matters, e.g. for binary data. It might also be important when it comes to interpreting or transferring (e.g. via CAN2SER, internet) files. In cases like this, simply use nb_of_records = 1.
Another use case for recordset files are for logging data in predictable chunks e.g. logging CAN messages or GPS coordinates etc. Recordset files provide an automatic bad-block management. Corrupted blocks (records) due to sudden lost of power are automatically marked ‘bad’ and will be ignored when the file is read or continued.
Simulated writing: Find an example in the Arduino IDE example menu:
DICE->dice-GNSS->Tracker and in SerialFlash-> SimulateBeforeWriteFile