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)
	ドキュメントを削除します。 [詳解]

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 を取得します。 [詳解]

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	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）です。

構築子と解体子

◆ BtrieveCollection()

BtrieveCollection::BtrieveCollection ( )

参照: 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。

戻り値

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

◆ 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 )

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

引数

[in] id ID。

戻り値

= 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

◆ DocumentRetrieveJson() [1/2]

const char* BtrieveCollection::DocumentRetrieveJson ( int id )

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

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

引数

[in] id ID。

戻り値

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

◆ 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/2]

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/2]

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

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

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

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

戻り値

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

参照: Btrieve::StatusCodeToString

◆ 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" です。文字列値はコードポイント順（単純なバイト単位の比較）で並べ替えられます。

戻り値

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

参照: Btrieve::StatusCodeToString

公開メンバ関数

詳解

構築子と解体子

◆ BtrieveCollection()

◆ ~BtrieveCollection()

関数詳解

◆ Decrypt()

◆ DocumentCreate() [1/2]

◆ DocumentCreate() [2/2]

◆ DocumentDelete()

◆ DocumentRetrieve()

◆ DocumentRetrieveBlob()

◆ DocumentRetrieveJson() [1/2]

◆ DocumentRetrieveJson() [2/2]

◆ DocumentUpdate() [1/2]

◆ DocumentUpdate() [2/2]

◆ Encrypt()

◆ GetLastStatusCode()

◆ Query()