08. Storage

The storage object is a built-in object that provides functions to read and write data to the user area in non-volatile memory.

Functional overview:

  • Provides text data reading and writing functions.
  • Provides binary data reading and writing functions.

Limitations:

  • The maximum data size that can be used in the text data storage area (MemBlock) is 1306KB.
  • The data size that can be used in the binary data storage area (RawMemBlock) is 16KBx16 blocks.


storage Global Object

Methods()/PropertiesSummaryVersionNote
storage.open()Creates a {MemBlock} instance.
storage.rawOpen()Creates a {RawMemBlock} instance.


Details

storage.open([blockNo])

The storage is opened and a {MemBlock} instance is created.

NameTypeM/OSummaryNote
blockNonumberoptional{MemBlock} identifier
Creates an instance corresponding to the specified number.
Range: 0
The default value is 0.		Only 0 can be used.
return{MemBlock}-{MemBlock} : Generated {MemBlock}When an error occurs, an exception is raised.

storage.rawOpen([blockNo])

The storage is opened and a {RawMemBlock} instance is created.

NameTypeM/OSummaryNote
blockNonumberoptional{RawMemBlock} identifier
Creates an instance corresponding to the specified number.
Range: 0 - 15
The default value is 0.
return{RawMemBlock}-{RawMemBlock} : Generated {RawMemBlock}When an error occurs, an exception is raised.


{MemBlock}

This object is generated internally and returned by storage.open().
This object provides a text-based FIFO access function to the non-volatile memory block.
After that, until .close() is called, memory access is permitted.

Methods()/PropertiesSummaryVersionNote
.getReadableSize()Gets the readable size in the specified memory block.
.getBlockSize()Gets the size of the specified memory block.
.write()Writes data to the memory block.
.writeFrame()Writes data to the memory block in the dedicated frame format managed by the frame identifier.
.read()Reads data from the memory block.
.readFrame()Reads the data corresponding to the specified frame identifier from the memory block.
.searchFrame()Searches for the frame with the specified identifier.
.recoverFrame()Performs recovery so that the data corresponding to the specified frame identifier becomes the first frame of the memory block.
.searchAllFrame()Searches all data corresponding to the specified frame identifier from the first frame of the memory block.
.remove()Erases the data from the top position of the readable data in the memory block.
.removeFrame()Erases the read first frame.
.reset()Resets the specified memory block.
.erase()Erases the specified memory block completely.
.close()Closes the specified memory block.


Details

.getReadableSize()

Gets the readable size in the specified memory block.

NameTypeM/OSummaryNote
returnnumber-Readable size [byte]

.getBlockSize()

Gets the size of the specified memory block.
This means the maximum size that can be written.

NameTypeM/OSummaryNote
returnnumber-Memory block capacity [byte]

.write(data[,size[,pad]])

Writes data to the memory block.

NameTypeM/OSummary                                      Note
datastringmandatoryData to be written
sizenumberoptionalSize of the data to be writtenIf the specified size exceeds the write data length, padding is performed.
padstringoptionalSpecify the padding character (1byte).
The default value is '`' (backtick).
returnnumber-Size of the written data [byte]If writing fails, 0 is returned. In that case, use .getReadableSize() and .getBlockSize() to check the remaining writable size.

.writeFrame(header,data)

Writes data to the memory block in the dedicated frame format managed by the frame identifier.

Data writing in dedicated frame format using .writeFrame() and data writing using .write() cannot be mixed in the same memory block. Therefore, if you use .writeFrame(), do not use .write().

NameTypeM/OSummary                                      Note
headerstringmandatoryFrame identifier
Specify an arbitrary name to identify the frame.
(1 - 7 characters)
datastringmandatoryData to be written
returnnumber-Size of the written frame [byte]The frame size is the sum of the written data length and the 24-byte frame overhead length.
If writing fails, 0 is returned. In that case, use .getReadableSize() and .getBlockSize() to check the remaining writable size.

.read(size,offset)

Reads data from the memory block.

NameTypeM/OSummary                                      Note
sizenumbermandatorySize of the data to read [byte]
offsetnumbermandatoryRead start offset [byte]
returnstring, null-Read dataThe read data is read from the start position specified by the offset to the specified data size or the range in which the data exists.
If there was no data to be read, returns null.

.readFrame(header,flag)

Reads the data corresponding to the specified frame identifier from the memory block.

NameTypeM/OSummary                                      Note
headerstringmandatoryFrame identifier
Specify the frame identifier of the target data.
flagnumbermandatoryRead flag
0: Only read the first frame
1(≠0): Read and delete the first frame
returnstring, null, undefined-Read dataIf no data exists null is returned. If the frame is broken or any other abnormality is detected, undefined is returned.

