Public Member Functions | List of all members
BtrieveFile Class Reference

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

Constructor & Destructor Documentation

◆ BtrieveFile()

BtrieveFile::BtrieveFile ( )
Snippet
BtrieveFile btrieveFile;
See also
BtrieveClient::FileOpen

◆ ~BtrieveFile()

BtrieveFile::~BtrieveFile ( )

Member Function Documentation

◆ BulkCreate()

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

Bulk create.

Parameters
[in]btrieveBulkCreatePayloadThe bulk create payload.
[out]btrieveBulkCreateResultThe 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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]bulkRetrieveAttributesThe bulk retrieve attributes.
[out]bulkRetrieveResultThe bulk retrieve result.
[in]lockModeThe 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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]bulkRetrieveAttributesThe bulk retrieve attributes.
[out]bulkRetrieveResultThe bulk retrieve result.
[in]lockModeThe 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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
>= 0The cursor position.
-1An 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]btrieveFileInformationThe 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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
// 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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 13.20.
Parameters
[in]cursorPositionThe cursor position.
[in]denominatorThe 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
>= 0The numerator returned as 0 through denominator.
-1An 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]indexThe index.
[in]keyThe key.
[in]keyLengthThe key length.
[in]denominatorThe 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
>= 0The numerator returned as 0 through denominator.
-1An 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]cursorPositionThe 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
>= 0The percentage returned as 0 through 10,000, corresponding to 0% through 100.00%.
-1An 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]indexThe index.
[in]keyThe key.
[in]keyLengthThe 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
>= 0The percentage returned as 0 through 10,000, corresponding to 0% through 100.00%.
-1An 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]btrieveIndexAttributesThe 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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]indexThe 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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]comparisonThe comparison. Btrieve::COMPARISON_NOT_EQUAL isn't supported.
[in]indexThe index.
[in]keyThe key.
[in]keyLengthThe 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;
}
{
printf("%u is not prime.\n", *key);
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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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]indexThe index.
[out]keyThe key.
[in]keySizeThe key size.
Cursor
The cursor is established.
Current Offset
The current offset is destroyed.
Return values
= Btrieve::STATUS_CODE_NO_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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]indexThe index.
[out]keyThe key.
[in]keySizeThe key size.
Cursor
The cursor is established.
Current Offset
The current offset is destroyed.
Return values
= Btrieve::STATUS_CODE_NO_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn error has occurred.
See also
Btrieve::StatusCodeToString

◆ KeyRetrieveNext()

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

Retrieve the next key.

Parameters
[out]keyThe key.
[in]keySizeThe 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn error has occurred.
See also
Btrieve::StatusCodeToString

◆ KeyRetrievePrevious()

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

Retrieve the previous key.

Parameters
[out]keyThe key.
[in]keySizeThe 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn error has occurred.
See also
Btrieve::StatusCodeToString

◆ RecordAppendChunk()

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

Append a record chunk.

Parameters
[in]chunkThe chunk.
[in]chunkLengthThe 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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]recordThe 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]recordLengthThe 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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.

Note
This method doesn't return a Btrieve::StatusCode. See below for more information.
Parameters
[in]comparisonThe comparison. Btrieve::COMPARISON_NOT_EQUAL isn't supported.
[in]indexThe index.
[in]keyThe key.
[in]keyLengthThe key length.
[out]recordThe record.
[in]recordSizeThe record size.
[in]lockModeThe 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
>= 0The 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.
-1An 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
This method doesn't return a Btrieve::StatusCode. See below for more information.
The signature for this method changed in PSQL 13.20.
Parameters
[in]indexAn index or Btrieve::INDEX_NONE.
[in]cursorPositionThe cursor position.
[out]recordThe record.
[in]recordSizeThe record size.
[in]lockModeThe 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
>= 0The 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.
-1An 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.

Note
This method doesn't return a Btrieve::StatusCode. See below for more information.
Parameters
[in]indexAn index or Btrieve::INDEX_NONE.
[in]numeratorThe numerator given as 0 through denominator.
[in]denominatorThe denominator.
[out]recordThe record.
[in]recordSizeThe record size.
[in]lockModeThe 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
>= 0The 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.
-1An 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.

Note
This method doesn't return a Btrieve::StatusCode. See below for more information.
Parameters
[in]indexAn index or Btrieve::INDEX_NONE.
[in]percentageThe percentage given as 0 through 10,000, corresponding to 0% through 100.00%.
[out]recordThe record.
[in]recordSizeThe record size.
[in]lockModeThe 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
>= 0The 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.
-1An 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.

Note
This method doesn't return a Btrieve::StatusCode. See below for more information.
Parameters
[in]offsetThe offset.
[in]lengthThe length.
[out]chunkThe chunk.
[in]chunkSizeThe chunk size.
[in]lockModeThe 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
>= 0The number of bytes read. You may retrieve multiple chunks.
-1An 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]lengthThe length.
[out]chunkThe chunk.
[in]chunkSizeThe chunk size.
[in]lockModeThe 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
>= 0The number of bytes read. You may retrieve multiple chunks.
-1An 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.

Note
This method doesn't return a Btrieve::StatusCode. See below for more information.
Parameters
[in]indexAn index or Btrieve::INDEX_NONE.
[out]recordThe record.
[in]recordSizeThe record size.
[in]lockModeThe 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
>= 0The 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.
-1An 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.

Note
This method doesn't return a Btrieve::StatusCode. See below for more information.
Parameters
[in]indexAn index or Btrieve::INDEX_NONE.
[out]recordThe record.
[in]recordSizeThe record size.
[in]lockModeThe 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
>= 0The 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.
-1An error has occurred. Use BtrieveFile::GetLastStatusCode to determine the Btrieve::StatusCode associated with any error.
Examples:
bpercentage.cpp, and Test_BTRV2.cpp.

◆ RecordRetrieveNext()

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]recordThe record.
[in]recordSizeThe record size.
[in]lockModeThe 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
>= 0The 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.
-1An 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.

Note
This method doesn't return a Btrieve::StatusCode. See below for more information.
Parameters
[out]recordThe record.
[in]recordSizeThe record size.
[in]lockModeThe lock mode.
Cursor
The cursor must be established. The cursor is traversed backward one record.
Current Offset
The current offset is destroyed.
Return values
>= 0The 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.
-1An 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]offsetThe 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn error has occurred.

◆ RecordUnlock()

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

Unlock a record or records.

Parameters
[in]unlockModeThe unlock mode.
Snippet
// If RecordUnlock() fails.
{
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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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]recordThe record.
[in]recordLengthThe 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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]offsetThe offset.
[in]chunkThe chunk.
[in]chunkLengthThe 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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]chunkThe chunk.
[in]chunkLengthThe 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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]ownerModeThe owner mode.
[in]ownerNameThe owner name.
[in]ownerNameAgainThe owner name (again).
[in]useLongOwnerNameUse 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_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn 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]cursorPositionThe cursor position.
Cursor
The cursor is unaffected.
Current Offset
The current offset is unaffected.
Return values
= Btrieve::STATUS_CODE_NO_ERRORSuccess.
!= Btrieve::STATUS_CODE_NO_ERRORAn error has occurred.
See also
Btrieve::StatusCodeToString