BtrieveCollection Class Reference

The Btrieve collection class. More...

#include <btrieveCpp.h>

Public Member Functions
	BtrieveCollection ()
	~BtrieveCollection ()
Btrieve::StatusCode	Decrypt ()
	Decrypt a collection.
int	DocumentCreate (const char *json)
	Create a document.
int	DocumentCreate (const char *json, const char *blob, int blobLength)
	Create a document.
Btrieve::StatusCode	DocumentDelete (int id, int entityTag=-1)
	Delete a document.
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.
Btrieve::StatusCode	DocumentRetrieveBlob (int id, char *blob, int blobSize, int documentBlobOffset=0, int documentBlobLength=0)
	Retrieve a document blob.
int	DocumentRetrieveEntityTag (int id)
	Retrieve a document entity tag.
const char *	DocumentRetrieveJson (int id)
	Retrieve a document json.
const char *	DocumentRetrieveJson (int id, char *blob, int blobSize, int documentBlobOffset=0, int documentBlobLength=0)
	Retrieve a document json.
Btrieve::StatusCode	DocumentUpdate (int id, const char *json)
	Update a document.
Btrieve::StatusCode	DocumentUpdate (int id, const char *json, const char *blob, int blobLength)
	Update a document.
Btrieve::StatusCode	DocumentUpdate (int id, int entityTag, const char *json)
	Update a document.
Btrieve::StatusCode	DocumentUpdate (int id, int entityTag, const char *json, const char *blob, int blobLength)
	Update a document.
Btrieve::StatusCode	Encrypt (const char *password, const char *passwordAgain)
	Encrypt a collection.
Btrieve::StatusCode	GetLastStatusCode ()
	Get the last status code.
Btrieve::StatusCode	Query (BtrieveDocumentSet *btrieveDocumentSet, const char *query=NULL)
	Query the collection.

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

Examples

bcollection.cpp.

Constructor & Destructor Documentation

BtrieveCollection()

BtrieveCollection::BtrieveCollection

(

)

Snippet

C++ bcollection.cpp

   BtrieveCollection btrieveCollection;

Python bcollection.py

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

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.

Snippet

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

Return values

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

Examples

bcollection.cpp.

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,
		int	entityTag = -1 )

Delete a document.

Parameters

[in]	id	The identifier.
[in]	entityTag	The entity tag. The entity tag must either equal the entity tag of the document or -1.

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

This 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

DocumentRetrieveEntityTag()

int BtrieveCollection::DocumentRetrieveEntityTag

(

int

id

)

Retrieve a document entity tag.

Parameters

[in]

id

The identifier.

Return values

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

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.

Snippet

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

Return values

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

Examples

bcollection.cpp.

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

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

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

DocumentUpdate() [3/4]

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

Update a document.

Parameters

[in]	id	The identifier.
[in]	entityTag	The entity tag. The entity tag must either equal the entity tag of the document or -1.
[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() [4/4]

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

Update a document.

Parameters

[in]	id	The identifier.
[in]	entityTag	The entity tag. The entity tag must either equal the entity tag of the document or -1.
[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.

Snippet

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

Return values

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

See also

Btrieve::StatusCodeToString

Examples

bcollection.cpp.

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

Snippet

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

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

Examples

bcollection.cpp.