The Btrieve collection class. More...

#include <btrieveCpp.h>

Public Member Functions
	BtrieveCollection ()

	~BtrieveCollection ()

Btrieve::StatusCode	Decrypt ()
	Decrypt a collection. More...

int	DocumentCreate (const char *json)
	Create a document. More...

int	DocumentCreate (const char json, const char blob, int blobLength)
	Create a document. More...

Btrieve::StatusCode	DocumentDelete (int id)
	Delete a document. More...

Btrieve::StatusCode	DocumentRetrieve (int id, char json=NULL, int jsonSize=0, char blob=NULL, int blobSize=0, int documentBlobOffset=0, int documentBlobLength=0)
	Retrieve a document. More...

Btrieve::StatusCode	DocumentRetrieveBlob (int id, char *blob, int blobSize, int documentBlobOffset=0, int documentBlobLength=0)
	Retrieve a document blob. More...

const char *	DocumentRetrieveJson (int id)
	Retrieve a document json. More...

const char *	DocumentRetrieveJson (int id, char *blob, int blobSize, int documentBlobOffset=0, int documentBlobLength=0)
	Retrieve a document json. More...

Btrieve::StatusCode	DocumentUpdate (int id, const char *json)
	Update a document. More...

Btrieve::StatusCode	DocumentUpdate (int id, const char json, const char blob, int blobLength)
	Update a document. More...

Btrieve::StatusCode	Encrypt (const char password, const char passwordAgain)
	Encrypt a collection. More...

Btrieve::StatusCode	GetLastStatusCode ()
	Get the last status code. More...

Btrieve::StatusCode	Query (BtrieveDocumentSet btrieveDocumentSet, const char query=NULL)
	Query the collection. More...

Detailed Description

The Btrieve collection class.

Note: This class is currently a beta release; feedback about usage and suggestions for improvements are requested, and can be submitted at https://communities.actian.com/s/actian-zen.

A Btrieve collection consists of zero or more documents. Each document consists of a label, JSON and an optional BLOB. The maximum label length is Btrieve::MAXIMUM_KEY_LENGTH bytes, including the terminating NULL byte. The maximum JSON length is Btrieve::MAXIMUM_RECORD_LENGTH bytes. The maximum BLOB length is 2147483647 bytes (2 GiB - 1).

JSON field names which begin with "_" or "$" are reserved. The following reserved JSON field names are currently defined:

Field Name	User Settable	System Generated	Indexed	Duplicates Allowed	Type	Description
_blobLength	no	yes	yes	yes	number	The document blob length.
_createTime	no	yes	yes	yes	number	The document create time in microseconds since the Unix Epoch.
_id	no	yes	yes	no	number	The document identifier.
_jsonLength	no	yes	yes	yes	number	The document json length.
_label	yes	no	yes	yes	string	The document label.
_updateTime	no	yes	yes	yes	number	The document update time in microseconds since the Unix Epoch.

Non-user settable JSON field names are silently ignored by BtrieveCollection::DocumentCreate and BtrieveCollection::DocumentUpdate. Use of reserved JSON field names other than those listed above will generate an error. Reserved JSON field names are added to the document JSON retrieved by BtrieveCollection::DocumentRetrieveJson and BtrieveCollection::DocumentRetrieve.

The document identifier is an autoincrement positive integer with a maximum value of 2147483647 (2^31 - 1).

Constructor & Destructor Documentation

◆ BtrieveCollection()

BtrieveCollection::BtrieveCollection ( )

See also: BtrieveClient::CollectionOpen

◆ ~BtrieveCollection()

BtrieveCollection::~BtrieveCollection ( )

See also: BtrieveClient::CollectionClose

Member Function Documentation

◆ Decrypt()

Btrieve::StatusCode BtrieveCollection::Decrypt ( )

Decrypt a collection.

Return values

= Btrieve::STATUS_CODE_NO_ERROR	Success.
!= Btrieve::STATUS_CODE_NO_ERROR	An error has occurred.

See also: Btrieve::StatusCodeToString

