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

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, const 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...

int	RecordRetrieve (Btrieve::Comparison comparison, Btrieve::Index index, const 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	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	RecordRetrieveByPercentage (Btrieve::Index index, int percentage, 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	RecordRetrieveLast (Btrieve::Index index, 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	RecordRetrievePrevious (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, and btestvlr.cpp.

Constructor & Destructor Documentation

◆ BtrieveFile()

BtrieveFile::BtrieveFile ( )

Snippet: BtrieveFile btrieveFile;

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.

◆ 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_NO_ERROR	Success.
!= Btrieve::STATUS_CODE_NO_ERROR	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`
	)

Get 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_NO_ERROR	Success.
!= Btrieve::STATUS_CODE_NO_ERROR	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 13.20.

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.

Snippet: // 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;
}

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, and btestvlr.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 13.20.

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

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.

◆ IndexCreate()

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

Create an index.

Parameters

[in] btrieveIndexAttributes The index attributes.

Snippet: // 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;
}

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, and btestvlr.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,
		const char *	key,
		int	keyLength
	)

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

Parameters

[in]	comparison	The comparison. Btrieve::COMPARISON_NOT_EQUAL isn't supported.
[in]	index	The index.
[in]	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.

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

Parameters

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

Snippet: // 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;
}

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, bkeyonly.cpp, block.cpp, bpercentage.cpp, btest.cpp, btestappend.cpp, btestchunk.cpp, and btestvlr.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.

◆ RecordRetrieve()

int BtrieveFile::RecordRetrieve	(	Btrieve::Comparison	comparison,
		Btrieve::Index	index,
		const 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.

Parameters

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

Snippet: // 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;
}

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

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: The signature for this method changed in PSQL 13.20.

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.

◆ RecordRetrieveByFraction()

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.

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.

◆ RecordRetrieveByPercentage()

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

Retrieve a record by percentage.

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.

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

Parameters

[in]	offset	The offset.
[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.

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

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

Retrieve the first record.

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.

◆ RecordRetrieveLast()

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

Retrieve the last record.

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.

◆ RecordRetrieveNext()

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

Retrieve the next record.

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.

◆ RecordRetrievePrevious()

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

Retrieve the previous record.

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.

◆ RecordTruncate() [1/2]

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

Truncate a record.

Parameters

[in] offset The offset.

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. 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.
[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 13.20.

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

◆ BulkRetrieveNext()

◆ BulkRetrievePrevious()

◆ GetCursorPosition()

◆ GetInformation()

◆ GetLastStatusCode()

◆ GetNumerator() [1/2]

◆ GetNumerator() [2/2]

◆ GetPercentage() [1/2]

◆ GetPercentage() [2/2]

◆ IndexCreate()

◆ IndexDrop()

◆ KeyRetrieve()

◆ KeyRetrieveFirst()

◆ KeyRetrieveLast()

◆ KeyRetrieveNext()

◆ KeyRetrievePrevious()

◆ RecordAppendChunk()

◆ RecordCreate()

◆ RecordDelete()

◆ RecordRetrieve()

◆ RecordRetrieveByCursorPosition()

◆ RecordRetrieveByFraction()

◆ RecordRetrieveByPercentage()

◆ RecordRetrieveChunk() [1/2]

◆ RecordRetrieveChunk() [2/2]

◆ RecordRetrieveFirst()

◆ RecordRetrieveLast()

◆ RecordRetrieveNext()

◆ RecordRetrievePrevious()

◆ RecordTruncate() [1/2]

◆ RecordTruncate() [2/2]

◆ RecordUnlock()

◆ RecordUpdate()

◆ RecordUpdateChunk() [1/2]

◆ RecordUpdateChunk() [2/2]

◆ SetOwner()

◆ UnlockCursorPosition()