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 16320KB.
• The data size that can be used in the binary data storage area (RawMemBlock) is 32KBx32 blocks.

---

storage Global Object

Methods()/Properties	Summary	Version	Note
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.

Name	Type	M/O	Summary	Note
blockNo	number	optional	{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.

Name	Type	M/O	Summary	Note
blockNo	number	optional	{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()/Properties	Summary	Version	Note
.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.

Name	Type	M/O	Summary	Note
return	number	-	Readable size [byte]

.getBlockSize()

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

Name	Type	M/O	Summary	Note
return	number	-	Memory block capacity [byte]

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

Writes data to the memory block.

Name	Type	M/O	Summary	Note
data	string	mandatory	Data to be written
size	number	optional	Size of the data to be written	If the specified size exceeds the write data length, padding is performed.
pad	string	optional	Specify the padding character (1byte). The default value is '`' (backtick).
return	number	-	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().

Name	Type	M/O	Summary	Note
header	string	mandatory	Frame identifier Specify an arbitrary name to identify the frame. (1 - 7 characters)
data	string	mandatory	Data to be written
return	number	-	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.

Name	Type	M/O	Summary	Note
size	number	mandatory	Size of the data to read [byte]
offset	number	mandatory	Read start offset [byte]
return	string, null	-	Read data	The 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.

Name	Type	M/O	Summary	Note
header	string	mandatory	Frame identifier Specify the frame identifier of the target data.
flag	number	mandatory	Read flag 0: Only read the first frame 1(≠0): Read and delete the first frame
return	string, null, undefined	-	Read data	If 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.

Name	Type	M/O	Summary	Note
header	string	mandatory	Frame Identifier Specify the frame identifier of the target data.
index	number	optional	Search Frame index Range: 0 - (N-1) The default value is 0.	N: Total number of detected frames that can be acquired by .searchAllFrame().
return	string, null, undefined	-	The detected read data	If 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.

Name	Type	M/O	Summary	Note
header	string	mandatory	Frame Identifier Specify the frame identifier of the target data.
return	number, 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.

Name	Type	M/O	Summary	Note
header	string	mandatory	Frame Identifier Specify the frame identifier of the target data.
retType	number	optional	Specify the return type. The default value is 0. 0: Total size of data in all detected frames [byte] 1: Total number of detected frames
return	number, undefined	-	The specified value	If 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.

Name	Type	M/O	Summary	Note
size	number	mandatory	Data size to delete [byte]
return	undefined	-	-

.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().

Name	Type	M/O	Summary	Note
return	undefined	-	-

.reset()

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

Name	Type	M/O	Summary	Note
return	undefined	-	-

.erase()

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

Name	Type	M/O	Summary	Note
return	undefined	-	-

.close()

Closes the specified memory block.

Name	Type	M/O	Summary	Note
return	undefined	-	-

---

{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()/Properties	Summary	Version	Note
.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.

Name	Type	M/O	Summary	Note
return	number	-	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.

Name	Type	M/O	Summary	Note
data	string, ArrayBuffer	mandatory	Data to be written
offset	number	mandatory	Write start offset [byte]
return	number	-	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.

Name	Type	M/O	Summary	Note
data	string, ArrayBuffer	mandatory	Data to be written
offset	number	mandatory	Write start offset [byte]
return	number	-	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.

Name	Type	M/O	Summary	Note
header	string	mandatory	Frame identifier Specify an arbitrary name to identify the frame. (1 - 8 characters)
data	string, ArrayBuffer	mandatory	Data to be written
offset	number	mandatory	Write start offset [byte]
return	number	-	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.

Name	Type	M/O	Summary	Note
header	string	mandatory	Frame identifier Specify an arbitrary name to identify the frame. (1 - 8 characters)
data	string, ArrayBuffer	mandatory	Data to be written
offset	number	mandatory	Write start offset [byte]
return	number	-	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.

Name	Type	M/O	Summary	Note
size	number	mandatory	Size of the data to read [byte]
offset	number	mandatory	Read start offset [byte]
return	string, null, undefined	-	Read data	The 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 00.00.03+). 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.

Name	Type	M/O	Summary	Note
size	number	mandatory	Size of the data to read [byte]
offset	number	mandatory	Read start offset [byte]
return	ArrayBuffer, null	-	Read data	The 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.

Name	Type	M/O	Summary	Note
header	string	mandatory	Frame Identifier Specify the frame identifier of the target data.
return	string, null, undefined	-	The detected read data	If 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.

Name	Type	M/O	Summary	Note
header	string	mandatory	Frame Identifier Specify the frame identifier of the target data.
return	ArrayBuffer, null, undefined	-	The detected read data	If 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.

Name	Type	M/O	Summary	Note
return	undefined	-	-

.close()

Closes the specified memory block.

Name	Type	M/O	Summary	Note
return	undefined	-	-

---

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();
}

step	method	memory block	read 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();
}

step	method	memory block	read 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-04-20