.searchFrame(header,index)

Searches the data corresponding to the specified frame identifier from the first frame of the memory block.

NameTypeM/OSummary                                      Note
headerstringmandatoryFrame Identifier
Specify the frame identifier of the target data.
indexnumberoptionalSearch Frame index
Range: 0 - (N-1)
The default value is 0.		N: Total number of detected frames that can be acquired by .searchAllFrame().
returnstring, null, undefined-The detected read dataIf no data exists null is returned. If the frame is broken or any other abnormality is detected, undefined is returned.

.recoverFrame(header)

Performs recovery so that the data corresponding to the specified frame identifier becomes the first frame of the memory block.
Use when a broken frame is detected; i.e, .readFrame() or .searchFrame() return undefined.
Use only if recovery is required. Otherwise, valid frames may be erased.

NameTypeM/OSummary                                      Note
headerstringmandatoryFrame Identifier
Specify the frame identifier of the target data.
returnnumber, undefined-number : Data size erased for recovery [byte]
undefined : Unrecoverable		If this returns undefined, the memory is unrecoverable, and .reset() must be used.

.searchAllFrame(header,retType)

Searches all data corresponding to the specified frame identifier from the first frame of the memory block.

NameTypeM/OSummary                                      Note
headerstringmandatoryFrame Identifier
Specify the frame identifier of the target data.
retTypenumberoptionalSpecify the return type.
The default value is 0.
0: Total size of data in all detected frames [byte]
1: Total number of detected frames
returnnumber, undefined-The specified valueIf the frame is broken or any other abnormality is detected, undefined is returned.

.remove(size)

Erases the data from the top position of the readable data in the memory block.

NameTypeM/OSummaryNote
sizenumbermandatoryData size to delete [byte]
returnundefined--

.removeFrame()

Erases the read first frame.
You cannot erase by specifying the frame identifier.
'The first frame read' means frame data read using .readFrame(), but does not include frame data read using .searchFrame().

NameTypeM/OSummaryNote
returnundefined--

.reset()

Resets the specified memory block.
It returns to the state where there is no read data.

NameTypeM/OSummaryNote
returnundefined--

.erase()

Erases the specified memory block completely.
It takes several tens of seconds time to erase completion.

NameTypeM/OSummaryNote
returnundefined--

.close()

Closes the specified memory block.

NameTypeM/OSummaryNote
returnundefined--


{RawMemBlock}

This object is generated internally and returned by storage.rawOpen().
This object provides the low-level access interface to the non-volatile memory block.
After that, until .close() is called, memory access is permitted.

Methods()/PropertiesSummaryVersionNote
.getBlockSize()Gets the size of the specified memory block.
.write()Writes data to the memory block.
.append()Appends data to the memory block.
.writeFrame()Writes data to the memory block in the dedicated frame format managed by the frame identifier.
.appendFrame()Appends data to the memory block in the dedicated frame format managed by the frame identifier.
.read()Reads data from the memory block.
.readBin()Reads data in binary from memory block.
.searchFrame()Searches the data corresponding to the specified frame identifier from the first frame of the memory block.
.searchBinFrame()Searches the data corresponding to the specified frame identifier from the first frame of the memory block and reads data in binary.
.erase()Erases the specified memory block completely.
.close()Closes the specified memory block.


Details

.getBlockSize()

Gets the size of the specified memory block.

NameTypeM/OSummaryNote
returnnumber-Memory block capacity [byte]

.write(data,offset)

Writes data to the memory block.
The data in the memory block is completely erased once before writing.

NameTypeM/OSummary                                      Note
datastring, ArrayBuffermandatoryData to be written
offsetnumbermandatoryWrite start offset [byte]
returnnumber-Size of the written data [byte]If writing fails, 0 is returned.

.append(data,offset)

Appends data to the memory block.
Basically, the position where the data has not been written is specified by the offset and used.

NameTypeM/OSummary                                      Note
datastring, ArrayBuffermandatoryData to be written
offsetnumbermandatoryWrite start offset [byte]
returnnumber-Size of the written data [byte]If writing fails, 0 is returned.

.writeFrame(header,data,offset)

Writes data to the memory block in the dedicated frame format managed by the frame identifier.
The data in the memory block is completely erased once before writing.

NameTypeM/OSummary                                      Note
headerstringmandatoryFrame identifier
Specify an arbitrary name to identify the frame.
(1 - 8 characters)
datastring, ArrayBuffermandatoryData to be written
offsetnumbermandatoryWrite start offset [byte]
returnnumber-Size of the written frame [byte]The frame size is the sum of the written data length and the 16-byte frame overhead length.
If writing fails, 0 is returned.

