08. Storage

storageオブジェクトは、ユーザー専用不揮発メモリ領域へのデータ読み書き機能を提供する組み込みオブジェクトです。

機能概要:

• テキストデータの読み書き機能を提供します。
• バイナリデータの読み書き機能を提供します。

制限事項:

• テキストデータ保存用領域(MemBlock)で使用できるデータサイズは最大16320KBとなります。
• バイナリデータ保存用領域(RawMemBlock)で使用できるデータサイズは32KBx32ブロックとなります。

---

storage Global Object

Methods()/Properties	Summary	Version	Note
storage.open()	{MemBlock}のインスタンスを生成します。
storage.rawOpen()	{RawMemBlock}のインスタンスを生成します。

---

Details

storage.open([blockNo])

ストレージをオープンし、{MemBlock}のインスタンスを生成します。

Name	Type	M/O	Summary	Note
blockNo	number	optional	{MemBlock}識別子 指定された番号に対応するインスタンスを生成します。 設定範囲: 0 デフォルト値は0となります。	0のみが使用可能です。
return	{MemBlock}	-	{MemBlock} : 生成された{MemBlock}	異常が発生した時は、例外となります。

storage.rawOpen([blockNo])

ストレージをオープンし、{RawMemBlock}のインスタンスを生成します。

Name	Type	M/O	Summary	Note
blockNo	number	optional	{RawMemBlock}識別子 指定された番号に対応するインスタンスを生成します。 設定範囲: 0～15 デフォルト値は0となります。
return	{RawMemBlock}	-	{RawMemBlock} : 生成された{RawMemBlock}	異常が発生した時は、例外となります。

---

{MemBlock}

本オブジェクトは、storage.open()により内部で生成され、返却されます。
不揮発性メモリブロックへのテキストベースFIFOアクセス機能を提供します。
以後、.close()が実行されるまで、メモリへのアクセスが許可されます。

Methods()/Properties	Summary	Version	Note
.getReadableSize()	指定されたメモリブロック内の読み出し可能なサイズを取得します。
.getBlockSize()	指定されたメモリブロックのサイズを取得します。
.write()	メモリブロックへデータを書き込みます。
.writeFrame()	メモリブロックへフレーム識別子で管理される専用フレーム形式でデータを書き込みます。
.read()	メモリブロックからデータを読み出します。
.readFrame()	メモリブロックから指定されたフレーム識別子に該当するデータを読み出します。
.searchFrame()	指定されたフレーム識別子に該当するデータをメモリブロックの先頭フレームから検索します。
.recoverFrame()	指定されたフレーム識別子に該当するデータがメモリブロックの先頭フレームとなるように回復を行います。
.searchAllFrame()	指定されたフレーム識別子に該当するデータをメモリブロックの先頭フレームからすべて検索します。
.remove()	メモリブロック内の読み取り可能なデータの先頭からデータを消去します。
.removeFrame()	読み出し済の先頭フレームを消去します。
.reset()	指定されたメモリブロックをリセットします。
.erase()	指定されたメモリブロックを完全に消去します。
.close()	指定されたメモリブロックをクローズします。

---

Details

.getReadableSize()

指定されたメモリブロック内の読み出し可能なサイズを取得します。

Name	Type	M/O	Summary	Note
return	number	-	読み出し可能サイズ[byte]

.getBlockSize()

指定されたメモリブロックのサイズを取得します。
書き込み可能な最大サイズを意味します。

Name	Type	M/O	Summary	Note
return	number	-	メモリブロック容量[byte]

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

メモリブロックへデータを書き込みます。

