BtrieveCollection クラス

Btrieve コレクション クラス。 [詳解]

#include <btrieveCpp.h>

公開メンバ関数
	BtrieveCollection ()
	~BtrieveCollection ()
Btrieve::StatusCode	Decrypt ()
	コレクションを復号します。
int	DocumentCreate (const char *json)
	ドキュメントを作成します。
int	DocumentCreate (const char *json, const char *blob, int blobLength)
	ドキュメントを作成します。
Btrieve::StatusCode	DocumentDelete (int id, int entityTag=-1)
	ドキュメントを削除します。
Btrieve::StatusCode	DocumentRetrieve (int id, char *json=NULL, int jsonSize=0, char *blob=NULL, int blobSize=0, int documentBlobOffset=0, int documentBlobLength=0)
	ドキュメントを取得します。
Btrieve::StatusCode	DocumentRetrieveBlob (int id, char *blob, int blobSize, int documentBlobOffset=0, int documentBlobLength=0)
	ドキュメントの blob を取得します。
int	DocumentRetrieveEntityTag (int id)
	ドキュメントのエンティティ タグを取得します。
const char *	DocumentRetrieveJson (int id)
	ドキュメントの json を取得します。
const char *	DocumentRetrieveJson (int id, char *blob, int blobSize, int documentBlobOffset=0, int documentBlobLength=0)
	ドキュメントの json を取得します。
Btrieve::StatusCode	DocumentUpdate (int id, const char *json)
	ドキュメントを更新します。
Btrieve::StatusCode	DocumentUpdate (int id, const char *json, const char *blob, int blobLength)
	ドキュメントを更新します。
Btrieve::StatusCode	DocumentUpdate (int id, int entityTag, const char *json)
	ドキュメントを更新します。
Btrieve::StatusCode	DocumentUpdate (int id, int entityTag, const char *json, const char *blob, int blobLength)
	ドキュメントを更新します。
Btrieve::StatusCode	Encrypt (const char *password, const char *passwordAgain)
	コレクションを暗号化します。
Btrieve::StatusCode	GetLastStatusCode ()
	最新のステータス コードを取得します。
Btrieve::StatusCode	Query (BtrieveDocumentSet *btrieveDocumentSet, const char *query=NULL)
	コレクションを照会します。

詳解

Btrieve コレクション クラス。

覚え書き

このクラスは現在ベータ リリースです。使用法に関するフィードバックや改善のためのご提案を求めておりますので、 https://communities.actian.com/s/actian-zen までお送りください。

Btrieve コレクションは 0 個以上のドキュメントで構成されています。 各ドキュメントはラベルおよび JSON と、任意の BLOB で構成されます。 ラベルの最大長は、終端のヌルのバイトも含めて Btrieve::MAXIMUM_KEY_LENGTH バイトです。 JSON の最大長は Btrieve::MAXIMUM_RECORD_LENGTH バイトです。 BLOB の最大長は 2147483647 バイト（2 GiB - 1）です。

"_" または "$" で始まる JSON フィールド名は予約されています。 現在のところ、次の予約済み JSON フィールド名が定義されています。

フィールド名	ユーザー設定可能	システム生成	インデックス作成	重複許可	型	説明
_blobLength	いいえ	はい	はい	はい	数値	ドキュメントの blob の長さ。
_createTime	いいえ	はい	はい	はい	数値	ドキュメントの作成時刻（Unix エポックからのマイクロ秒数）。
_id	いいえ	はい	はい	いいえ	数値	ドキュメント ID。
_jsonLength	いいえ	はい	はい	はい	数値	ドキュメントの json の長さ。
_label	はい	いいえ	はい	はい	文字列	ドキュメントのラベル。
_updateTime	いいえ	はい	はい	はい	数値	ドキュメントの更新時刻（Unix エポックからのマイクロ秒数）。

BtrieveCollection::DocumentCreate および BtrieveCollection::DocumentUpdate では、ユーザー設定可能でない JSON フィールド名があっても通知されません。 上に挙げた以外の予約済み JSON フィールド名を使用すると、エラーが発生します。 予約済み JSON フィールド名は、 BtrieveCollection::DocumentRetrieveJson および BtrieveCollection::DocumentRetrieve によって取得されるドキュメントの JSON に追加されます。