.appendFrame(header,data,offset)

Appends data to the memory block in the dedicated frame format managed by the frame identifier.
The position where the frame data has not been written is specified by the offset and used.

NameTypeM/OSummary                                      Note
headerstringmandatoryFrame identifier
Specify an arbitrary name to identify the frame.
(1 - 8 characters)
datastring, ArrayBuffermandatoryData to be written
offsetnumbermandatoryWrite start offset [byte]
returnnumber-Size of the written frame [byte]The frame size is the sum of the written data length and the 16-byte frame overhead length.
If writing fails, 0 is returned.

.read(size,offset)

Reads data from the memory block.

NameTypeM/OSummary                                      Note
sizenumbermandatorySize of the data to read [byte]
offsetnumbermandatoryRead start offset [byte]
returnstring, null, undefined-Read dataThe read data is read from the start position specified by the offset to the specified data size or the range in which the data exists (Version 02.01.00+).
If there was no data to be read, returns null.
If non-character data is detected, returns undefined.

.readBin(size,offset)

Reads data in binary from memory block.

NameTypeM/OSummary                                      Note
sizenumbermandatorySize of the data to read [byte]
offsetnumbermandatoryRead start offset [byte]
returnArrayBuffer, null-Read dataThe read data is read from the start position specified by the offset to the specified data size.
If there was no data to be read, returns null.

.searchFrame(header)

Searches the data corresponding to the specified frame identifier from the first frame of the memory block.

NameTypeM/OSummary                                      Note
headerstringmandatoryFrame Identifier
Specify the frame identifier of the target data.
returnstring, null, undefined-The detected read dataIf no data exists null is returned. If the frame is broken or any other abnormality is detected, undefined is returned.

.searchBinFrame(header)

Searches the data corresponding to the specified frame identifier from the first frame of the memory block and reads data in binary.

NameTypeM/OSummary                                      Note
headerstringmandatoryFrame Identifier
Specify the frame identifier of the target data.
returnArrayBuffer, null, undefined-The detected read dataIf no data exists null is returned. If the frame is broken or any other abnormality is detected, undefined is returned.

.erase()

Erases the specified memory block completely.

NameTypeM/OSummaryNote
returnundefined--

.close()

Closes the specified memory block.

NameTypeM/OSummaryNote
returnundefined--


Object Usage Examples

Sample 1

This is a sample of reading and writing frames.

var mb = storage.open();  
var FRAME_TYPE = 'Sample';
var str = 'abcdefg';
mb.writeFrame(FRAME_TYPE, str);

var r_u_data = mb.readFrame(FRAME_TYPE, 1);
print('r_u_data=' + r_u_data);

mb.close();

Sample 2

This is a sample of frame write and frame read with different headers.

var mb = storage.open();
var FRAME_TYPE_1 = 'type1';
var FRAME_TYPE_2 = 'type2';
var w_len;
var w_str;

w_str = 'abcdefg';
w_len = mb.writeFrame(FRAME_TYPE_1, w_str);
var w_str = '1234567890';
w_len = mb.writeFrame(FRAME_TYPE_2, w_str);

var r_u_data;
var frame_type = FRAME_TYPE_2;
  r_u_data = mb.searchFrame(frame_type);
  if(typeof r_u_data == 'string'){
    print('found r_u_data=' + r_u_data);
  }else{
    if (r_u_data === null){
      print('none data');
    }else{
      print('read fail -> reset');
      mb.reset();
    }
  }

mb.close();

Sample 3

This is a sample to try recovery when a broken frame is detected.

var mb = storage.open();  

var FRAME_TYPE = 'sample';
var w_len;
var w_str;

w_str = 'abcdefg';
w_len = mb.writeFrame(FRAME_TYPE, w_str);

var w_str = '1234567890';
w_len = mb.writeFrame(FRAME_TYPE, w_str);

var r_u_data;
var frame_type = FRAME_TYPE;
while(mb.getReadableSize()){
  r_u_data = mb.readFrame(frame_type, 0);
  if(typeof r_u_data == 'string'){
    print('r_u_data=' + r_u_data);
    mb.removeFrame();
  }else{
    if (r_u_data === undefined) {
      print('data broken');
      var ret = mb.recoverFrame(frame_type);
      if (ret === undefined) {
        print('recover fail');
        mb.reset();
      } else {
        print('recover success ' + ret);
      }
    }
  }
}
print('finish reading frames!\n')

mb.close();

Sample 4

This is a sample of reading and writing data using {RawMemBlock}.