◆ DocumentCreate() [1/2]

int BtrieveCollection::DocumentCreate ( const char * json )

Create a document.

Parameters

[in] json The json.

Return values

>= 0	The document identifier.
-1	An error has occurred. Use BtrieveCollection::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

◆ DocumentCreate() [2/2]

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

Create a document.

Parameters

[in]	json	The json.
[in]	blob	The blob.
[in]	blobLength	The blob length. If blob is NULL, then blobLength must be 0.

Return values

>= 0	The document identifier.
-1	An error has occurred. Use BtrieveCollection::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

◆ DocumentDelete()

Btrieve::StatusCode BtrieveCollection::DocumentDelete ( int id )

Delete a document.

Parameters

[in] id The identifier.

Return values

= Btrieve::STATUS_CODE_NO_ERROR	Success.
!= Btrieve::STATUS_CODE_NO_ERROR	An error has occurred.

See also: 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`
	)

Retrieve a document.

Note: The method is available only in C++.

Parameters

[in]	id	The identifier.
[out]	json	The json.
[in]	jsonSize	The json size.
[out]	blob	The blob.
[in]	blobSize	The blob size.
[in]	documentBlobOffset	The document blob offset.
[in]	documentBlobLength	The document blob length. If document blob length is 0, then the entire document blob will be retrieved beginning at document blob offset.

Description: Remember to allocate enough space to retrieve not only the document JSON but also the reserved JSON field names and values, e.g. "_bloblength" : 1234567890.

Return values

= Btrieve::STATUS_CODE_NO_ERROR	Success.
!= Btrieve::STATUS_CODE_NO_ERROR	An error has occurred.

See also: Btrieve::StatusCodeToString

◆ DocumentRetrieveBlob()

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

Retrieve a document blob.

Parameters

[in]	id	The identifier.
[out]	blob	The blob.
[in]	blobSize	The blob size.
[in]	documentBlobOffset	The document blob offset.
[in]	documentBlobLength	The document blob length. If document blob length is 0, then the entire document blob will be retrieved beginning at document blob offset.

Return values

= Btrieve::STATUS_CODE_NO_ERROR	Success.
!= Btrieve::STATUS_CODE_NO_ERROR	An error has occurred.

See also: Btrieve::StatusCodeToString

◆ DocumentRetrieveJson() [1/2]

const char* BtrieveCollection::DocumentRetrieveJson ( int id )

Retrieve a document json.

Note: This method is not thread safe. The string returned will be overwritten on subsequent calls.

Parameters

[in] id The identifier.

Return values

!= NULL	The json.
NULL	An error has occurred.

◆ DocumentRetrieveJson() [2/2]

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

Retrieve a document json.

Note: This method is not thread safe. The string returned will be overwritten on subsequent calls.

Parameters

[in]	id	The identifier.
[out]	blob	The blob.
[in]	blobSize	The blob size.
[in]	documentBlobOffset	The document blob offset.
[in]	documentBlobLength	The document blob length. If document blob length is 0, then the entire document blob will be retrieved beginning at document blob offset.

Return values

!= NULL	The json.
NULL	An error has occurred.

◆ DocumentUpdate() [1/2]

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

Update a document.

Parameters

[in]	id	The identifier.
[in]	json	The json. If json is NULL, then the document json will not be updated.

Return values

= Btrieve::STATUS_CODE_NO_ERROR	Success.
!= Btrieve::STATUS_CODE_NO_ERROR	An error has occurred.

See also: Btrieve::StatusCodeToString

◆ DocumentUpdate() [2/2]

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

Update a document.

Parameters

[in]	id	The identifier.
[in]	json	The json. If json is NULL, then the document json will not be updated.
[in]	blob	The blob. If blob is NULL, then the document blob will not be updated.
[in]	blobLength	The blob length. If blob is not NULL and blobLength is 0, then the document blob will be deleted.

Return values

= Btrieve::STATUS_CODE_NO_ERROR	Success.
!= Btrieve::STATUS_CODE_NO_ERROR	An error has occurred.

See also: Btrieve::StatusCodeToString

◆ Encrypt()

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

Encrypt a collection.

Parameters

[in]	password	The password. Password is a null terminated string limited to 32 bytes in length.
[in]	passwordAgain	The password (again).

Description: An encrypted file cannot be opened without providing the correct password. See BtrieveClient::CollectionOpen.

Return values

= Btrieve::STATUS_CODE_NO_ERROR	Success.
!= Btrieve::STATUS_CODE_NO_ERROR	An error has occurred.

See also: Btrieve::StatusCodeToString

◆ GetLastStatusCode()

Btrieve::StatusCode BtrieveCollection::GetLastStatusCode ( )

Get the last status code.

Note: This method is intended for use following methods which don't return a status code.

Return values

= Btrieve::STATUS_CODE_NO_ERROR	Success.
!= Btrieve::STATUS_CODE_NO_ERROR	An error has occurred.

See also: Btrieve::StatusCodeToString

◆ Query()

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

Query the collection.

Parameters

[out]	btrieveDocumentSet	The Btrieve document set.
[in]	query	The query. The maximum query length is Btrieve::MAXIMUM_RECORD_LENGTH bytes.

Description: query ::= { <expressions> }
<expressions> ::= <expression> | <expression> , <expressions>
<expression> ::= <json_expression> | <reserved_expression>
<json_expression> ::=
"$and" : [ <braced_json_expression> , <braced_json_expressions> ] |
"$not" : <braced_json_expression> |
"$or" : [ <braced_json_expression> , <braced_json_expressions> ] |
<field_expression>
<braced_json_expressions> ::=
<braced_json_expression> |
<braced_json_expression> , <braced_json_expressions>
<braced_json_expression> ::= { <json_expression> }
<field_expression> ::=
<field> : <value> |
<field> : { "$exists" : false | true } |
<field> : { "$in" : [ <value> , <values> ] } |
<field> : { "$nin" : [ <value> , <values> ] } |
<field> : { "$type" : <type> } |
<field> : { <operator> : <value> } |
<field> : { <field_expression> }
<field> ::= <string>
<values> ::= <value> | <value> , <values>
<value> ::= false | true | NULL | <string> | <number> | <array>
<type> ::= "array" | "boolean" | "null" | "number" | "object" | "string"
<operator> ::= "$eq" | "$gt" | "$gte" | "$lt" | "$lte" | "$ne"
<reserved_expression> ::=
"_blobLength" : <number> |
"_blobLength" : { <operator> : <number> } |
"_createTime" : <number> |
"_createTime" : { <time_operator> : <number> } |
"_id" : <number> |
"_id" : { <operator> : <number> } |
"_jsonLength" : <number> |
"_jsonLength" : { <operator> : <number> } |
"_label" : <string> |
"_label" : { <string_operator> : <string> } |
"_sortField" : <sort_field> |
"_sortOrder" : "ascending" |
"_sortOrder" : "descending" |
"_updateTime" : <number> |
"_updateTime" : { <time_operator> : <number> }
<sort_field> := "_blobLength" | "_createTime" | "_id" | "_jsonLength" | "_label" | "_updateTime"
<time_operator> ::= "$eq" | "$gt" | "$gte" | "$lt" | "$lte"
<string_operator> ::= "$eq" | "$gt" | "$gte" | "$like" | "$lt" | "$lte" | "$ne" | "$notlike"

: In a JSON expression, if the query value is not an array and the document value is an array then each element in the array is evaluated. If any evaluation returns true then the JSON expression returns true.

: Only one each of "_sortField" and "_sortOrder" may appear in a query. The default sort field is "_id". The default sort order is "ascending". String values are sorted in code point order (simple byte-by-byte comparison).

Return values

= Btrieve::STATUS_CODE_NO_ERROR	Success.
!= Btrieve::STATUS_CODE_NO_ERROR	An error has occurred. A more detailed description of the error may be available in the Zen event log.

See also: Btrieve::StatusCodeToString

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BtrieveCollection()

◆ ~BtrieveCollection()

Member Function Documentation

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