Name	Type	M/O	Summary	Note
data	string	mandatory	書き込みデータ
size	number	optional	書き込みデータサイズ	指定されたサイズが書き込みデータ長を超えた場合、パディングが行われます。
pad	string	optional	パディング文字(1byte)を指定します。 デフォルト値はバッククォート( ` )となります。
return	number	-	書き込まれたサイズ[byte]	書き込みに失敗した場合は0が返却されます。その場合、 .getReadableSize()と .getBlockSize()を使って、残りの書き込み可能なサイズを確認してください。

.writeFrame(header,data)

メモリブロックへフレーム識別子で管理される専用フレーム形式でデータを書き込みます。

.writeFrame()を使用した専用フレーム形式のデータ書き込みと.write()を使用したデータ書き込みを同じメモリブロックに混在させることはできません。 したがって、.writeFrame()を使用する場合は、.write()を使用しないでください。

Name	Type	M/O	Summary	Note
header	string	mandatory	フレーム識別子 フレームを識別する任意の名前(1～7文字)を指定します。
data	string	mandatory	書き込みデータ
return	number	-	書き込まれたフレームサイズ[byte]	フレームサイズは、書き込まれたデータ長と24バイトのフレームオーバーヘッド長の合計となります。 書き込みに失敗した場合は0が返却されます。その場合、 .getReadableSize()と .getBlockSize()を使って、残りの書き込み可能なサイズを確認してください。

.read(size,offset)

メモリブロックからデータを読み出します。

Name	Type	M/O	Summary	Note
size	number	mandatory	読み出しデータサイズ[byte]
offset	number	mandatory	読み出し開始オフセット[byte]
return	string, null	-	読み出しデータ	読み出しデータは、オフセットで指定された開始位置から、指定されたデータサイズまたはデータが存在する範囲まで読み込まれます。 データが存在しない場合はnullが返却されます。

.readFrame(header,flag)

メモリブロックから指定されたフレーム識別子に該当するデータを読み出します。

Name	Type	M/O	Summary	Note
header	string	mandatory	フレーム識別子 対象データのフレーム識別子を指定します。
flag	number	mandatory	読み出しフラグ 0: 先頭フレームデータの読み出しのみ 1(≠0): 先頭フレームデータの読み出しとフレームの自動消去
return	string, null, undefined	-	読み出しデータ	データが存在しない場合はnullが返却されます。フレーム破損又はその他の異常が検出された場合はundefinedが返却されます。

.searchFrame(header,index)

指定されたフレーム識別子に該当するデータをメモリブロックの先頭フレームから検索します。

Name	Type	M/O	Summary	Note
header	string	mandatory	フレーム識別子 対象データのフレーム識別子を指定します。
index	number	optional	サーチフレームのインデックス 設定範囲: 0～(N-1) デフォルト値は0となります。	N: .searchAllFrame()によって得られる検出されたフレーム総数
return	string, null, undefined	-	検出された読み出しデータ	データが存在しない場合はnullが返却されます。フレーム破損又はその他の異常が検出された場合はundefinedが返却されます。

.recoverFrame(header)

指定されたフレーム識別子に該当するデータがメモリブロックの先頭フレームとなるように回復を行います。
フレーム破損を検出した際に使用してください。(.readFrame()又は.searchFrame()でundefinedが返却された時)
回復が不要な場合に行うと、有効なフレームが削除されることがあるため、回復が必要な場合のみ使用してください。

Name	Type	M/O	Summary	Note
header	string	mandatory	フレーム識別子 対象データのフレーム識別子を指定します。
return	number, undefined	-	number : 回復のために消去されたデータサイズ[byte] undefined : 回復不能	回復不能となった際は、resetを実行してください。

.searchAllFrame(header,retType)

指定されたフレーム識別子に該当するデータをメモリブロックの先頭フレームからすべて検索します。

Name	Type	M/O	Summary	Note
header	string	mandatory	フレーム識別子 対象データのフレーム識別子を指定します。
retType	number	optional	戻り値で返却する値を指定します。 デフォルト値は0となります。 0: 検出されたすべてのフレーム内のデータの総サイズ[byte] 1: 検出されたフレーム総数
return	number, undefined	-	指定された値	フレーム破損又はその他の異常が検出された場合、undefinedが返却されます。

.remove(size)

メモリブロック内の読み取り可能なデータの先頭からデータを消去します。

Name	Type	M/O	Summary	Note
size	number	mandatory	削除するデータサイズ[byte]
return	undefined	-	-

.removeFrame()

読み出し済の先頭フレームを消去します。
フレーム識別子を指定して消去することはできません。
読み込まれた最初のフレームとは、.readFrame()を使用して読み取られたフレームデータを意味します。.searchFrame()を使用して読み取られたフレームデータは対象となりません。

Name	Type	M/O	Summary	Note
return	undefined	-	-

.reset()

指定されたメモリブロックをリセットします。
読み出しデータが存在しない状態に戻ります。

Name	Type	M/O	Summary	Note
return	undefined	-	-

.erase()

指定されたメモリブロックを完全に消去します。
消去完了までに数十秒時間がかかります。

Name	Type	M/O	Summary	Note
return	undefined	-	-

.close()

指定されたメモリブロックをクローズします。

Name	Type	M/O	Summary	Note
return	undefined	-	-

---

{RawMemBlock}

本オブジェクトは、storage.rawOpen()により内部で生成され、返却されます。
不揮発性メモリブロックへの低レベルなアクセスインタフェースを提供します。
以後、.close()が実行されるまで、メモリへのアクセスが許可されます。

Methods()/Properties	Summary	Version	Note
.getBlockSize()	指定されたメモリブロックのサイズを取得します。
.write()	メモリブロックへデータを書き込みます。
.append()	メモリブロックへデータを追記します。
.writeFrame()	メモリブロックへフレーム識別子で管理される専用フレーム形式でデータを書き込みます。
.appendFrame()	メモリブロックへフレーム識別子で管理される専用フレーム形式でデータを追記します。
.read()	メモリブロックからデータを読み出します。
.readBin()	メモリブロックからデータをバイナリで読み出します。
.searchFrame()	指定されたフレーム識別子に該当するデータをメモリブロックの先頭フレームから検索します。
.searchBinFrame()	指定されたフレーム識別子に該当するデータをメモリブロックの先頭フレームから検索し、バイナリで読み出します。
.erase()	指定されたメモリブロックを完全に消去します。
.close()	指定されたメモリブロックをクローズします。

---

Details

.getBlockSize()

指定されたメモリブロックのサイズを取得します。

Name	Type	M/O	Summary	Note
return	number	-	メモリブロック容量[byte]

.write(data,offset)

メモリブロックへデータを書き込みます。
メモリブロックのデータは、書き込み前に一度完全に消去されます。

Name	Type	M/O	Summary	Note
data	string, ArrayBuffer	mandatory	書き込みデータ
offset	number	mandatory	書き込み開始オフセット[byte]
return	number	-	書き込まれたサイズ[byte]	書き込みに失敗した場合は0が返却されます。

.append(data,offset)

メモリブロックへデータを追記します。
基本的に、データが書き込まれていない位置をオフセットで指定して使用します。

Name	Type	M/O	Summary	Note
data	string, ArrayBuffer	mandatory	書き込みデータ
offset	number	mandatory	書き込み開始オフセット[byte]
return	number	-	書き込まれたサイズ[byte]	書き込みに失敗した場合は0が返却されます。

.writeFrame(header,data,offset)

メモリブロックへフレーム識別子で管理される専用フレーム形式でデータを書き込みます。
メモリブロックのデータは、書き込み前に一度完全に消去されます。

Name	Type	M/O	Summary	Note
header	string	mandatory	フレーム識別子 フレームを識別する任意の名前(1～8文字)を指定します。
data	string, ArrayBuffer	mandatory	書き込みデータ
offset	number	mandatory	書き込み開始オフセット[byte]
return	number	-	書き込まれたフレームサイズ[byte]	フレームサイズは、書き込まれたデータ長と16バイトのフレームオーバーヘッド長の合計となります。 書き込みに失敗した場合は0が返却されます。

.appendFrame(header,data,offset)

メモリブロックへフレーム識別子で管理される専用フレーム形式でデータを追記します。
フレームデータが書き込まれていない位置をオフセットで指定して使用します。

Name	Type	M/O	Summary	Note
header	string	mandatory	フレーム識別子 フレームを識別する任意の名前(1～8文字)を指定します。
data	string, ArrayBuffer	mandatory	書き込みデータ
offset	number	mandatory	書き込み開始オフセット[byte]
return	number	-	書き込まれたフレームサイズ[byte]	フレームサイズは、書き込まれたデータ長と16バイトのフレームオーバーヘッド長の合計となります。 書き込みに失敗した場合は0が返却されます。

.read(size,offset)

メモリブロックからデータを読み出します。

Name	Type	M/O	Summary	Note
size	number	mandatory	読み出しデータサイズ[byte]
offset	number	mandatory	読み出し開始オフセット[byte]
return	string, null, undefined	-	読み出しデータ	読み出しデータは、オフセットで指定された開始位置から、指定されたデータサイズまたはデータが存在する範囲(Version 00.00.03+)まで読み込まれます。 データが存在しない場合はnullが返却されます。 文字以外のデータが検出された場合はundefinedが返却されます。

.readBin(size,offset)

メモリブロックからデータをバイナリで読み出します。

Name	Type	M/O	Summary	Note
size	number	mandatory	読み出しデータサイズ[byte]
offset	number	mandatory	読み出し開始オフセット[byte]
return	ArrayBuffer, null	-	読み出しデータ	読み出しデータは、オフセットで指定された開始位置から、指定されたデータサイズまで読み込まれます。 データが存在しない場合はnullが返却されます。

.searchFrame(header)

指定されたフレーム識別子に該当するデータをメモリブロックの先頭フレームから検索します。

Name	Type	M/O	Summary	Note
header	string	mandatory	フレーム識別子 対象データのフレーム識別子を指定します。
return	string, null, undefined	-	検出された読み出しデータ	データが存在しない場合はnullが返却されます。フレーム破損又はその他の異常が検出された場合はundefinedが返却されます。

.searchBinFrame(header)

指定されたフレーム識別子に該当するデータをメモリブロックの先頭フレームから検索し、バイナリで読み出します。

Name	Type	M/O	Summary	Note
header	string	mandatory	フレーム識別子 対象データのフレーム識別子を指定します。
return	ArrayBuffer, null, undefined	-	検出された読み出しデータ	データが存在しない場合はnullが返却されます。フレーム破損又はその他の異常が検出された場合はundefinedが返却されます。

.erase()

指定されたメモリブロックを完全に消去します。

Name	Type	M/O	Summary	Note
return	undefined	-	-

.close()

指定されたメモリブロックをクローズします。

Name	Type	M/O	Summary	Note
return	undefined	-	-

---

オブジェクトの使用例

Sample 1

フレーム書き込みおよびフレーム読み出しのサンプルです。

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

異なるヘッダを使用した、フレーム書き込みおよびフレーム読み出しのサンプルです。

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

フレーム破損を検出した場合に、復旧を試みるサンプルです。

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

{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

フレーム書き込みおよびフレーム読み出しのサンプルです。
下表は、このサンプルを実行した時のメモリブロック内のデータの流れを示しています。

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

異なるヘッダを使用した、フレーム書き込みおよびフレーム読み出しのサンプルです。
下表は、このサンプルを実行した時のメモリブロック内のデータの流れを示しています。

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