var rawmb = storage.rawOpen(3);
var w_idx = 0;
var header1 = 'option1';
w_idx += rawmb.writeFrame(header1, '10000', w_idx); //data offset
print('total written size=' +  w_idx);

var header2 = 'option2';
w_idx += rawmb.appendFrame(header2, '12', w_idx); //data offset
print('total written size=' +  w_idx);

var header3 = 'option3';
w_idx += rawmb.appendFrame(header3, '2018', w_idx); //data offset
print('total written size=' +  w_idx);

var r_u_data;
r_u_data = rawmb.searchFrame(header1); //size offset
print(typeof r_u_data + ':' + header1 + ':' + r_u_data);

r_u_data = rawmb.searchFrame(header2); //size offset
print(typeof r_u_data + ':' + header2 + ':' + r_u_data);

r_u_data = rawmb.searchFrame(header3); //size offset
print(typeof r_u_data + ':' + header3 + ':' + r_u_data);

rawmb.close();

Sample 5

This is a sample of reading and writing frames.
The table below shows the flow of data in the memory block when this sample is executed.

var mb = storage.open(0);
print('mb:', mb.getReadableSize(), '/', mb.getBlockSize());
if(mb.getReadableSize()){
    mb.erase();
}
mb.writeFrame('tag', 'data1');
mb.writeFrame('tag', 'data2');
mb.writeFrame('tag', 'data3');
while(1) {
    var str = mb.readFrame('tag', 0);   //0:Only read.
    if(null === str) {
        print('No data');
        break;
    } else if(undefined === str) {
        print('Broken frame');
        break;
    }
    print(str);
    mb.removeFrame();
}
stepmethodmemory blockread data
1.erase()
2.writeFrame('tag', 'data1')['tag', 'data1']
3.writeFrame('tag', 'data2')['tag', 'data1'] ['tag', 'data2']
4.writeFrame('tag', 'data3')['tag', 'data1'] ['tag', 'data2'] ['tag', 'data3']
5.readFrame('tag', 0)['tag', 'data1'] ['tag', 'data2'] ['tag', 'data3']'data1'
6.removeFrame()['tag', 'data2'] ['tag', 'data3']
7.readFrame('tag', 0)['tag', 'data2'] ['tag', 'data3']'data2'
8.removeFrame()['tag', 'data3']
9.readFrame('tag', 0)['tag', 'data3']'data3'
10.removeFrame()
11.readFrame('tag',0)null

Sample 6

This is a sample of frame write and frame read with different headers.
The table below shows the flow of data in the memory block when this sample is executed.

var mb = storage.open(0);
print('mb:', mb.getReadableSize(), '/', mb.getBlockSize());
if(mb.getReadableSize()){
    mb.erase();
}
mb.writeFrame('tag1', 'data1');
mb.writeFrame('tag2', 'data2');
mb.writeFrame('tag3', 'data3');

while(1) {
    if(0 == mb.getReadableSize()) {
        break;
    }
    var tag;
    var str = null;
    if(null === str) {
        tag = 'tag3';
        str = mb.readFrame(tag, 0);
    }
    if(null === str) {
        tag = 'tag2';
        str = mb.readFrame(tag, 0);
    }
    if(null === str) {
        tag = 'tag1';
        str = mb.readFrame(tag, 0);
    }
    if(null === str) {
        print('No data');
        break;
    }
    if(undefined === str) {
        print('Broken frame');
        break;
    }
    print(tag, ':', str);
    mb.removeFrame();
}
stepmethodmemory blockread data
1.erase()
2.writeFrame('tag1', 'data1')['tag1', 'data1']
3.writeFrame('tag2', 'data2')['tag1', 'data1'] ['tag2', 'data2']
4.writeFrame('tag3', 'data3')['tag1', 'data1'] ['tag2', 'data2'] ['tag3', 'data3']
5.readFrame('tag3', 0)['tag1', 'data1'] ['tag2', 'data2'] ['tag3', 'data3']null
6.readFrame('tag2', 0)['tag1', 'data1'] ['tag2', 'data2'] ['tag3', 'data3']null
7.readFrame('tag1', 0)['tag1', 'data1'] ['tag2', 'data2'] ['tag3', 'data3']'data1'
8.removeFrame()['tag2', 'data2'] ['tag3', 'data3']
9.readFrame('tag3', 0)['tag2', 'data2'] ['tag3', 'data3']null
10.readFrame('tag2', 0)['tag2', 'data2'] ['tag3', 'data3']'data2'
11.removeFrame()['tag3', 'data3']
12.readFrame('tag3', 0)['tag3', 'data3']'data3'
13.removeFrame()


Updated: 2023-09-28
← 07. Secure09. Sleep →