ドキュメント ID は自動インクリメントの正の整数で、最大値は 2147483647（2^31 - 1）です。

各種例

bcollection.cpp.

構築子と解体子

BtrieveCollection()

BtrieveCollection::BtrieveCollection

(

)

スニペット

C++ bcollection.cpp

   BtrieveCollection btrieveCollection;

Python bcollection.py

btrieveCollection = btrievePython.BtrieveCollection()
assert(btrieveCollection != None)

参照

BtrieveClient::CollectionOpen

~BtrieveCollection()

BtrieveCollection::~BtrieveCollection

(

)

参照

BtrieveClient::CollectionClose

関数詳解

Decrypt()

Btrieve::StatusCode BtrieveCollection::Decrypt

(

)

コレクションを復号します。

戻り値

= Btrieve::STATUS_CODE_NO_ERROR	成功。
!= Btrieve::STATUS_CODE_NO_ERROR	エラーが発生しました。

参照

Btrieve::StatusCodeToString

DocumentCreate() [1/2]

int BtrieveCollection::DocumentCreate

(

const char *

json

)

ドキュメントを作成します。

引数

[in]

json

json。

スニペット

C++ bcollection.cpp

      // If DocumentCreate() fails.
      if (btrieveCollection->DocumentCreate(json) < 0)
      {
         status = btrieveCollection->GetLastStatusCode();
         printf("Error: BtrieveCollection::DocumentCreate():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
         goto leave;
      }

Python bcollection.py

    rc = btrieveCollection.DocumentCreate(documentJson)
    assert(rc >= 0), "Error: BtrieveCollection::DocumentCreate():%d:%s.\n"  % (rc, btrievePython.Btrieve_StatusCodeToString(btrieveCollection.GetLastStatusCode()))

戻り値

>= 0	ドキュメント ID。
-1	エラーが発生しました。 エラーに関連する Btrieve::StatusCode を特定するには BtrieveCollection::GetLastStatusCode を使用します。

各種例

bcollection.cpp.

DocumentCreate() [2/2]

int BtrieveCollection::DocumentCreate	(	const char *	json,
		const char *	blob,
		int	blobLength )

ドキュメントを作成します。

引数

[in]	json	json。
[in]	blob	blob。
[in]	blobLength	blob の長さ。blob が NULL の場合は、blobLength を 0 にする必要があります。

戻り値

>= 0	ドキュメント ID。
-1	エラーが発生しました。 エラーに関連する Btrieve::StatusCode を特定するには BtrieveCollection::GetLastStatusCode を使用します。

DocumentDelete()

Btrieve::StatusCode BtrieveCollection::DocumentDelete	(	int	id,
		int	entityTag = -1 )

ドキュメントを削除します。

引数

[in]	id	ID。
[in]	entityTag	エンティティ タグ。エンティティ タグは、ドキュメントのエンティティ タグと等しいか、または -1 である必要があります。

戻り値

= Btrieve::STATUS_CODE_NO_ERROR	成功。
!= Btrieve::STATUS_CODE_NO_ERROR	エラーが発生しました。

参照

Btrieve::StatusCodeToString

DocumentRetrieve()

Btrieve::StatusCode BtrieveCollection::DocumentRetrieve	(	int	id,
		char *	json = NULL,
		int	jsonSize = 0,
		char *	blob = NULL,
		int	blobSize = 0,
		int	documentBlobOffset = 0,
		int	documentBlobLength = 0 )

ドキュメントを取得します。

覚え書き

このメソッドは C++ でのみ使用可能です。

引数

[in]	id	ID。
[out]	json	json。
[in]	jsonSize	json のサイズ。
[out]	blob	blob。
[in]	blobSize	blob のサイズ。
[in]	documentBlobOffset	ドキュメントの blob のオフセット。
[in]	documentBlobLength	ドキュメントの blob の長さ。ドキュメントの blob の長さが 0 の場合は、ドキュメントの blob 全体は blob のオフセットから取得されます。

説明

ドキュメントの JSON だけでなく、予約済みの JSON フィールド名と値（例："_bloblength" : 1234567890）を取得するのにも十分な領域を割り当てることを忘れないでください。

戻り値

= Btrieve::STATUS_CODE_NO_ERROR	成功。
!= Btrieve::STATUS_CODE_NO_ERROR	エラーが発生しました。

参照

Btrieve::StatusCodeToString

DocumentRetrieveBlob()

Btrieve::StatusCode BtrieveCollection::DocumentRetrieveBlob	(	int	id,
		char *	blob,
		int	blobSize,
		int	documentBlobOffset = 0,
		int	documentBlobLength = 0 )

ドキュメントの blob を取得します。

引数

[in]	id	ID。
[out]	blob	blob。
[in]	blobSize	blob のサイズ。
[in]	documentBlobOffset	ドキュメントの blob のオフセット。
[in]	documentBlobLength	ドキュメントの blob の長さ。ドキュメントの blob の長さが 0 の場合は、ドキュメントの blob 全体は blob のオフセットから取得されます。

戻り値

= Btrieve::STATUS_CODE_NO_ERROR	成功。
!= Btrieve::STATUS_CODE_NO_ERROR	エラーが発生しました。

参照

Btrieve::StatusCodeToString

DocumentRetrieveEntityTag()

int BtrieveCollection::DocumentRetrieveEntityTag

(

int

id

)

ドキュメントのエンティティ タグを取得します。

引数

[in]

id

ID。

戻り値

>= 0	ドキュメントのエンティティ タグ。
-1	エラーが発生しました。 エラーに関連する Btrieve::StatusCode を特定するには BtrieveCollection::GetLastStatusCode を使用します。

DocumentRetrieveJson() [1/2]

const char * BtrieveCollection::DocumentRetrieveJson

(

int

id

)

ドキュメントの json を取得します。

覚え書き

このメソッドはスレッド セーフではありません。返された文字列は、次の呼び出しで上書きされます。

引数

[in]

id

ID。

スニペット

C++ bcollection.cpp

   // If DocumentRetrieveJson() fails.
   if ((json = btrieveCollection->DocumentRetrieveJson(id)) == NULL)
   {
      status = btrieveCollection->GetLastStatusCode();
      printf("Error: BtrieveCollection::DocumentRetrieveJson():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
      goto leave;
   }

Python bcollection.py

rc = btrieveCollection.DocumentRetrieveJson(rc)
assert(rc != None), "Error: BtrieveCollection::DocumentRetrieveJson():%d:%s.\n" % (rc, btrievePython.Btrieve_StatusCodeToString(btrieveCollection.GetLastStatusCode()))

戻り値

!= NULL	json。
NULL	エラーが発生しました。

各種例

bcollection.cpp.

DocumentRetrieveJson() [2/2]

const char * BtrieveCollection::DocumentRetrieveJson	(	int	id,
		char *	blob,
		int	blobSize,
		int	documentBlobOffset = 0,
		int	documentBlobLength = 0 )

ドキュメントの json を取得します。

覚え書き

このメソッドはスレッド セーフではありません。返された文字列は、次の呼び出しで上書きされます。

引数

[in]	id	ID。
[out]	blob	blob。
[in]	blobSize	blob のサイズ。
[in]	documentBlobOffset	ドキュメントの blob のオフセット。
[in]	documentBlobLength	ドキュメントの blob の長さ。ドキュメントの blob の長さが 0 の場合は、ドキュメントの blob 全体は blob のオフセットから取得されます。

戻り値

!= NULL	json。
NULL	エラーが発生しました。

DocumentUpdate() [1/4]

Btrieve::StatusCode BtrieveCollection::DocumentUpdate	(	int	id,
		const char *	json )

ドキュメントを更新します。

引数

[in]	id	ID。
[in]	json	json。json が NULL の場合、ドキュメントの json は更新されません。

戻り値

= Btrieve::STATUS_CODE_NO_ERROR	成功。
!= Btrieve::STATUS_CODE_NO_ERROR	エラーが発生しました。

参照

Btrieve::StatusCodeToString

DocumentUpdate() [2/4]

Btrieve::StatusCode BtrieveCollection::DocumentUpdate	(	int	id,
		const char *	json,
		const char *	blob,
		int	blobLength )

ドキュメントを更新します。

引数

[in]	id	ID。
[in]	json	json。json が NULL の場合、ドキュメントの json は更新されません。
[in]	blob	blob。blob が NULL の場合、ドキュメントの blob は更新されません。
[in]	blobLength	blob の長さ。blob が NULL でなく、blobLength が 0 の場合、ドキュメントの blob は削除されます。

戻り値

= Btrieve::STATUS_CODE_NO_ERROR	成功。
!= Btrieve::STATUS_CODE_NO_ERROR	エラーが発生しました。

参照

Btrieve::StatusCodeToString

DocumentUpdate() [3/4]

Btrieve::StatusCode BtrieveCollection::DocumentUpdate	(	int	id,
		int	entityTag,
		const char *	json )

ドキュメントを更新します。

引数

[in]	id	ID。
[in]	entityTag	エンティティ タグ。エンティティ タグは、ドキュメントのエンティティ タグと等しいか、または -1 である必要があります。
[in]	json	json。json が NULL の場合、ドキュメントの json は更新されません。

戻り値

= Btrieve::STATUS_CODE_NO_ERROR	成功。
!= Btrieve::STATUS_CODE_NO_ERROR	エラーが発生しました。

参照

Btrieve::StatusCodeToString

DocumentUpdate() [4/4]

Btrieve::StatusCode BtrieveCollection::DocumentUpdate	(	int	id,
		int	entityTag,
		const char *	json,
		const char *	blob,
		int	blobLength )

ドキュメントを更新します。

引数

[in]	id	ID。
[in]	entityTag	エンティティ タグ。エンティティ タグは、ドキュメントのエンティティ タグと等しいか、または -1 である必要があります。
[in]	json	json。json が NULL の場合、ドキュメントの json は更新されません。
[in]	blob	blob。blob が NULL の場合、ドキュメントの blob は更新されません。
[in]	blobLength	blob の長さ。blob が NULL でなく、blobLength が 0 の場合、ドキュメントの blob は削除されます。

戻り値

= Btrieve::STATUS_CODE_NO_ERROR	成功。
!= Btrieve::STATUS_CODE_NO_ERROR	エラーが発生しました。

参照

Btrieve::StatusCodeToString

Encrypt()

Btrieve::StatusCode BtrieveCollection::Encrypt	(	const char *	password,
		const char *	passwordAgain )

コレクションを暗号化します。

引数

[in]	password	パスワード。パスワードは、32 バイトまでに制限されたヌル終了文字列です。
[in]	passwordAgain	パスワード（確認）。

説明

暗号化されたファイルは、正しいパスワードを提供しないと開くことができません。 BtrieveClient::CollectionOpen を参照してください。

戻り値

= Btrieve::STATUS_CODE_NO_ERROR	成功。
!= Btrieve::STATUS_CODE_NO_ERROR	エラーが発生しました。

参照

Btrieve::StatusCodeToString

GetLastStatusCode()

Btrieve::StatusCode BtrieveCollection::GetLastStatusCode

(

)

最新のステータス コードを取得します。

覚え書き

このメソッドは、ステータス コードを返さない以下のメソッドでの使用を目的としています。

スニペット

C++ bcollection.cpp

      // If DocumentCreate() fails.
      if (btrieveCollection->DocumentCreate(json) < 0)
      {
         status = btrieveCollection->GetLastStatusCode();
         printf("Error: BtrieveCollection::DocumentCreate():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
         goto leave;
      }

Python bcollection.py

    rc = btrieveCollection.DocumentCreate(documentJson)
    assert(rc >= 0), "Error: BtrieveCollection::DocumentCreate():%d:%s.\n"  % (rc, btrievePython.Btrieve_StatusCodeToString(btrieveCollection.GetLastStatusCode()))

戻り値

= Btrieve::STATUS_CODE_NO_ERROR	成功。
!= Btrieve::STATUS_CODE_NO_ERROR	エラーが発生しました。

参照

Btrieve::StatusCodeToString

各種例

bcollection.cpp.

Query()

Btrieve::StatusCode BtrieveCollection::Query	(	BtrieveDocumentSet *	btrieveDocumentSet,
		const char *	query = NULL )

コレクションを照会します。

引数

[out]	btrieveDocumentSet	Btrieve ドキュメント セット。
[in]	query	クエリ。クエリの最大長は Btrieve::MAXIMUM_RECORD_LENGTH バイトです。

説明

query ::= { } | { <式> }
 
<式> ::= <式> | <式> , <式>
 
<式> ::= <json 式> | <予約された式>
 
<json 式> ::= 
   "$and" : [ <中かっこで囲まれた json 式> , <中かっこで囲まれた json 式> ] |
   "$not" : <中かっこで囲まれた json 式> |
   "$or" : [ <中かっこで囲まれた json 式> , <中かっこで囲まれた json 式> ] |
   <フィールド式>
 
<中かっこで囲まれた json 式> ::= 
   <中かっこで囲まれた json 式> | 
   <中かっこで囲まれた json 式> , <中かっこで囲まれた json 式>
 
<中かっこで囲まれた json 式> ::= { <json 式> }
 
<フィールド式> ::=
   <フィールド> : <値> |
   <フィールド> : { "$exists" : false | true } |
   <フィールド> : { "$in" : [ <値> , <複数値> ] } |
   <フィールド> : { "$nin" : [ <値> , <複数値> ] } |
   <フィールド> : { "$type" : <型> } |
   <フィールド> : { <演算子> : <値> } |
   <フィールド> : { <フィールド式> }
 
<フィールド> ::= <文字列>
 
<複数値> ::= <値> | <値> , <複数値>
 
<値> ::= false | true | NULL | <文字列> | <数値> | <配列>
 
<型> ::= "array" | "boolean" | "null" | "number" | "object" | "string"
 
<演算子> ::= "$eq" | "$gt" | "$gte" | "$lt" | "$lte" | "$ne"
 
<予約された式> ::= 
   "_blobLength" : <数値> | 
   "_blobLength" : { <演算子> : <数値> } |
   "_createTime" : <数値> | 
   "_createTime" : { <時刻演算子> : <数値> } | 
   "_id" : <数値> | 
   "_id" : { <演算子> : <数値> } |
   "_jsonLength" : <数値> | 
   "_jsonLength" : { <演算子> : <数値> } |
   "_label" : <文字列> | 
   "_label" : { <文字列演算子> : <文字列> } |
   "_sortField" : <並べ替えフィールド> |
   "_sortOrder" : "ascending" | 
   "_sortOrder" : "descending" |
   "_updateTime" : <数値> | 
   "_updateTime" : { <時刻演算子> : <数値> }
 
<並べ替えフィールド> := "_blobLength" | "_createTime" | "_id" | "_jsonLength" | "_label" | "_updateTime"
 
<時刻演算子> ::= "$eq" | "$gt" | "$gte" | "$lt" | "$lte"
 
<文字列演算子> ::= "$eq" | "$gt" | "$gte" | "$like" | "$lt" | "$lte" | "$ne" | "$notlike"

JSON 式で、クエリ値が配列でなくドキュメント値が配列である場合は、配列内の各要素が評価されます。すべての評価が true を返せば、JSON 式は true を返します。

"_sortField" および "_sortOrder" は、配列内に各 1 つずつのみ含めることができます。 デフォルトの並べ替えフィールドは "_id" です。 デフォルトの並べ替え順は "ascending" です。 文字列値はコード ポイント順（単純なバイト単位の比較）で並べ替えられます。

スニペット

C++ bcollection.cpp

   // If Query() fails.
   if ((status = btrieveCollection->Query(&btrieveDocumentSet, query.c_str())) != Btrieve::STATUS_CODE_NO_ERROR)
   {
      printf("Error: BtrieveCollection::Query():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
      goto leave;
   }

Python bcollection.py

rc = btrieveCollection.Query(btrieveDocumentSet, query)
assert(rc == btrievePython.Btrieve.STATUS_CODE_NO_ERROR), "Error: BtrieveCollection::Query():%d:%s.\n" % (rc, btrievePython.Btrieve_StatusCodeToString(rc))

戻り値

= Btrieve::STATUS_CODE_NO_ERROR	成功。
!= Btrieve::STATUS_CODE_NO_ERROR	エラーが発生しました。 エラーに関する詳細説明は、Zen イベント ログで入手できます。

参照

Btrieve::StatusCodeToString

各種例

bcollection.cpp.