The Btrieve file class. More...

#include <btrieveCpp.h>

Public Member Functions
	BtrieveFile ()

	~BtrieveFile ()

Btrieve::StatusCode	BulkCreate (BtrieveBulkCreatePayload btrieveBulkCreatePayload, BtrieveBulkCreateResult btrieveBulkCreateResult)
	Bulk create. More...

Btrieve::StatusCode	BulkDeleteNext (BtrieveBulkDeleteAttributes bulkDeleteAttributes, BtrieveBulkDeleteResult bulkDeleteResult)
	Delete bulk next. More...

Btrieve::StatusCode	BulkDeletePrevious (BtrieveBulkDeleteAttributes bulkDeleteAttributes, BtrieveBulkDeleteResult bulkDeleteResult)
	Delete bulk previous. More...

Btrieve::StatusCode	BulkRetrieveNext (BtrieveBulkRetrieveAttributes bulkRetrieveAttributes, BtrieveBulkRetrieveResult bulkRetrieveResult, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve bulk next. More...

Btrieve::StatusCode	BulkRetrievePrevious (BtrieveBulkRetrieveAttributes bulkRetrieveAttributes, BtrieveBulkRetrieveResult bulkRetrieveResult, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve bulk previous. More...

long long	GetCursorPosition ()
	Get the cursor position. More...

Btrieve::StatusCode	GetInformation (BtrieveFileInformation *btrieveFileInformation)
	Get the file information. More...

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

int	GetNumerator (long long cursorPosition, int denominator)
	Get the numerator which best approximates the location of the cursor position within the file relative to the denominator. More...

int	GetNumerator (Btrieve::Index index, const char *key, int keyLength, int denominator)
	Get the numerator which best approximates the location of the key within the index relative to the denominator. More...

int	GetPercentage (long long cursorPosition)
	Get the percentage which best approximates the location of the cursor position within the file. More...

int	GetPercentage (Btrieve::Index index, const char *key, int keyLength)
	Get the percentage which best approximates the location of the key within the given index. More...

long long	GetRecordCreateTime ()
	Get the record create time. More...

long long	GetRecordUpdateTime ()
	Get the record update time. More...

Btrieve::StatusCode	IndexCreate (BtrieveIndexAttributes *btrieveIndexAttributes)
	Create an index. More...

Btrieve::StatusCode	IndexDrop (Btrieve::Index index)
	Drop an index. More...

Btrieve::StatusCode	KeyRetrieve (Btrieve::Comparison comparison, Btrieve::Index index, char *key, int keyLength)
	Retrieve a key using the given comparison, index, and key. More...

Btrieve::StatusCode	KeyRetrieveFirst (Btrieve::Index index, char *key, int keySize)
	Retrieve the first key. More...

Btrieve::StatusCode	KeyRetrieveLast (Btrieve::Index index, char *key, int keySize)
	Retrieve the last key. More...

Btrieve::StatusCode	KeyRetrieveNext (char *key, int keySize)
	Retrieve the next key. More...

Btrieve::StatusCode	KeyRetrievePrevious (char *key, int keySize)
	Retrieve the previous key. More...

Btrieve::StatusCode	RecordAppendChunk (const char *chunk, int chunkLength)
	Append a record chunk. More...

Btrieve::StatusCode	RecordCreate (char *record, int recordLength)
	Create a record. More...

Btrieve::StatusCode	RecordDelete ()
	Delete a record. More...

Btrieve::StatusCode	RecordDeleteChunk (int offset, int chunkLength)
	Delete a record chunk. More...

Btrieve::StatusCode	RecordDeleteChunk (int chunkLength)
	Delete a record chunk at the current offset. More...

Btrieve::StatusCode	RecordInsertChunk (int offset, const char *chunk, int chunkLength)
	Insert a record chunk. More...

Btrieve::StatusCode	RecordInsertChunk (const char *chunk, int chunkLength)
	Insert a record chunk at the current offset. More...

int	RecordRetrieve (Btrieve::Comparison comparison, Btrieve::Index index, char key, int keyLength, char record, int recordSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve a record using the given comparison, index, and key. More...

int	RecordRetrieveByCursorPosition (Btrieve::Index index, long long cursorPosition, char *record, int recordSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve a record by cursor position. More...

int	RecordRetrieveByCursorPosition (Btrieve::Index index, long long cursorPosition, char key, int keySize, char record, int recordSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve a record by cursor position. More...

int	RecordRetrieveByFraction (Btrieve::Index index, int numerator, int denominator, char *record, int recordSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve a record by fraction. More...

int	RecordRetrieveByFraction (Btrieve::Index index, int numerator, int denominator, char key, int keySize, char record, int recordSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve a record by fraction. More...

int	RecordRetrieveByPercentage (Btrieve::Index index, int percentage, char *record, int recordSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve a record by percentage. More...

int	RecordRetrieveByPercentage (Btrieve::Index index, int percentage, char key, int keySize, char record, int recordSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve a record by percentage. More...

int	RecordRetrieveChunk (int offset, int length, char *chunk, int chunkSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve a record chunk. More...

int	RecordRetrieveChunk (int length, char *chunk, int chunkSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve a record chunk at the current offset. More...

int	RecordRetrieveFirst (Btrieve::Index index, char *record, int recordSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve the first record. More...

int	RecordRetrieveFirst (Btrieve::Index index, char key, int keySize, char record, int recordSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve the first record. More...

int	RecordRetrieveLast (Btrieve::Index index, char *record, int recordSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve the last record. More...

int	RecordRetrieveLast (Btrieve::Index index, char key, int keySize, char record, int recordSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve the last record. More...

int	RecordRetrieveNext (char *record, int recordSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve the next record. More...

int	RecordRetrieveNext (char key, int keySize, char record, int recordSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve the next record. More...

int	RecordRetrievePrevious (char *record, int recordSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve the previous record. More...

int	RecordRetrievePrevious (char key, int keySize, char record, int recordSize, Btrieve::LockMode lockMode=Btrieve::LOCK_MODE_NONE)
	Retrieve the previous record. More...

Btrieve::StatusCode	RecordTruncate (int offset)
	Truncate a record. More...

Btrieve::StatusCode	RecordTruncate ()
	Truncate a record at the current offset. More...

Btrieve::StatusCode	RecordUnlock (Btrieve::UnlockMode unlockMode)
	Unlock a record or records. More...

Btrieve::StatusCode	RecordUpdate (const char *record, int recordLength)
	Update a record. More...

Btrieve::StatusCode	RecordUpdateChunk (int offset, const char *chunk, int chunkLength)
	Update a record chunk. More...

Btrieve::StatusCode	RecordUpdateChunk (const char *chunk, int chunkLength)
	Update a record chunk at the current offset. More...

Btrieve::StatusCode	SetOwner (Btrieve::OwnerMode ownerMode, const char ownerName=NULL, const char ownerNameAgain=NULL, bool useLongOwnerName=true)
	Set the owner. More...

Btrieve::StatusCode	UnlockCursorPosition (long long cursorPosition)
	Unlock the cursor position. More...

Detailed Description

The Btrieve file class.

In order to retrieve, update, and delete records in a Btrieve file the cursor must be established. The following methods are among those used to establish the cursor:

Once established, the cursor enables traversal over the records in the file. The following methods are among those used to traverse over the file:

The cursor may be re-established repeatedly.

Examples:: bfileattributes.cpp, bfileinformation.cpp, bfilter.cpp, bindexattributes.cpp, bkeyonly.cpp, block.cpp, bpercentage.cpp, btest.cpp, btestappend.cpp, btestbulk.cpp, btestchunk.cpp, btestvlr.cpp, and Test_BTRV2.cpp.

Constructor & Destructor Documentation

◆ BtrieveFile()

BtrieveFile::BtrieveFile ( )

Snippet: C++ btest.cpp
BtrieveFile btrieveFile;
Python btest.py
btrieveFile = btrievePython.BtrieveFile()
assert(btrieveFile != None)

See also: BtrieveClient::FileOpen

◆ ~BtrieveFile()

BtrieveFile::~BtrieveFile ( )

See also: BtrieveClient::FileClose

Member Function Documentation

◆ BulkCreate()

Btrieve::StatusCode BtrieveFile::BulkCreate	(	BtrieveBulkCreatePayload *	btrieveBulkCreatePayload,
		BtrieveBulkCreateResult *	btrieveBulkCreateResult
	)

Bulk create.

Parameters

[in]	btrieveBulkCreatePayload	The bulk create payload.
[out]	btrieveBulkCreateResult	The bulk create result.

Snippet: // If BulkCreate() fails.
if ((status = btrieveFile->BulkCreate(&btrieveBulkCreatePayload, &btrieveBulkCreateResult)) != Btrieve::STATUS_CODE_NO_ERROR)
{
printf("Error: BtrieveFile::BulkCreate():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is unaffected.

Current Offset: The current offset is unaffected.

Return values

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

See also: Btrieve::StatusCodeToString

Examples:: btestbulk.cpp.

◆ BulkDeleteNext()

Btrieve::StatusCode BtrieveFile::BulkDeleteNext	(	BtrieveBulkDeleteAttributes *	bulkDeleteAttributes,
		BtrieveBulkDeleteResult *	bulkDeleteResult
	)

Delete bulk next.

Parameters

[in]	bulkDeleteAttributes	The bulk delete attributes.
[out]	bulkDeleteResult	The bulk delete result.

Cursor: The cursor must be established. The cursor is traversed forward to the last record examined.

Current Offset: The current offset is destroyed.

Return values

= Btrieve::STATUS_CODE_END_OF_FILE	Success. Zero or more records were deleted. There are no more records matching the given bulk delete attributes.
= Btrieve::STATUS_CODE_NO_ERROR	Success. One or more records were deleted. There may be more records matching the given bulk delete attributes.
Otherwise	An error has occurred.

See also: Btrieve::StatusCodeToString

◆ BulkDeletePrevious()

Btrieve::StatusCode BtrieveFile::BulkDeletePrevious	(	BtrieveBulkDeleteAttributes *	bulkDeleteAttributes,
		BtrieveBulkDeleteResult *	bulkDeleteResult
	)

Delete bulk previous.

Parameters

[in]	bulkDeleteAttributes	The bulk delete attributes.
[out]	bulkDeleteResult	The bulk delete result.

Cursor: The cursor must be established. The cursor is traversed backwards to the last record examined.

Current Offset: The current offset is destroyed.

Return values

= Btrieve::STATUS_CODE_END_OF_FILE	Success. Zero or more records were deleted. There are no more records matching the given bulk delete attributes.
= Btrieve::STATUS_CODE_NO_ERROR	Success. One or more records were deleted. There may be more records matching the given bulk delete attributes.
Otherwise	An error has occurred.

See also: Btrieve::StatusCodeToString

◆ BulkRetrieveNext()

Btrieve::StatusCode BtrieveFile::BulkRetrieveNext	(	BtrieveBulkRetrieveAttributes *	bulkRetrieveAttributes,
		BtrieveBulkRetrieveResult *	bulkRetrieveResult,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve bulk next.

Parameters

[in]	bulkRetrieveAttributes	The bulk retrieve attributes.
[out]	bulkRetrieveResult	The bulk retrieve result.
[in]	lockMode	The lock mode.

Snippet: // If BulkRetrieveNext() fails.
if ((status = btrieveFile->BulkRetrieveNext(&btrieveBulkRetrieveAttributes, &btrieveBulkRetrieveResult)) != Btrieve::STATUS_CODE_NO_ERROR)
{
printf("Error: BtrieveFile::BulkRetrieveNext():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor must be established. The cursor is traversed forward to the last record examined.

Current Offset: The current offset is destroyed.

Return values

= Btrieve::STATUS_CODE_END_OF_FILE	Success. Zero or more records were retrieved. There are no more records matching the given bulk retrieve attributes.
= Btrieve::STATUS_CODE_NO_ERROR	Success. One or more records were retrieved. There may be more records matching the given bulk retrieve attributes.
Otherwise	An error has occurred.

See also: Btrieve::StatusCodeToString

Examples:: bfilter.cpp, and btestbulk.cpp.

◆ BulkRetrievePrevious()

Btrieve::StatusCode BtrieveFile::BulkRetrievePrevious	(	BtrieveBulkRetrieveAttributes *	bulkRetrieveAttributes,
		BtrieveBulkRetrieveResult *	bulkRetrieveResult,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve bulk previous.

Parameters

[in]	bulkRetrieveAttributes	The bulk retrieve attributes.
[out]	bulkRetrieveResult	The bulk retrieve result.
[in]	lockMode	The lock mode.

Cursor: The cursor must be established. The cursor is traversed backwards to the last record examined.

Current Offset: The current offset is destroyed.

Return values

= Btrieve::STATUS_CODE_END_OF_FILE	Success. Zero or more records were retrieved. There are no more records matching the given bulk retrieve attributes.
= Btrieve::STATUS_CODE_NO_ERROR	Success. One or more records were retrieved. There may be more records matching the given bulk retrieve attributes.
Otherwise	An error has occurred.

See also: Btrieve::StatusCodeToString

◆ GetCursorPosition()

long long BtrieveFile::GetCursorPosition ( )

Get the cursor position.

Note: The signature for this method changed in PSQL v13 R2.

Snippet: // If GetCursorPosition() fails.
if ((cursorPosition = btrieveFile->GetCursorPosition()) == -1)
{
status = btrieveFile->GetLastStatusCode();
printf("Error: BtrieveFile::GetCursorPosition():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is unaffected but must be established.

Current Offset: The current offset is unaffected.

Return values

>= 0	The cursor position.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

Examples:: bpercentage.cpp.

◆ GetInformation()

Btrieve::StatusCode BtrieveFile::GetInformation ( BtrieveFileInformation * btrieveFileInformation )

Get the file information.

Parameters

[out] btrieveFileInformation The file information.

Snippet: // If GetInformation() fails.
if ((status = btrieveFile->GetInformation(&btrieveFileInformation)) != Btrieve::STATUS_CODE_NO_ERROR)
{
printf("Error: BtrieveFile::GetInformation():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is unaffected.

Current Offset: The current offset is unaffected.

Return values

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

See also: Btrieve::StatusCodeToString

Examples:: bfileattributes.cpp, and bfileinformation.cpp.

◆ GetLastStatusCode()

Btrieve::StatusCode BtrieveFile::GetLastStatusCode ( )

Get the last status code.

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

Snippet: C++ btest.cpp
// If RecordRetrieve() fails.
if (btrieveFile->RecordRetrieve(Btrieve::COMPARISON_EQUAL, Btrieve::INDEX_1, (char *)key, sizeof(*key), (char *)&record, sizeof(record)) != sizeof(record))
{
status = btrieveFile->GetLastStatusCode();
printf("Error: BtrieveFile::RecordRetrieve():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}
Python btest.py
rc = btrieveFile.RecordRetrieve(btrievePython.Btrieve.COMPARISON_EQUAL,btrievePython.Btrieve.INDEX_1, key, record)
assert(rc == recordLength), "Error: BtrieveFileRecordRetrieveEqual():%d:%s.\n" % (rc, btrievePython.Btrieve_StatusCodeToString(btrieveFile.GetLastStatusCode()))

Cursor: The cursor is unaffected.

Current Offset: The current offset is unaffected.

Return values

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

See also: Btrieve::StatusCodeToString

Examples:: bfilter.cpp, bindexattributes.cpp, block.cpp, bpercentage.cpp, btest.cpp, btestappend.cpp, btestbulk.cpp, btestchunk.cpp, btestvlr.cpp, and Test_BTRV2.cpp.

◆ GetNumerator() [1/2]

int BtrieveFile::GetNumerator	(	long long	cursorPosition,
		int	denominator
	)

Get the numerator which best approximates the location of the cursor position within the file relative to the denominator.

Note: The signature for this method changed in PSQL v13 R2.

Parameters

[in]	cursorPosition	The cursor position.
[in]	denominator	The denominator.

Snippet: // If GetNumerator() fails.
if ((numerator = btrieveFile->GetNumerator(cursorPosition, NUMBER_OF_RECORDS)) == -1)
{
status = btrieveFile->GetLastStatusCode();
printf("Error: BtrieveFile::GetNumerator():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is unaffected.

Current Offset: The current offset is unaffected.

Return values

>= 0	The numerator returned as 0 through denominator.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

Examples:: bpercentage.cpp.

◆ GetNumerator() [2/2]

int BtrieveFile::GetNumerator	(	Btrieve::Index	index,
		const char *	key,
		int	keyLength,
		int	denominator
	)

Get the numerator which best approximates the location of the key within the index relative to the denominator.

Parameters

[in]	index	The index.
[in]	key	The key.
[in]	keyLength	The key length.
[in]	denominator	The denominator.

Snippet: // If GetNumerator() fails.
if ((numerator = btrieveFile->GetNumerator(Btrieve::INDEX_1, (char *)&key, sizeof(key), NUMBER_OF_RECORDS)) == -1)
{
status = btrieveFile->GetLastStatusCode();
printf("Error: BtrieveFile::GetNumerator():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is unaffected.

Current Offset: The current offset is unaffected.

Return values

>= 0	The numerator returned as 0 through denominator.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

◆ GetPercentage() [1/2]

int BtrieveFile::GetPercentage ( long long cursorPosition )

Get the percentage which best approximates the location of the cursor position within the file.

Note: The signature for this method changed in PSQL v13 R2.

Parameters

[in] cursorPosition The cursor position.

Snippet: // If GetPercentage() fails.
if ((percentage = btrieveFile->GetPercentage(cursorPosition)) == -1)
{
status = btrieveFile->GetLastStatusCode();
printf("Error: BtrieveFile::GetPercentage():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is unaffected.

Current Offset: The current offset is unaffected.

Return values

>= 0	The percentage returned as 0 through 10,000, corresponding to 0% through 100.00%.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

Examples:: bpercentage.cpp.

◆ GetPercentage() [2/2]

int BtrieveFile::GetPercentage	(	Btrieve::Index	index,
		const char *	key,
		int	keyLength
	)

Get the percentage which best approximates the location of the key within the given index.

Parameters

[in]	index	The index.
[in]	key	The key.
[in]	keyLength	The key length.

Snippet: // If GetPercentage() fails.
if ((percentage = btrieveFile->GetPercentage(Btrieve::INDEX_1, (char *)&key, sizeof(key))) == -1)
{
status = btrieveFile->GetLastStatusCode();
printf("Error: BtrieveFile::GetPercentage():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is unaffected.

Current Offset: The current offset is unaffected.

Return values

>= 0	The percentage returned as 0 through 10,000, corresponding to 0% through 100.00%.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

◆ GetRecordCreateTime()

long long BtrieveFile::GetRecordCreateTime ( )

Get the record create time.

Cursor: The cursor is unaffected but must be established.

Current Offset: The current offset is unaffected.

Return values

> 0	The record create time as a Btrieve timestamp.
= 0	The record create time is unavailable. Ensure the file was created with system data. See BtrieveFileAttributes::SetSystemDataMode.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

See also: Btrieve::TimestampToUnixEpochMicroseconds

◆ GetRecordUpdateTime()

long long BtrieveFile::GetRecordUpdateTime ( )

Get the record update time.

Cursor: The cursor is unaffected but must be established.

Current Offset: The current offset is unaffected.

Return values

> 0	The record update time as a Btrieve timestamp.
= 0	The record update time is unavailable. Ensure the file was created with system data version 2. See BtrieveFileAttributes::SetSystemDataMode.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

See also: Btrieve::TimestampToUnixEpochMicroseconds

◆ IndexCreate()

Btrieve::StatusCode BtrieveFile::IndexCreate ( BtrieveIndexAttributes * btrieveIndexAttributes )

Create an index.

Parameters

[in] btrieveIndexAttributes The index attributes.

Snippet: C++ btest.cpp
// If IndexCreate() fails.
if ((status = btrieveFile->IndexCreate(&btrieveIndexAttributes)) != Btrieve::STATUS_CODE_NO_ERROR)
{
printf("Error: BtrieveFile::IndexCreate():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}
Python btest.py
rc = btrieveFile.IndexCreate(btrieveIndexAttributes)
assert(rc == btrievePython.Btrieve.STATUS_CODE_NO_ERROR), "Error: BtrieveFile::IndexCreate():%d:%s.\n" % (rc, btrievePython.Btrieve_StatusCodeToString(rc))

Cursor: The cursor is unaffected.

Current Offset: The current offset is unaffected.

Return values

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

See also: Btrieve::StatusCodeToString

Examples:: bfilter.cpp, bindexattributes.cpp, block.cpp, bpercentage.cpp, btest.cpp, btestvlr.cpp, and Test_BTRV2.cpp.

◆ IndexDrop()

Btrieve::StatusCode BtrieveFile::IndexDrop ( Btrieve::Index index )

Drop an index.

Parameters

[in] index The index.

Cursor: If the cursor index is dropped the cursor is destroyed. Otherwise, the cursor is unaffected.

Current Offset: The current offset is unaffected.

Return values

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

See also: Btrieve::StatusCodeToString

◆ KeyRetrieve()

Btrieve::StatusCode BtrieveFile::KeyRetrieve	(	Btrieve::Comparison	comparison,
		Btrieve::Index	index,
		char *	key,
		int	keyLength
	)

Retrieve a key using the given comparison, index, and key.

Note: The signature for this method changed in PSQL v15 R0.

Parameters

[in]	comparison	The comparison. Btrieve::COMPARISON_NOT_EQUAL isn't supported.
[in]	index	The index.
[in,out]	key	The key.
[in]	keyLength	The key length.

Snippet: // If KeyRetrieve() fails.
if ((status = btrieveFile->KeyRetrieve(Btrieve::COMPARISON_EQUAL, Btrieve::INDEX_1, (char *)key, sizeof(*key))) == Btrieve::STATUS_CODE_NO_ERROR)
{
printf("%u is prime.\n", *key);
goto leave;
}
if (status == Btrieve::STATUS_CODE_KEY_VALUE_NOT_FOUND)
{
printf("%u is not prime.\n", *key);
status = Btrieve::STATUS_CODE_NO_ERROR;
goto leave;
}
printf("Error: BtrieveClient::KeyRetrieve():%d:%s.\n", status, Btrieve::StatusCodeToString(status));

Cursor: The cursor is established.

Current Offset: The current offset is destroyed.

Return values

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

See also: Btrieve::StatusCodeToString

Examples:: bkeyonly.cpp.

◆ KeyRetrieveFirst()

Btrieve::StatusCode BtrieveFile::KeyRetrieveFirst	(	Btrieve::Index	index,
		char *	key,
		int	keySize
	)

Retrieve the first key.

Parameters

[in]	index	The index.
[out]	key	The key.
[in]	keySize	The key size.

Cursor: The cursor is established.

Current Offset: The current offset is destroyed.

Return values

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

See also: Btrieve::StatusCodeToString

◆ KeyRetrieveLast()

Btrieve::StatusCode BtrieveFile::KeyRetrieveLast	(	Btrieve::Index	index,
		char *	key,
		int	keySize
	)

Retrieve the last key.

Parameters

[in]	index	The index.
[out]	key	The key.
[in]	keySize	The key size.

Cursor: The cursor is established.

Current Offset: The current offset is destroyed.

Return values

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

See also: Btrieve::StatusCodeToString

◆ KeyRetrieveNext()

Btrieve::StatusCode BtrieveFile::KeyRetrieveNext	(	char *	key,
		int	keySize
	)

Retrieve the next key.

Parameters

[out]	key	The key.
[in]	keySize	The key size.

Cursor: The cursor must be established. The cursor is traversed forward one key.

Current Offset: The current offset is destroyed.

Return values

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

See also: Btrieve::StatusCodeToString

◆ KeyRetrievePrevious()

Btrieve::StatusCode BtrieveFile::KeyRetrievePrevious	(	char *	key,
		int	keySize
	)

Retrieve the previous key.

Parameters

[out]	key	The key.
[in]	keySize	The key size.

Cursor: The cursor must be established. The cursor is traversed backward one key.

Current Offset: The current offset is destroyed.

Return values

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

See also: Btrieve::StatusCodeToString

◆ RecordAppendChunk()

Btrieve::StatusCode BtrieveFile::RecordAppendChunk	(	const char *	chunk,
		int	chunkLength
	)

Append a record chunk.

Parameters

[in]	chunk	The chunk.
[in]	chunkLength	The chunk length.

Description: The file must have variable length records. See BtrieveFileAttributes::SetVariableLengthRecordsMode.

Snippet: // If RecordAppendChunk() fails.
if ((status = btrieveFile->RecordAppendChunk((char *)&chunk, sizeof(chunk))) != Btrieve::STATUS_CODE_NO_ERROR)
{
printf("Error: BtrieveFile::RecordAppendChunk():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is unaffected but must be established.

Current Offset: The current offset is established at the end of the appended chunk.

Return values

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

See also: Btrieve::StatusCodeToString

Examples:: btestappend.cpp.

◆ RecordCreate()

Btrieve::StatusCode BtrieveFile::RecordCreate	(	char *	record,
		int	recordLength
	)

Create a record.

Note: The signature for this method changed in PSQL v13 R2.

Parameters

[in,out]	record	The record. If the current record contains a Btrieve::DATA_TYPE_AUTOINCREMENT or Btrieve::DATA_TYPE_AUTOTIMESTAMP key segment then the passed in record may be modifed.
[in]	recordLength	The record length. Record length is limited to Btrieve::MAXIMUM_RECORD_LENGTH bytes. See BtrieveFile::RecordAppendChunk for creating records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length.

Snippet: C++ btest.cpp
// If RecordCreate() fails.
if ((status = btrieveFile->RecordCreate((char *)&record, sizeof(record))) != Btrieve::STATUS_CODE_NO_ERROR)
{
printf("Error: BtrieveFile::RecordCreate():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}
Python btest.py
rc = btrieveFile.RecordCreate(record)
assert(rc == btrievePython.Btrieve.STATUS_CODE_NO_ERROR), "Error: BtrieveFile::RecordCreate():%d:%s.\n" % (rc, btrievePython.Btrieve_StatusCodeToString(rc))

Cursor: The cursor is established.

Current Offset: The current offset is unaffected.

Return values

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

See also: Btrieve::StatusCodeToString

Examples:: bfilter.cpp, bindexattributes.cpp, bkeyonly.cpp, block.cpp, bpercentage.cpp, btest.cpp, btestappend.cpp, btestchunk.cpp, btestvlr.cpp, and Test_BTRV2.cpp.

◆ RecordDelete()

Btrieve::StatusCode BtrieveFile::RecordDelete ( )

Delete a record.

Snippet: // If RecordDelete() fails.
if ((status = btrieveFile->RecordDelete()) != Btrieve::STATUS_CODE_NO_ERROR)
{
printf("Error: BtrieveFile::RecordDelete():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is unaffected but must be established.

Current Offset: The current offset is destroyed.

Return values

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

See also: Btrieve::StatusCodeToString

Examples:: bkeyonly.cpp.

◆ RecordDeleteChunk() [1/2]

Btrieve::StatusCode BtrieveFile::RecordDeleteChunk	(	int	offset,
		int	chunkLength
	)

Delete a record chunk.

Parameters

[in]	offset	The offset. If offset is -1, then the current offset is used. Offset must be within the variable length portion of the record.
[in]	chunkLength	The chunk length.

Description: The file must have variable length records. See BtrieveFileAttributes::SetVariableLengthRecordsMode.

Cursor: The cursor is unaffected but must be established.

Current Offset: The current offset is established at the end of the deleted chunk.

Return values

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

◆ RecordDeleteChunk() [2/2]

Btrieve::StatusCode BtrieveFile::RecordDeleteChunk ( int chunkLength )

Delete a record chunk at the current offset.

Parameters

[in] chunkLength The chunk length.

Description: The file must have variable length records. See BtrieveFileAttributes::SetVariableLengthRecordsMode.

Cursor: The cursor is unaffected but must be established.

Current Offset: The current offset must be established and is then traversed forward to the end of the deleted chunk.

Return values

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

◆ RecordInsertChunk() [1/2]

Btrieve::StatusCode BtrieveFile::RecordInsertChunk	(	int	offset,
		const char *	chunk,
		int	chunkLength
	)

Insert a record chunk.

Parameters

[in]	offset	The offset. If offset is -1, then the current offset is used. Offset must be within the variable length portion of the record.
[in]	chunk	The chunk.
[in]	chunkLength	The chunk length.

Description: The file must have variable length records. See BtrieveFileAttributes::SetVariableLengthRecordsMode.

Cursor: The cursor is unaffected but must be established.

Current Offset: The current offset is established at the end of the inserted chunk.

Return values

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

◆ RecordInsertChunk() [2/2]

Btrieve::StatusCode BtrieveFile::RecordInsertChunk	(	const char *	chunk,
		int	chunkLength
	)

Insert a record chunk at the current offset.

Parameters

[in]	chunk	The chunk.
[in]	chunkLength	The chunk length.

Description: The file must have variable length records. See BtrieveFileAttributes::SetVariableLengthRecordsMode.

Cursor: The cursor is unaffected but must be established.

Current Offset: The current offset must be established and is then traversed forward to the end of the inserted chunk.

Return values

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

◆ RecordRetrieve()

int BtrieveFile::RecordRetrieve	(	Btrieve::Comparison	comparison,
		Btrieve::Index	index,
		char *	key,
		int	keyLength,
		char *	record,
		int	recordSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve a record using the given comparison, index, and key.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.; The signature for this method changed in PSQL v15 R0.

Parameters

[in]	comparison	The comparison. Btrieve::COMPARISON_NOT_EQUAL isn't supported.
[in]	index	The index.
[in,out]	key	The key.
[in]	keyLength	The key length.
[out]	record	The record.
[in]	recordSize	The record size.
[in]	lockMode	The lock mode.

Snippet: C++ btest.cpp
// If RecordRetrieve() fails.
if (btrieveFile->RecordRetrieve(Btrieve::COMPARISON_EQUAL, Btrieve::INDEX_1, (char *)key, sizeof(*key), (char *)&record, sizeof(record)) != sizeof(record))
{
status = btrieveFile->GetLastStatusCode();
printf("Error: BtrieveFile::RecordRetrieve():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}
Python btest.py
rc = btrieveFile.RecordRetrieve(btrievePython.Btrieve.COMPARISON_EQUAL,btrievePython.Btrieve.INDEX_1, key, record)
assert(rc == recordLength), "Error: BtrieveFileRecordRetrieveEqual():%d:%s.\n" % (rc, btrievePython.Btrieve_StatusCodeToString(btrieveFile.GetLastStatusCode()))

Cursor: The cursor is established.

Current Offset: The current offset is destroyed.

Return values

>= 0	The number of bytes read. The number of bytes read is limited to Btrieve::MAXIMUM_RECORD_LENGTH. See BtrieveFile::RecordRetrieveChunk for retrieving records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length. If the record size requested is less than the length of the current record then BtrieveFile::GetLastStatusCode will return Btrieve::STATUS_CODE_DATALENGTH_ERROR.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

Examples:: bkeyonly.cpp, btest.cpp, and btestvlr.cpp.

◆ RecordRetrieveByCursorPosition() [1/2]

int BtrieveFile::RecordRetrieveByCursorPosition	(	Btrieve::Index	index,
		long long	cursorPosition,
		char *	record,
		int	recordSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve a record by cursor position.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.; The signature for this method changed in PSQL v13 R2.

Parameters

[in]	index	An index or Btrieve::INDEX_NONE.
[in]	cursorPosition	The cursor position.
[out]	record	The record.
[in]	recordSize	The record size.
[in]	lockMode	The lock mode.

Snippet: // If RecordRetrieveByCursorPosition() fails.
if (btrieveFile->RecordRetrieveByCursorPosition(Btrieve::INDEX_1, cursorPosition, (char *)&record, sizeof(record)) != sizeof(record))
{
printf("Error: BtrieveFileAttributes::RecordRetrieveByCursorPosition():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is established.

Current Offset: The current offset is destroyed.

Return values

>= 0	The number of bytes read. The number of bytes read is limited to Btrieve::MAXIMUM_RECORD_LENGTH. See BtrieveFile::RecordRetrieveChunk for retrieving records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length. If the record size requested is less than the length of the current record then BtrieveFile::GetLastStatusCode will return Btrieve::STATUS_CODE_DATALENGTH_ERROR.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

Examples:: bpercentage.cpp.

◆ RecordRetrieveByCursorPosition() [2/2]

int BtrieveFile::RecordRetrieveByCursorPosition	(	Btrieve::Index	index,
		long long	cursorPosition,
		char *	key,
		int	keySize,
		char *	record,
		int	recordSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve a record by cursor position.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.

Parameters

[in]	index	An index or Btrieve::INDEX_NONE.
[in]	cursorPosition	The cursor position.
[out]	key	The key.
[in]	keySize	The key size.
[out]	record	The record.
[in]	recordSize	The record size.
[in]	lockMode	The lock mode.

Cursor: The cursor is established.

Current Offset: The current offset is destroyed.

Return values

>= 0	The number of bytes read. The number of bytes read is limited to Btrieve::MAXIMUM_RECORD_LENGTH. See BtrieveFile::RecordRetrieveChunk for retrieving records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length. If the record size requested is less than the length of the current record then BtrieveFile::GetLastStatusCode will return Btrieve::STATUS_CODE_DATALENGTH_ERROR.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

◆ RecordRetrieveByFraction() [1/2]

int BtrieveFile::RecordRetrieveByFraction	(	Btrieve::Index	index,
		int	numerator,
		int	denominator,
		char *	record,
		int	recordSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve a record by fraction.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.

Parameters

[in]	index	An index or Btrieve::INDEX_NONE.
[in]	numerator	The numerator given as 0 through denominator.
[in]	denominator	The denominator.
[out]	record	The record.
[in]	recordSize	The record size.
[in]	lockMode	The lock mode.

Snippet: // If RecordRetrieveByFraction() fails.
if (btrieveFile->RecordRetrieveByFraction(Btrieve::INDEX_1, NUMBER_OF_RECORDS / 2, NUMBER_OF_RECORDS, (char *)&record, sizeof(record)) != sizeof(record))
{
status = btrieveFile->GetLastStatusCode();
printf("Error: BtrieveFile::RecordRetrieveByFraction():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is established.

Current Offset: The current offset is destroyed.

Return values

>= 0	The number of bytes read. The number of bytes read is limited to Btrieve::MAXIMUM_RECORD_LENGTH. See BtrieveFile::RecordRetrieveChunk for retrieving records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length. If the record size requested is less than the length of the current record then BtrieveFile::GetLastStatusCode will return Btrieve::STATUS_CODE_DATALENGTH_ERROR.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

Examples:: bpercentage.cpp.

◆ RecordRetrieveByFraction() [2/2]

int BtrieveFile::RecordRetrieveByFraction	(	Btrieve::Index	index,
		int	numerator,
		int	denominator,
		char *	key,
		int	keySize,
		char *	record,
		int	recordSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve a record by fraction.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.

Parameters

[in]	index	An index or Btrieve::INDEX_NONE.
[in]	numerator	The numerator given as 0 through denominator.
[in]	denominator	The denominator.
[out]	key	The key.
[in]	keySize	The key size.
[out]	record	The record.
[in]	recordSize	The record size.
[in]	lockMode	The lock mode.

Cursor: The cursor is established.

Current Offset: The current offset is destroyed.

Return values

>= 0	The number of bytes read. The number of bytes read is limited to Btrieve::MAXIMUM_RECORD_LENGTH. See BtrieveFile::RecordRetrieveChunk for retrieving records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length. If the record size requested is less than the length of the current record then BtrieveFile::GetLastStatusCode will return Btrieve::STATUS_CODE_DATALENGTH_ERROR.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

◆ RecordRetrieveByPercentage() [1/2]

int BtrieveFile::RecordRetrieveByPercentage	(	Btrieve::Index	index,
		int	percentage,
		char *	record,
		int	recordSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve a record by percentage.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.

Parameters

[in]	index	An index or Btrieve::INDEX_NONE.
[in]	percentage	The percentage given as 0 through 10,000, corresponding to 0% through 100.00%.
[out]	record	The record.
[in]	recordSize	The record size.
[in]	lockMode	The lock mode.

Snippet: // If RecordRetrieveByPercentage() fails.
if (btrieveFile->RecordRetrieveByPercentage(Btrieve::INDEX_1, 5000, (char *)&record, sizeof(record)) != sizeof(record))
{
status = btrieveFile->GetLastStatusCode();
printf("Error: BtrieveFile::RecordRetrieveByPercentage():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is established.

Current Offset: The current offset is destroyed.

Return values

>= 0	The number of bytes read. The number of bytes read is limited to Btrieve::MAXIMUM_RECORD_LENGTH. See BtrieveFile::RecordRetrieveChunk for retrieving records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length. If the record size requested is less than the length of the current record then BtrieveFile::GetLastStatusCode will return Btrieve::STATUS_CODE_DATALENGTH_ERROR.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

Examples:: bpercentage.cpp.

◆ RecordRetrieveByPercentage() [2/2]

int BtrieveFile::RecordRetrieveByPercentage	(	Btrieve::Index	index,
		int	percentage,
		char *	key,
		int	keySize,
		char *	record,
		int	recordSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve a record by percentage.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.

Parameters

[in]	index	An index or Btrieve::INDEX_NONE.
[in]	percentage	The percentage given as 0 through 10,000, corresponding to 0% through 100.00%.
[out]	key	The key.
[in]	keySize	The key size.
[out]	record	The record.
[in]	recordSize	The record size.
[in]	lockMode	The lock mode.

Cursor: The cursor is established.

Current Offset: The current offset is destroyed.

Return values

>= 0	The number of bytes read. The number of bytes read is limited to Btrieve::MAXIMUM_RECORD_LENGTH. See BtrieveFile::RecordRetrieveChunk for retrieving records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length. If the record size requested is less than the length of the current record then BtrieveFile::GetLastStatusCode will return Btrieve::STATUS_CODE_DATALENGTH_ERROR.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

◆ RecordRetrieveChunk() [1/2]

int BtrieveFile::RecordRetrieveChunk	(	int	offset,
		int	length,
		char *	chunk,
		int	chunkSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve a record chunk.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.

Parameters

[in]	offset	The offset. If offset is -1, then the current offset is used.
[in]	length	The length.
[out]	chunk	The chunk.
[in]	chunkSize	The chunk size.
[in]	lockMode	The lock mode.

Snippet: // If RecordRetrieveChunk() fails.
if (btrieveFile->RecordRetrieveChunk(0, sizeof(chunk), (char *)&chunk, sizeof(chunk)) != sizeof(chunk))
{
status = btrieveFile->GetLastStatusCode();
printf("Error: BtrieveFile::RecordRetrieveChunk():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is unaffected but must be established.

Current Offset: The current offset is established at the end of the retrieved chunk.

Return values

>= 0	The number of bytes read. You may retrieve multiple chunks.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

Examples:: btestappend.cpp, and btestchunk.cpp.

◆ RecordRetrieveChunk() [2/2]

int BtrieveFile::RecordRetrieveChunk	(	int	length,
		char *	chunk,
		int	chunkSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve a record chunk at the current offset.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.

Parameters

[in]	length	The length.
[out]	chunk	The chunk.
[in]	chunkSize	The chunk size.
[in]	lockMode	The lock mode.

Snippet: // If RecordRetrieveChunk() fails.
if (btrieveFile->RecordRetrieveChunk(sizeof(chunk), (char *)&chunk, sizeof(chunk)) != sizeof(chunk))
{
status = btrieveFile->GetLastStatusCode();
printf("Error: BtrieveFile::RecordRetrieveChunk():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is unaffected but must be established.

Current Offset: The current offset must be established and is then traversed forward to the end of the retrieved chunk.

Return values

>= 0	The number of bytes read. You may retrieve multiple chunks.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

◆ RecordRetrieveFirst() [1/2]

int BtrieveFile::RecordRetrieveFirst	(	Btrieve::Index	index,
		char *	record,
		int	recordSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve the first record.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.

Parameters

[in]	index	An index or Btrieve::INDEX_NONE.
[out]	record	The record.
[in]	recordSize	The record size.
[in]	lockMode	The lock mode.

Snippet: // If RecordRetrieveFirst() fails.
if (btrieveFile->RecordRetrieveFirst(Btrieve::INDEX_NONE, (char *)&record, sizeof(record)) != sizeof(record))
{
status = btrieveFile->GetLastStatusCode();
printf("Error: BtrieveFile::RecordRetrieveFirst():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is established.

Current Offset: The current offset is destroyed.

Return values

>= 0	The number of bytes read. The number of bytes read is limited to Btrieve::MAXIMUM_RECORD_LENGTH. See BtrieveFile::RecordRetrieveChunk for retrieving records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length. If the record size requested is less than the length of the current record then BtrieveFile::GetLastStatusCode will return Btrieve::STATUS_CODE_DATALENGTH_ERROR.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

Examples:: bfilter.cpp, bindexattributes.cpp, block.cpp, bpercentage.cpp, btestappend.cpp, btestbulk.cpp, and btestchunk.cpp.

◆ RecordRetrieveFirst() [2/2]

int BtrieveFile::RecordRetrieveFirst	(	Btrieve::Index	index,
		char *	key,
		int	keySize,
		char *	record,
		int	recordSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve the first record.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.

Parameters

[in]	index	An index or Btrieve::INDEX_NONE.
[out]	key	The key.
[in]	keySize	The key size.
[out]	record	The record.
[in]	recordSize	The record size.
[in]	lockMode	The lock mode.

Cursor: The cursor is established.

Current Offset: The current offset is destroyed.

Return values

>= 0	The number of bytes read. The number of bytes read is limited to Btrieve::MAXIMUM_RECORD_LENGTH. See BtrieveFile::RecordRetrieveChunk for retrieving records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length. If the record size requested is less than the length of the current record then BtrieveFile::GetLastStatusCode will return Btrieve::STATUS_CODE_DATALENGTH_ERROR.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

◆ RecordRetrieveLast() [1/2]

int BtrieveFile::RecordRetrieveLast	(	Btrieve::Index	index,
		char *	record,
		int	recordSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve the last record.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.

Parameters

[in]	index	An index or Btrieve::INDEX_NONE.
[out]	record	The record.
[in]	recordSize	The record size.
[in]	lockMode	The lock mode.

Snippet: // If RecordRetrieveLast() fails.
if (btrieveFile->RecordRetrieveLast(Btrieve::INDEX_1, (char *)&record, sizeof(record)) != sizeof(record))
{
status = btrieveFile->GetLastStatusCode();
printf("Error: BtrieveFile::RecordRetrieveLast():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is established.

Current Offset: The current offset is destroyed.

Return values

>= 0	The number of bytes read. The number of bytes read is limited to Btrieve::MAXIMUM_RECORD_LENGTH. See BtrieveFile::RecordRetrieveChunk for retrieving records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length. If the record size requested is less than the length of the current record then BtrieveFile::GetLastStatusCode will return Btrieve::STATUS_CODE_DATALENGTH_ERROR.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

Examples:: bpercentage.cpp, and Test_BTRV2.cpp.

◆ RecordRetrieveLast() [2/2]

int BtrieveFile::RecordRetrieveLast	(	Btrieve::Index	index,
		char *	key,
		int	keySize,
		char *	record,
		int	recordSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve the last record.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.

Parameters

[in]	index	An index or Btrieve::INDEX_NONE.
[out]	key	The key.
[in]	keySize	The key size.
[out]	record	The record.
[in]	recordSize	The record size.
[in]	lockMode	The lock mode.

Cursor: The cursor is established.

Current Offset: The current offset is destroyed.

Return values

>= 0	The number of bytes read. The number of bytes read is limited to Btrieve::MAXIMUM_RECORD_LENGTH. See BtrieveFile::RecordRetrieveChunk for retrieving records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length. If the record size requested is less than the length of the current record then BtrieveFile::GetLastStatusCode will return Btrieve::STATUS_CODE_DATALENGTH_ERROR.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

◆ RecordRetrieveNext() [1/2]

int BtrieveFile::RecordRetrieveNext	(	char *	record,
		int	recordSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve the next record.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.

Parameters

[out]	record	The record.
[in]	recordSize	The record size.
[in]	lockMode	The lock mode.

Snippet: // If RecordRetrieveNext() fails.
if (btrieveFile->RecordRetrieveNext((char *)&record, sizeof(record)) != sizeof(record))
{
status = btrieveFile->GetLastStatusCode();
printf("Error: BtrieveFile::RecordRetrieveNext():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}
}

Cursor: The cursor must be established. The cursor is traversed forward one record.

Current Offset: The current offset is destroyed.

Return values

>= 0	The number of bytes read. The number of bytes read is limited to Btrieve::MAXIMUM_RECORD_LENGTH. See BtrieveFile::RecordRetrieveChunk for retrieving records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length. If the record size requested is less than the length of the current record then BtrieveFile::GetLastStatusCode will return Btrieve::STATUS_CODE_DATALENGTH_ERROR.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

Examples:: bindexattributes.cpp.

◆ RecordRetrieveNext() [2/2]

int BtrieveFile::RecordRetrieveNext	(	char *	key,
		int	keySize,
		char *	record,
		int	recordSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve the next record.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.

Parameters

[out]	key	The key.
[in]	keySize	The key size.
[out]	record	The record.
[in]	recordSize	The record size.
[in]	lockMode	The lock mode.

Cursor: The cursor must be established. The cursor is traversed forward one record.

Current Offset: The current offset is destroyed.

Return values

>= 0	The number of bytes read. The number of bytes read is limited to Btrieve::MAXIMUM_RECORD_LENGTH. See BtrieveFile::RecordRetrieveChunk for retrieving records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length. If the record size requested is less than the length of the current record then BtrieveFile::GetLastStatusCode will return Btrieve::STATUS_CODE_DATALENGTH_ERROR.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

◆ RecordRetrievePrevious() [1/2]

int BtrieveFile::RecordRetrievePrevious	(	char *	record,
		int	recordSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve the previous record.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.

Parameters

[out]	record	The record.
[in]	recordSize	The record size.
[in]	lockMode	The lock mode.

Cursor: The cursor must be established. The cursor is traversed backward one record.

Current Offset: The current offset is destroyed.

Return values

>= 0	The number of bytes read. The number of bytes read is limited to Btrieve::MAXIMUM_RECORD_LENGTH. See BtrieveFile::RecordRetrieveChunk for retrieving records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length. If the record size requested is less than the length of the current record then BtrieveFile::GetLastStatusCode will return Btrieve::STATUS_CODE_DATALENGTH_ERROR.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

◆ RecordRetrievePrevious() [2/2]

int BtrieveFile::RecordRetrievePrevious	(	char *	key,
		int	keySize,
		char *	record,
		int	recordSize,
		Btrieve::LockMode	lockMode = `Btrieve::LOCK_MODE_NONE`
	)

Retrieve the previous record.

Note: This method doesn't return a Btrieve::StatusCode. See below for more information.

Parameters

[out]	key	The key.
[in]	keySize	The key size.
[out]	record	The record.
[in]	recordSize	The record size.
[in]	lockMode	The lock mode.

Cursor: The cursor must be established. The cursor is traversed backward one record.

Current Offset: The current offset is destroyed.

Return values

>= 0	The number of bytes read. The number of bytes read is limited to Btrieve::MAXIMUM_RECORD_LENGTH. See BtrieveFile::RecordRetrieveChunk for retrieving records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length. If the record size requested is less than the length of the current record then BtrieveFile::GetLastStatusCode will return Btrieve::STATUS_CODE_DATALENGTH_ERROR.
-1	An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.

◆ RecordTruncate() [1/2]

Btrieve::StatusCode BtrieveFile::RecordTruncate ( int offset )

Truncate a record.

Parameters

[in] offset The offset. If offset is -1, then the current offset is used.

Cursor: The cursor is unaffected but must be established.

Current Offset: The current offset is established at the end of the record.

Return values

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

◆ RecordTruncate() [2/2]

Btrieve::StatusCode BtrieveFile::RecordTruncate ( )

Truncate a record at the current offset.

Cursor: The cursor is unaffected but must be established.

Current Offset: The current offset must be established and remains unchanged.

Return values

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

◆ RecordUnlock()

Btrieve::StatusCode BtrieveFile::RecordUnlock ( Btrieve::UnlockMode unlockMode )

Unlock a record or records.

Parameters

[in] unlockMode The unlock mode.

Snippet: // If RecordUnlock() fails.
if ((status = btrieveFile->RecordUnlock(Btrieve::UNLOCK_MODE_SINGLE)) != Btrieve::STATUS_CODE_NO_ERROR)
{
printf("Error: BtrieveFile::RecordUnlock():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is unaffected.

Current Offset: The current offset is unaffected.

Return values

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

See also: Btrieve::StatusCodeToString

Examples:: block.cpp.

◆ RecordUpdate()

Btrieve::StatusCode BtrieveFile::RecordUpdate	(	const char *	record,
		int	recordLength
	)

Update a record.

Parameters

[in]	record	The record.
[in]	recordLength	The record length. Record length is limited to Btrieve::MAXIMUM_RECORD_LENGTH bytes. See BtrieveFile::RecordUpdateChunk for updating records greater than Btrieve::MAXIMUM_RECORD_LENGTH in length.

Snippet: status = btrieveFile.RecordUpdate((char *)&record, sizeof(record));

Cursor: The cursor is unaffected but must be established.

Current Offset: The current offset is unaffected.

Return values

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

See also: Btrieve::StatusCodeToString

Examples:: block.cpp.

◆ RecordUpdateChunk() [1/2]

Btrieve::StatusCode BtrieveFile::RecordUpdateChunk	(	int	offset,
		const char *	chunk,
		int	chunkLength
	)

Update a record chunk.

Parameters

[in]	offset	The offset. If offset is -1, then the current offset is used.
[in]	chunk	The chunk.
[in]	chunkLength	The chunk length.

Snippet: // If RecordUpdateChunk() fails.
if ((status = btrieveFile->RecordUpdateChunk(0, (char *)&chunk, sizeof(chunk))) != Btrieve::STATUS_CODE_NO_ERROR)
{
printf("Error: BtrieveFile::RecordUpdateChunk():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is unaffected but must be established.

Current Offset: The current offset is established at the end of the updated chunk.

Return values

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

Examples:: btestchunk.cpp.

◆ RecordUpdateChunk() [2/2]

Btrieve::StatusCode BtrieveFile::RecordUpdateChunk	(	const char *	chunk,
		int	chunkLength
	)

Update a record chunk at the current offset.

Parameters

[in]	chunk	The chunk.
[in]	chunkLength	The chunk length.

Snippet: // If RecordUpdateChunk() fails.
if ((status = btrieveFile->RecordUpdateChunk((char *)&chunk, sizeof(chunk))) != Btrieve::STATUS_CODE_NO_ERROR)
{
printf("Error: BtrieveFile::RecordUpdateChunk():%d:%s.\n", status, Btrieve::StatusCodeToString(status));
goto leave;
}

Cursor: The cursor is unaffected but must be established.

Current Offset: The current offset must be established and is then traversed forward to the end of the updated chunk.

Return values

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

◆ SetOwner()

Btrieve::StatusCode BtrieveFile::SetOwner	(	Btrieve::OwnerMode	ownerMode,
		const char *	ownerName = `NULL`,
		const char *	ownerNameAgain = `NULL`,
		bool	useLongOwnerName = `true`
	)

Set the owner.

Parameters

[in]	ownerMode	The owner mode.
[in]	ownerName	The owner name.
[in]	ownerNameAgain	The owner name (again).
[in]	useLongOwnerName	Use a long owner name?

Description: Owner mode defaults to Btrieve::OWNER_MODE_NONE.

Cursor: The cursor is unaffected.

Current Offset: The current offset is unaffected.

Return values

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

See also: Btrieve::StatusCodeToString

◆ UnlockCursorPosition()

Btrieve::StatusCode BtrieveFile::UnlockCursorPosition ( long long cursorPosition )

Unlock the cursor position.

Note: The signature for this method changed in PSQL v13 R2.

Parameters

[in] cursorPosition The cursor position.

Cursor: The cursor is unaffected.

Current Offset: The current offset is unaffected.

Return values

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

See also: Btrieve::StatusCodeToString

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BtrieveFile()

◆ ~BtrieveFile()

Member Function Documentation

◆ BulkCreate()

◆ BulkDeleteNext()

◆ BulkDeletePrevious()

◆ BulkRetrieveNext()

◆ BulkRetrievePrevious()

◆ GetCursorPosition()

◆ GetInformation()

◆ GetLastStatusCode()

◆ GetNumerator() [1/2]

◆ GetNumerator() [2/2]

◆ GetPercentage() [1/2]

◆ GetPercentage() [2/2]

◆ GetRecordCreateTime()

◆ GetRecordUpdateTime()

◆ IndexCreate()

◆ IndexDrop()

◆ KeyRetrieve()

◆ KeyRetrieveFirst()

◆ KeyRetrieveLast()

◆ KeyRetrieveNext()

◆ KeyRetrievePrevious()

◆ RecordAppendChunk()

◆ RecordCreate()

◆ RecordDelete()

◆ RecordDeleteChunk() [1/2]

◆ RecordDeleteChunk() [2/2]

◆ RecordInsertChunk() [1/2]

◆ RecordInsertChunk() [2/2]

◆ RecordRetrieve()

◆ RecordRetrieveByCursorPosition() [1/2]

◆ RecordRetrieveByCursorPosition() [2/2]

◆ RecordRetrieveByFraction() [1/2]

◆ RecordRetrieveByFraction() [2/2]

◆ RecordRetrieveByPercentage() [1/2]

◆ RecordRetrieveByPercentage() [2/2]

◆ RecordRetrieveChunk() [1/2]

◆ RecordRetrieveChunk() [2/2]

◆ RecordRetrieveFirst() [1/2]

◆ RecordRetrieveFirst() [2/2]

◆ RecordRetrieveLast() [1/2]

◆ RecordRetrieveLast() [2/2]

◆ RecordRetrieveNext() [1/2]

◆ RecordRetrieveNext() [2/2]

◆ RecordRetrievePrevious() [1/2]

◆ RecordRetrievePrevious() [2/2]

◆ RecordTruncate() [1/2]

◆ RecordTruncate() [2/2]

◆ RecordUnlock()

◆ RecordUpdate()

◆ RecordUpdateChunk() [1/2]

◆ RecordUpdateChunk() [2/2]

◆ SetOwner()

◆ UnlockCursorPosition()