class CTRecord

Description

The CTRecord class deals with the record concept. The CTRecord object is the "atomic" or basic element of the database system, in the sense that it has the smallest piece of integrated information. It represents the information in the data structure defined in the table. Multiple records may belong to one table, but a record belongs to only one table. The records are several times defined as the "rows" in the tables.

See also

CTBase, CTDatabase, CTTable

Preconditions

In order to deal with the records, the user must logon to a Session, be connected to a Database, and have a Table open.

CTRecord Methods

Constructor / Destructor

CTRecord() Creates a CTRecord object
~CTRecord() Destroys a CTRecord Object and resets all the dependent objects

Record Search

First(): Moves to the first record in the table
Last(): Moves to the last record in the table.
Next(): Moves to the next record in the table.
Prev(): Moves to the previous record in the table.
Find(): Looks for the record in the table.
FindRowid(): Verifies if a record at a given rowid exist.
FindTarget(): Looks for one specified record in the table.
GetRecordCount(): Retrieves the number of records in table
GetRowid(): Retrieves the record’s rowid value

Record Buffers

LockRecord(): Locks the current record.
UnlockRecord(): Unlocks the current record.
Clear(): Clears the record buffer
Read(): Reads the current record
Write(): Writes the record buffer to disk
Delete(): Deletes the current record from table
Reset(): Resets the record buffer to its initial condition
IsNew(): Indicates if a record buffer is cleared
IsEdited(): Indicates if a record buffer has been modified
SetNew(): Sets the new record flag
SetEdited(): Sets the change record flag
GetRecordBuffer(): Retrieves the record buffer object
GetRecordPos(): Retrieves the current record offset position
SetRecordPos(): Sets the current record offset position.
SetRecordOffset(): Updates the record offset.
SeekRecord(): Moves the record to position pointed by offset
GetRecordLength(): Retrieves the record length.
GetRecordSize(): Retrieves the allocated record size.
AtPercentile(): Find a record located at about a given percentile value.
EstimateSpan(): Estimate the approximate number of records between two key values.

Record Sets

RecordSetOn(): Activates record sets.
RecordSetOff(): Disactivates record sets.

Field Handling

IsNullField(): Indicates if the field pointed by field number or name is a null field.
GetFieldName(): Retrieves the field name based on the field number
GetFieldType(): Retrieves the field type based on the field number or name
GetFieldAsBool(): Retrieves the field contents as a boolean value
GetFieldAsSigned(): Retrieves the field contents as a signed value
GetFieldAsUnsigned(): Retrieves the field contents as an unsigned value
GetFieldAsDate(): Retrieves the field contents as a date object
GetFieldAsTime(): Retrieves the field contents as a time object
GetFieldAsDateTime(): Retrieves the field contents as a date and time object
GetFieldAsMoney(): Retrieves the field contents as a money object
GetFieldAsFloat(): Retrieves the field contents as a float value
GetFieldAsString(): Retrieves the field contents as a string object
GetFieldAsBlob(): Retrieves the field contents as a blob object
GetFieldAsBigint(): Retrieves the field contents as a big integer (64-bit)
GetFieldAsCurrency(): Retrieves the field contents as a CTCurrency object (64-bit)
GetFieldAsNumber(): Retrieves the field contents as a CTNumber object
SetFieldAsBool(): Sets the field contents as a boolean value
SetFieldAsSigned(): Sets the field contents as a signed value
SetFieldAsUnsigned(): Sets the field contents as an unsigned value
SetFieldAsDate(): Sets the field contents as a date object
SetFieldAsTime(): Sets the field contents as a time object
SetFieldAsDateTime(): Sets the field contents as a date and time object
SetFieldAsMoney(): Sets the field contents as a money object
SetFieldAsFloat(): Sets the field contents as a float value
SetFieldAsString(): Sets the field contents as a string object
SetFieldAsBlob(): Sets the field contents as a blob object
SetFieldAsBigint(): Sets the field contents as a big integer (64-bit)
SetFieldAsCurrency(): Sets the field contents as a CTCurrency object (64-bit)
SetFieldAsNumber(): Sets the field contents as a CTNumber object
GetFieldAsChar(): Retrieves the field contents as a char value
GetFieldAsBytes(): Retrieves the field contents as a byte (one-byte unsigned NINT) value
GetFieldAsShort(): Retrieves the field contents as a COUNT (two-bytes signed NINT) value
GetFieldAsWord(): Retrieves the field contents as a UCOUNT (unsigned two-byte integer) value
SetFieldAsChar(): Sets the field contents as a char value
SetFieldAsByte(): Sets the field contents as a byte (one-byte unsigned NINT) value
SetFieldAsShort(): Sets the field contents as a COUNT (two-bytes signed NINT) value
SetFieldAsWord(): Sets the field contents as a UCOUNT (unsigned two-byte integer) value
IsVariableField(): Indicates if a field is in the variable portion of a record
GetFieldLength(): Retrieves the actual field data length
GetFieldSize(): Retrieves the defined field size
GetFieldOffset(): Retrieves the field offset in the record
GetFieldAddress(): Retrieves the field address in the record buffer
GetFieldByName(): Retrieves the field number based on the field name
ClearField(): Clears the contents of a field.

Index Handling

GetDefaultIndex(): Retrieves the record default index number
GetDefaultIndexName(): Retrieves the default record index name.
SetDefaultIndex(): Sets the new record default index number.

Other Handling

SwitchContext(): Force a c-tree Plus ISAM context switch.

CTRecord::AtPercentile

Find a record located at about the given percentile value.

Declaration

void CTRecord::AtPercentile(NINT percent);

Description

CTRecord::AtPercentile() reads the record located at, approximately, the given percentile value.

Percent indicates the percentile value. The valid values for percent are from 0 to 100, indicating 0% to 100%. CTRecord::AtPercentile() return CTDBRET_OK on success.

The record is located using the record handle current index. You may select a new current index by calling the CTRecord::SetDefaultIndex() method. The table must have at least one index to be able to use this function.

The record returned is an approximation location indicated by the percentile value passed to CTRecord::AtPercentile().

CTRecord::AtPercentile(), which is based on c-tree low level function KeyAtPercentile(), and it is very efficient since it does not traverse all of the key values in order to determine the record located at the specified percentile. However, CTRecord::AtPercentile() is only an approximation since it assumes that key values are uniformly distributed among all of the b-tree leaf nodes.

CTRecord::AtPercentile() may be used to support scroll bar positioning, found in many GUI windowing environments, in the cases when the position must be maintained in key sequential order.

Return

CTRecord::AtPercentile() throws a CTException exception object if no record cannot be located.

See "FairCom DB API Errors and Return Values" for a complete listing of valid FairCom DB API error codes and return values.

Example


pRec->Clear
pRec->AtPercentile(40);

See also

CTIndex::SetDefault()

CTRecord::BatchLoaded

Retrieves the number of batch records loaded into batch buffer.

Declaration

LONG CTRecord::BatchLoaded();

Description

CTRecord::BatchLoaded() retrieves the number of batch records loaded into batch buffer for CTBATCH_GET, CTBATCH_RANGE or a CTBATCH_PHYS operation. This is the number of records that are ready to be retrieved by the CTRecord::NextBatch() function.

Return

CTRecord::BatchLoaded() returns the number of records ready for retrieval. In case of an error, CTRecord::BatchLoaded() throws an exception.

Example


try
{
  // set the partial target key
  hRecord.Clear();
  hRecord.SetFieldAsSigned("Invoice", Invoice);
  // set the batch operation
  hRecord.SetBatch(CTBATCH_GET, sizeof(Invoice), 0);
  // show how many records are ready
  printf("%d records are ready\n",  hRecord.BatchLoaded());
}
catch (CTException& err)
{
  printf("Batch failed with error %d\n", hRecord.GetError());
}

See Also

CTRecord::BatchLocked(), CTRecord::BatchMode(), CTRecord::BatchTotal(), CTRecord::EndBatch(), CTRecord::InsertBatch(), CTRecord::IsBatchActive(), CTRecord::NextBatch(), CTRecord::SetBatch()

CTRecord::BatchLocked

Retrieves the number of locked batch records.

Declaration

LONG CTRecord::BatchLocked();

Description

CTRecord::BatchLocked() retrieves the number of records locked during a CTBATCH_GET, CTBATH_RANGE or CTBATCH_PHYS operation. If CTBATCH_LOCK_READ or CTBATCH_LOCK_WRITE are specified in the batch mode, the CTRecord::BatchLocked() method returns the total number of records locked. If CTBATCH_LOCK_ONE is specified, or if either the CTBATCH_LOCK_READ or CTBATCH_LOCK_WRITE modes are not specified, CTRecord::BatchLocked() returns zero.

Return

CTRecord::BatchLocked() returns the number of locked records. In case of an error, CTRecord::BatchLocked() throws a CTException exception.

Example


try
{
  // set the partial target key
  hRecord.Clear();
  hRecord.SetFieldAsSigned("Invoice", Invoice);
  // set the batch operation
  hRecord.SetBatch(CTBATCH_GET, sizeof(Invoice), 0);
  // show how many records are ready
  printf("%d records are locked\n",  hRecord.BatchLocked());
}
catch (CTException& err)
{
  printf("Batch failed with error %d\n", hRecord.GetError());
}

See Also

TRecord::BatchLoaded(), CTRecord::BatchMode(), CTRecord::BatchTotal(), CTRecord::EndBatch(), CTRecord::InsertBatch(), CTRecord::IsBatchActive(), CTRecord::NextBatch(), CTRecord::SetBatch()

CTRecord::BatchMode

Retrieves the current batch mode.

Declaration

CTBATCH_MODE CTRecord::BatchMode();

Description

CTRecord::BatchMode() retrieves the current batch mode. The batch mode is set by calling the CTRecord::SetBatch() method. If a batch operation is not active, CTRecord::BatchMode() returns CTBATCH_NONE.

Return

Returns the current batch mode or CTBATCH_NONE if no batch operation is currently active.

Example


// check if a batch operation is in progress
if (hRecord.BatchMode() != CTBATCH_NONE)
    printf("Batch operation is underway\n");
else
    printf("No batch operations\n");

See Also

TRecord::BatchLoaded(), CTRecord::BatchLocked(), CTRecord::BatchTotal(), CTRecord::EndBatch(), CTRecord::InsertBatch(), CTRecord::IsBatchActive(), CTRecord::NextBatch(), CTRecord::SetBatch()

CTRecord::BatchTotal

Retrieves the total number of records affected by a batch retrieval operation.

Declaration

LONG CTRecord::BatchTotal();

Description

CTRecord::BatchTotal() retrieves the total number of records selected by a batch retrieval operation. If a batch operation is not active, CTRecord::BatchTotal() returns zero.

Return

Returns the total number of records selected by a batch retrieval operation. In case of an error, CTRecord::BatchTotal() throws a CTException.

Example


try
{
  // set the partial target key
  hRecord.Clear();
  hRecord.SetFieldAsSigned("Invoice", Invoice);
  // set the batch operation
  hRecord.SetBatch(CTBATCH_GET, sizeof(Invoice), 0);
  // show how many records are ready
  printf("%d records total\n",  hRecord.BatchLocked());
}
catch (CTException& err)
{
  printf("Batch failed with error %d\n", hRecord.GetError());
}

See Also

TRecord::BatchLoaded(), CTRecord::BatchLocked(), CTRecord::BatchMode(), CTRecord::EndBatch(), CTRecord::InsertBatch(), CTRecord::IsBatchActive(), CTRecord::NextBatch(), CTRecord::SetBatch()

CTRecord::BuildTargetKey

Syntax

void BuildTargetKey(CTFIND_MODE FindMode, pVOID targetkey, pVRLEN targetlen);

Parameters

FindMode [in] The find modes are: CTFIND_EQ, CTFIND_LT, CTFIND_LE, CTFIND_GT and CTFIND_GE.
targetkey [out] target key buffer
targetlen [in/out] target key length. Before calling ctdbBuildTargetKey() set targetlen with the size of targetkey buffer.

Description

Build a target key based on data in record buffer

Return

None.

See also

FindTarget()

CTRecord::Clear

Syntax

void Clear( )

Parameters

This method has no parameters.

Description

Clears the record buffer. Following this, FairCom DB API no longer has a current record.

Return

None.

Example


Rec1 = new CTRecord(pTable);
Rec1->Clear();
Rec1->SetFieldAsString("name", "Peter Thorn");
Rec1->SetFieldAsLong("age", 35);
Rec1->SetFieldAsString("phone", "555-55555");
Rec1->Write();

See also

Read(), Write(), Delete(), Reset(), Lock(), Locking

CTRecord::ClearField

Syntax

void ClearField(const NINT FieldNbr)
void ClearField(const CTString& FieldName)

Parameters

FieldNbr [in] The field number.
FieldName [in] The field name.

Description

Clears the contents of a field.

Return

None.

See also

Clear(), Reset()

CTRecord::CTRecord

Syntax

CTRecord(const CTTable& Handle)
CTRecord(const CTTable* Handle)
CTRecord(const CTRecord& Handle)
CTRecord(const CTRecord* Handle)

Parameters

Handle [in] The Table or Record Object. If the prototype CTRecord(const CTTable& Handle) or CTRecord(const CTTable* Handle) is used, Handle is the Table Object. If the prototype CTRecord(const CTRecord & Handle) or CTRecord(const CTRecord * Handle) is used, Handle is the Record Object. The CTRecord object being created is a child of the CTTable or CTRecord object.

Description

This is the constructor for the CTRecord class.

See also

~CTRecord()

CTRecord::Delete

Syntax

void Delete( )

Parameters

This method has no parameters.

Description

Deletes the current record from table. The record must be locked with one of the write locks before it is deleted.

Return

None.

Example


pRec->Clear();
pRec->SetDefaultIndex("name");
pRec->SetFieldAsString("name", "Peter Thorn");
if(pRec->Find(CTFIND_EQ))
{    pRec->LockRecord(CTLOCK_WRITE_BLOCK);
     pRec->Delete();
}

See also

Clear(), Reset(), Read(), Write(), LockRecord(), CTBase::Lock()

CTRecord::EndBatch

Terminates or cancels a batch operation.

Declaration

void CTRecord::EndBatch();

Description

A batch operation must be terminated by calling the CTRecord::EndBatch() function. Once a batch operation is started, by calling CTRecord::SetBatch(), no other batch operation is allowed to start until the current batch operation is terminated.

When performing batch retrieval operations, you may cancel the batch operation before retrieving all the records by calling CTRecord::EndBatch().

If the batch operation is a CTBATCH_RANGE them you must also call the CTRecord::RangeOff() function to terminate the index range used for the batch operation.

In case of errors, CTRecord::EndBatch() throws a CTException.

Return

void

Example


try
{
  // set the partial target key
  hRecord.Clear();
  hRecord.SetFieldAsSigned("Invoice", Invoice);
  // set the batch operation
  hRecord.SetBatch(CTBATCH_DEL, sizeof(Invoice), 0);
  // end the batch operation
  hRecord.EndBatch();
}
catch (CTException& err)
{
  printf("Batch failed with error %d\n", hRecord.GetError());
}

See Also

TRecord::BatchLoaded(), CTRecord::BatchLocked(), CTRecord::BatchMode(), CTRecord::BatchTotal(), CTRecord::InsertBatch(), CTRecord::IsBatchActive(), CTRecord::NextBatch(), CTRecord::SetBatch()

CTRecord::EstimateSpan

Estimate an approximate number of records between two key target values.

Declaration

LONG CTRecord::EstimateSpan(pVOID key1, pVOID key2);

Description

key1 and key2 are two key target values used to obtain the estimated number of records.

If CTRecord::EstimateSpan() returns 0, use CTRecord::GetError() function to retrieve the error code. If CTRecord::EstimateSpan() returns 0 and CTRecord::GetError() returns CTDBRET_OK then there are no records between the two key values supplied.

The estimation is based on the record handle current index. The current index may be changed by calling CTIndex::SetDefault(). The table must have at least one index to be able to use this function.

CTRecord::EstimateSpan(), which is based on the c-tree low level function CTRecord::EstimateSpan(), does not traverse the index to compute the values. Instead, it makes approximately ten calls to the c-tree low level function KeyAtPercentile() to determine the relative location of the target values.

The key target values used by CTRecord::EstimateSpan() can be created using CTRecord::BuildTargetKey().

Return

CTRecord::EstimateSpan() returns an estimate of records between key1 and key2. Call the CTRecord::GetError() method to check for error conditions.

Example

LONG Estimate(CTRecord& Handle, NINT index)
{
	LONG Retval = 0;
	TEXT key1[16], key2[16];
	VRLEN klen;

	try
	{		
		// set the default index
		Handle->SetDefaultIndex(index);

		// load the first record
		Handle->First();

		// build the target key for the first record
		klen = sizeof(key1);
		Handle->BuildTargetKey(CTFIND_EQ, key1, &klen);

		// load the last record
		Handle->Last();

		// build the target key for the last record 
		klen = sizeof(key2);
		Handle->BuildTargetKey(CTFIND_EQ, key2, &klen);

		// get the estimated span
		Retval = Handle->EstimateSpan(key1, key2);
		if (Retval > 0)
			Retval--;
	}
	catch (CTException &err)
	{
	    printf("Error: %s with error %d\n", err.GetErrorMsg(), err.GetErrorCode());
	}
	return Retval;
}

See also

CTIndex::SetDefault(), CTRecord::BuildTargetKey()

CTRecord::Find

Syntax

CTBOOL Find (CTFIND_MODE FindMode)

Parameters

FindMode [in] The find mode for the search. Valid values for the find mode are shown in the "Find Modes".
Notice that when the FindMode CTFIND_EQ is used, all segments that compose the index must be fulfilled, and also the index cannot allow duplicates.

Description

Looks for the record in the table.

Return

Find return YES if the record is found, NO otherwise.

Example


pRec->Clear();
pRec->SetDefaultIndex("name");
pRec->SetFieldAsString("name", "Peter Thorn");
if(pRec->Find(CTFIND_EQ))
{    pRec->LockRecord(CTLOCK_WRITE_BLOCK);
     pRec->Delete();
}

See also

First(), Next(), Prev(), Last(), FindTarget()

CTRecord::FindRowid

Syntax

CTBOOL FindRowid(CTROWID rowid, CTFIND_MODE FindMode)

Parameters

rowid [in] Rowid of record being sought
FindMode [in] The find mode for the search. Valid values for the find mode are shown in the "Find Modes".
Notice that when the FindMode CTFIND_EQ is used, all segments that compose the index must be fulfilled, and also the index cannot allow duplicates.

Description

Verifies if a record exist at a given rowid value. To retrieve the record rowid, use GetRowid(). One table has the rowid record enabled by default at creation time. To verify if one table has support to rowid, use CTTable::HasRowid().

Return

FindRowid() returns YES if the record is located, NO otherwise.

See also

GetRowid(), CTTable::HasRowid()

CTRecord::FindTarget

Syntax

CTBOOL FindTarget(pVOID target, CTFIND_MODE FindMode)

Parameters

target [in] The target key to look for in the table. target must be a properly transformed key value (use BuildTargetKey() if necessary).
FindMode [in] The find mode for the search. Valid values for the find mode are shown in the "Find Modes".
Notice that when the FindMode CTFIND_EQ is used, all segments that compose the index must be fulfilled, and also the index cannot allow duplicates.

Note Prior to FairCom DB V9.1 target must NOT be transformed.

Description

Looks for one specified record in the table.

Return

FindTarget() return YES if the record is found, NO otherwise.

See also

First(), Next(), Prev(), Last(), Find()

CTRecord::First

Syntax

CTBOOL First( )

Parameters

This method has no parameters.

Description

Moves to first record in table.

Return

First returns YES if the record is found, NO otherwise.

Example


pRec->First();
do {
     printf("\nName: %s", pRec ->
              GetFieldAsString("name").c_str()); }
while (pRec->Next());

See also

Next(), Prev(), Last(), Find()

CTRecord::FullTextSearchOff

Turn off Full-Text Search.

See CTRecord::FullTextSearchOff

CTRecord::FullTextSearchOn

Set the Full-Text Search criteria.

See CTRecord::FullTextSearchOn

CTRecord::GetDefaultIndex

Syntax

NINT GetDefaultIndex( )

Parameters

This method has no parameters.

Description

Retrieves the default record index number.

Return

GetDefaultIndex() returns the default index number.

CTDB_DATA_IDXNO: indicates a physical data table traversal without using any indexes.

Example


i = pRec->GetDefaultIndex();
if (i == 1)
{
     pRec->Clear();
     pRec->First();
}

See also

SetDefaultIndex(), GetDefaultIndexName()

CTRecord::GetDefaultIndexName

Syntax

CTString GetDefaultIndexName( )

Parameters

This method has no parameters.

Description

Retrieves the default record index name.

Return

GetDefaultIndexName() returns the default index name.

Example


if ("name" == pRec->GetDefaultIndexName())
{
     pRec->Clear();
     pRec->SetFieldAsString("name", "Peter Thorn");
     pRec->Find(CTFIND_EQ);
}

See also

GetDefaultIndex(), SetDefaultIndex()

CTRecord::GetErrorIndex

Declaration

NINT CTRecord::GetErrorIndex();

Description

Retrieves the index number that cause a record insert or record update operation to fail. This function should only be called after a Write() call fails. The error index number value is maintained until the next call to Write().

Return Values

A number from 0 to n to indicate which index caused the error. A value of 0 represents the first index, 1 represents the second index, and so on. If the index number can not be obtained, GetErrorIndex() returns -1.

See Also

CTRecord::Write()

CTRecord::GetFieldAddress

Syntax

pVOID GetFieldAddress(NINT FieldNbr)
pVOID GetFieldAddress(const CTString& FieldName)

Parameters

FieldNbr [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field address in the record buffer.

Return

GetFieldAddress() returns the field address.

See also

GetFieldSize(), GetFieldName(), GetFieldType(), GetFieldOffset()

CTRecord::GetFieldAsBigint

Syntax

CTBigint GetFieldAsBigint(NINT FieldNumber)
CTBigint GetFieldAsBigint(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field contents as a big integer (64-bit).

Return

GetFieldAsBigint() returns the contents as a big integer value.

See also

GetFieldAsBool(), GetFieldAsByte(), GetFieldAsBlob(), GetFieldAsChar(), GetFieldAsDate(), GetFieldAsTime(), GetFieldAsDateTime(), GetFieldAsMoney(), GetFieldAsShort(), GetFieldAsFloat(), GetFieldAsSigned(), GetFieldAsUnsigned(), GetFieldAsWord(), GetFieldAsString(), GetFieldAsCurrency(), GetFieldAsBigint(), GetFieldAsNumber()

CTRecord::GetFieldAsBlob

Syntax

void GetFieldAsBlob(NINT FieldNumber, CTBlob& value)
void GetFieldAsBlob(const CTString& FieldName, CTBlob& value)

Parameters

FieldNumber [in] The field number.
value [out] The Blob object, returned by the method.
FieldName [in] The field name.

Description

Retrieves the field contents as a CTBlob object

Return

None.

See also

GetFieldAsBool(), GetFieldAsByte(), GetFieldAsChar(), GetFieldAsDate(), GetFieldAsTime(), GetFieldAsDateTime(), GetFieldAsMoney(), GetFieldAsShort(), GetFieldAsFloat(), GetFieldAsSigned(), GetFieldAsUnsigned(), GetFieldAsWord(), GetFieldAsString(), GetFieldAsCurrency(), GetFieldAsBigint(), GetFieldAsNumber()

CTRecord::GetFieldAsBool

Syntax

CTBOOL GetFieldAsBool(NINT FieldNumber)
CTBOOL GetFieldAsBool(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field contents as a boolean value

Return

GetFieldAsBool() returns the contents as a boolean value.

See also

GetFieldAsByte(), GetFieldAsBlob(), GetFieldAsChar(), GetFieldAsDate(), GetFieldAsTime(), GetFieldAsDateTime(), GetFieldAsMoney(), GetFieldAsShort(), GetFieldAsFloat(), GetFieldAsSigned(), GetFieldAsUnsigned(), GetFieldAsWord(), GetFieldAsString(), GetFieldAsCurrency(), GetFieldAsBigint(), GetFieldAsNumber()

CTRecord::GetFieldAsBytes

Syntax

UTEXT GetFieldAsBytes(NINT FieldNumber)
UTEXT GetFieldAsBytes(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field contents as a UTEXT value (unsigned one-byte integer).

Return

GetFieldAsByte() returns the contents as a UTEXT value.

See also

GetFieldAsBool(), GetFieldAsBlob(), GetFieldAsChar(), GetFieldAsDate(), GetFieldAsTime(), GetFieldAsDateTime(), GetFieldAsMoney(), GetFieldAsShort(), GetFieldAsFloat(), GetFieldAsSigned(), GetFieldAsUnsigned(), GetFieldAsWord(), GetFieldAsString(), GetFieldAsCurrency(), GetFieldAsBigint(), GetFieldAsNumber()

CTRecord::GetFieldAsCurrency

Syntax

CTCurrency GetFieldAsCurrency(NINT FieldNumber)
CTCurrency GetFieldAsCurrency(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field contents as a CTCurrency object.

Return

GetFieldAsCurrency() returns the contents as a CTCurrency object.

See also

GetFieldAsBool(), GetFieldAsByte(), GetFieldAsBlob(), GetFieldAsChar(), GetFieldAsDate(), GetFieldAsTime(), GetFieldAsDateTime(), GetFieldAsShort(), GetFieldAsFloat(), GetFieldAsSigned(), GetFieldAsUnsigned(), GetFieldAsWord(), GetFieldAsString(), GetFieldAsMoney(), GetFieldAsBigint(), GetFieldAsNumber()

CTRecord::GetFieldAsDate

Syntax

CTDate GetFieldAsDate(NINT FieldNumber)
CTDate GetFieldAsDate(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field contents as a CTDate object

Return

GetFieldAsDate() returns the contents as CTDate object.

See also

GetFieldAsBool(), GetFieldAsByte(), GetFieldAsBlob(), GetFieldAsChar(), GetFieldAsTime(), GetFieldAsDateTime(), GetFieldAsMoney(), GetFieldAsShort(), GetFieldAsFloat(), GetFieldAsSigned(), GetFieldAsUnsigned(), GetFieldAsWord(), GetFieldAsString(), GetFieldAsCurrency(), GetFieldAsBigint(), GetFieldAsNumber()

CTRecord::GetFieldAsDateTime

Syntax

CTDateTime GetFieldAsDateTime(NINT FieldNumber)
CTDateTime GetFieldAsDateTime(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field contents as a CTDateTime object

Return

GetFieldAsDateTime() returns the contents as a CTDateTime object.

See also

GetFieldAsBool(), GetFieldAsByte(), GetFieldAsBlob(), GetFieldAsChar(), GetFieldAsDate(), GetFieldAsTime(), GetFieldAsMoney(), GetFieldAsShort(), GetFieldAsFloat(), GetFieldAsSigned(), GetFieldAsUnsigned(), GetFieldAsWord(), GetFieldAsString(), GetFieldAsCurrency(), GetFieldAsBigint(), GetFieldAsNumber()

CTRecord::GetFieldAsFloat

Syntax

CTFLOAT GetFieldAsFloat(NINT FieldNumber)
CTFLOAT GetFieldAsFloat(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field contents as a float value

Return

GetFieldAsFloat() returns the contents as a float value.

See also

GetFieldAsBool(), GetFieldAsByte(), GetFieldAsBlob(), GetFieldAsChar(), GetFieldAsDate(), GetFieldAsTime(), GetFieldAsDateTime(), GetFieldAsMoney(), GetFieldAsShort(), GetFieldAsSigned(), GetFieldAsUnsigned(), GetFieldAsWord(), GetFieldAsString(), GetFieldAsCurrency(), GetFieldAsBigint(), GetFieldAsNumber()

CTRecord::GetFieldAsMoney

Syntax

CTMoney GetFieldAsMoney(NINT FieldNumber)
CTMoney GetFieldAsMoney(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field contents as a CTMoney object.

Return

GetFieldAsMoney() returns the contents as a CTMoney object.

See also

CTRecord::GetFieldAsNumber

Syntax

CTNumber GetFieldAsNumber(NINT FieldNumber)
CTNumber GetFieldAsNumber(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field contents as a CTNumber object

Return

GetFieldAsFloat() returns the contents as a CTNumber object.

See also

CTRecord::GetFieldAsShort

Syntax

COUNT GetFieldAsShort(NINT FieldNumber)
COUNT GetFieldAsShort(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field contents as a 2-bytes signed integer (COUNT) value.

Return

GetFieldAsShort() returns the contents as a COUNT value.

See also

GetFieldAsBool(), GetFieldAsByte(), GetFieldAsBlob(), GetFieldAsChar(), GetFieldAsDate(), GetFieldAsTime(), GetFieldAsDateTime(), GetFieldAsMoney(), GetFieldAsFloat(), GetFieldAsSigned(), GetFieldAsUnsigned(), GetFieldAsWord(), GetFieldAsString(), GetFieldAsCurrency(), GetFieldAsBigint(), GetFieldAsNumber()

CTRecord::GetFieldAsSigned

Syntax

CTSIGNED GetFieldAsSigned(NINT FieldNumber)
CTSIGNED GetFieldAsSigned(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field contents as a signed value

Return

GetFieldAsSigned() returns the contents as a signed value.

See also

GetFieldAsBool(), GetFieldAsByte(), GetFieldAsBlob(), GetFieldAsChar(), GetFieldAsDate(), GetFieldAsTime(), GetFieldAsDateTime(), GetFieldAsMoney(), GetFieldAsShort(), GetFieldAsFloat(), GetFieldAsUnsigned(), GetFieldAsWord(), GetFieldAsString(), GetFieldAsCurrency(), GetFieldAsBigint(), GetFieldAsNumber()

CTRecord::GetFieldAsString

Syntax

TEXT GetFieldAsString(NINT FieldNumber)
TEXT GetFieldAsString(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field contents as a char value.

Return

GetFieldAsString() returns the contents as a TEXT value.

See also

GetFieldAsBool(), GetFieldAsByte(), GetFieldAsBlob(), GetFieldAsDate(), GetFieldAsTime(), GetFieldAsDateTime(), GetFieldAsMoney(), GetFieldAsShort(), GetFieldAsFloat(), GetFieldAsSigned(), GetFieldAsUnsigned(), GetFieldAsWord(), GetFieldAsString(), GetFieldAsCurrency(), GetFieldAsBigint(), GetFieldAsNumber()

CTRecord::GetFieldAsString

Syntax

CTString GetFieldAsString(NINT FieldNumber)
CTString GetFieldAsString(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field contents as a CTString object.

Return

GetFieldAsString() returns the contents as a CTString object.

See also

CTRecord::GetFieldAsTime

Syntax

CTTime GetFieldAsTime(NINT FieldNumber)
CTTime GetFieldAsTime(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field contents as a CTTime object

Return

GetFieldAsTime() returns the contents as a CTTime object.

See also

GetFieldAsBool(), GetFieldAsByte(), GetFieldAsBlob(), GetFieldAsChar(), GetFieldAsDate(), GetFieldAsDateTime(), GetFieldAsMoney(), GetFieldAsShort(), GetFieldAsFloat(), GetFieldAsSigned(), GetFieldAsUnsigned(), GetFieldAsWord(), GetFieldAsString(), GetFieldAsCurrency(), GetFieldAsBigint(), GetFieldAsNumber()

CTRecord::GetFieldAsUnsigned

Syntax

CTUNSIGNED GetFieldAsUnsigned (NINT FieldNumber)
CTUNSIGNED GetFieldAsUnsigned(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field contents as an unsigned value

Return

GetFieldAsUnsigned() returns the contents as an unsigned value.

See also

GetFieldAsBool(), GetFieldAsByte(), GetFieldAsBlob(), GetFieldAsChar(), GetFieldAsDate(), GetFieldAsTime(), GetFieldAsDateTime(), GetFieldAsMoney(), GetFieldAsShort(), GetFieldAsFloat(), GetFieldAsSigned(), GetFieldAsWord(), GetFieldAsString(), GetFieldAsCurrency(), GetFieldAsBigint(), GetFieldAsNumber()

CTRecord::GetFieldAsUTF16

Retrieves the field data as a Unicode UTF-16 string.

Declaration

void CTRecord::GetFieldAsUTF16(NINT FieldNumber, pWCHAR value, VRLEN size);

Description

CTRecord::GetFieldAsUTF16() retrieves the field data as a UNICODE UTF-16 string. If the underlying field type is not one of the UNICODE field types, the data is converted to UTF-16 strings. FieldNumber is the number of the field, value is a pointer to a wide (UTF-16) string buffer and size indicates the size in bytes of the string area.

Return

void

Example


void CheckData(CTRecord& hRecord, const CTString& str, NINT val)
{
	WCHAR WStr[32];
	TEXT s[64];
	CTSIGNED t;
 
	hRecord.GetFieldAsUTF16(0, WStr, sizeof(WStr));
	ctdb_u16TOu8(WStr, s, sizeof(s));
	if (strcmp(s, str) != 0)
	printf("UNICODE field contents not the same written");
 
	t = hRecord.GetFieldAsSigned(1);
	if ((NINT)t != val)
	printf("integer field contents not the same written");
 
}

See Also

SetFieldAsUTF16()

CTRecord::GetFieldAsWord

Syntax

UCOUNT GetFieldAsWord(NINT FieldNumber)
UCOUNT GetFieldAsWord(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field contents as an unsigned two-bytes integer value (UCOUNT).

Return

GetFieldAsWord() returns the contents as an UCOUNT value.

See also

GetFieldAsBool(), GetFieldAsByte(), GetFieldAsBlob(), GetFieldAsChar(), GetFieldAsDate(), GetFieldAsTime(), GetFieldAsDateTime(), GetFieldAsMoney(), GetFieldAsShort(), GetFieldAsFloat(), GetFieldAsSigned(), GetFieldAsUnsigned(), GetFieldAsString(), GetFieldAsCurrency(), GetFieldAsBigint(), GetFieldAsNumber()

CTRecord::GetFieldByName

Syntax

NINT GetFieldByName(const CTString& FieldName)

Parameters

FieldName [in] The field name.

Description

Retrieves the field number based on the field name.

Return

GetFieldByName() returns the field number.

See also

GetFieldName(), GetFieldLength(), GetFieldOffset(), GetFieldType(), GetFieldSize()

CTRecord::GetFieldLength

Syntax

VRLEN GetFieldLength(NINT FieldNbr)
VRLEN GetFieldLength(const CTString& FieldName)

Parameters

FieldNbr [in] The field number.
FieldName [in] The field name.

Description

Retrieves the actual field data length.

Return

GetFieldLength() returns the field length.

See also

GetFieldSize(), GetFieldName(), GetFieldType(), GetFieldOffset()

CTRecord::GetFieldName

Syntax

CTString GetFieldName(NINT FieldNumber)

Parameters

FieldNumber [in] The field number.

Description

Retrieves the field name based on the field number.

Return

GetFieldName() returns the field name.

Example


field_name=pRec->GetFieldName(1);

See also

GetFieldType(), GetFieldOffset()

CTRecord::GetFieldOffset

Syntax

VRLEN GetFieldOffset(NINT FieldNbr)
VRLEN GetFieldOffset(const CTString& FieldName)

Parameters

FieldNbr [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field record offset.

Return

GetFieldOffset() returns the field offset.

See also

GetFieldLength(), GetFieldName(), GetFieldType(), GetFieldAddress()

CTRecord::GetFieldSize

Syntax

VRLEN GetFieldSize (NINT FieldNbr)
VRLEN GetFieldSize(const CTString& FieldName)

Parameters

FieldNbr [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field defined size.

Return

GetFieldSize() returns the defined field size.

See also

GetFieldLength(), GetFieldName(), GetFieldType(), GetFieldOffset()

CTRecord::GetFieldType

Syntax

CTDBTYPE GetFieldType(NINT FieldNumber)
CTDBTYPE GetFieldType(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Retrieves the field type based on the field number or name.

Return

GetFieldType() returns the field type.

See also

GetFieldName(), GetFieldOffset()

CTRecord::GetFilter

Retrieves the current filter expression text.

Declaration

void CTRecord::GetFilter(CTString& cndexpr);

Description

CTRecord::GetFilter() retrieves the current filter expression text. If no record filter is active for this record object, an empty string is returned.

Return

void

Example


// if the record filter is active, retrieve the filter expression
if  (hRecord.IsFiltered())
{
    CTString expr;
    hRecord.GetFilter(expr);
    printf("Filter expression %s\n", expr.c_str());
}

See Also

CTRecord::SetFilter(), CTRecord::IsFiltered()

CTRecord::GetFullTextSearchErrorDetails

Get detail about Full-Text Search error.

See CTRecord::GetFullTextSearchErrorDetails

CTRecord::GetRecordBuffer

Syntax

pVOID GetRecordBuffer( )

Parameters

This method has no parameters.

Description

Retrieves the record buffer object

Return

GetRecordBuffer() returns the record buffer object.

CTRecord::GetRecordCount

Syntax

CTUINT64 GetRecordCount( )

Parameters

This method has no parameters.

Description

Retrieves the number of records in table. It may be used in conjunction with First and Next to retrieve all records in the table.

Return

GetRecordCount() returns the number of records in the table.

See also

First(), Next()

CTRecord::GetRecordKeyPos

Syntax

CTOFFSET CTRecord::GetRecordKeyPos() const

Parameters

None

Description

Retrieves the given record position in the default index.

Return

Position. The returned position is the Ordinal key position, not a file offset.

Throws a CTException exception object if an error occurs.

CTRecord::GetRecordLength

Syntax

VRLEN GetRecordLength( ) const

Parameters

This method has no parameters.

Description

Retrieves the record length.

Return

GetRecordLength() returns the record length.

See also

GetRecordSize()

CTRecord::GetRecordPos

Syntax

CTOFFSET GetRecordPos( ) const

Parameters

This method has no parameters.

Description

Retrieves the current record offset position

Return

None.

See also

SetRecordOffset()

CTRecord::GetRecordSize

Syntax

VRLEN GetRecordSize( ) const

Parameters

This method has no parameters.

Description

Retrieves the allocated record size.

Return

GetRecordSize() returns the allocated record size.

See also

GetRecordLength()

CTRecord::GetRowid

Syntax

CTROWID GetRowid( )

Parameters

This method has no parameters.

Description

Retrieves the record’s rowid value

Return

GetRowid() returns the rowid for the record.

See also

FindRowid(), CTTable::HasRowid()

CTRecord::InsertBatch

Inserts a new record into a batch buffer.

Declaration

void CTRecord::InsertBatch();

Description

Inserts a new record into a batch buffer maintained internally by FairCom DB API. When the batch buffer fills up, the group of records stored in the batch buffer are inserted into the table. If CTRecord::EndBatch() is called and the batch buffer still contains records, a new insert record operation is performed for the remaining records before the batch operation is terminated.

For transaction controlled files, the batch insertion operation is treated as one all or nothing operation. If no explicit transaction is started, each insertion of records with will start and end its own transaction. Even if an explicit transaction is started, each insertion operation is treated independently through safe points.

Note currently, all record insertion operations will not perform any conversion of record images, key values and record position for heterogeneous client/server implementations.

The following steps must be taken to perform a batch insert record operation:

Call CTRecord::SetBatch() function, with CTBATCH_INS mode, to insert a group of records.
For each record to be inserted perform the following operations:
Call CTRecord::Clear() to clear a record buffer
For each field in the record call one of the CTRecord::SetFieldAs...() functions to set the field data.
Call CTRecord::InsertBatch() to insert the record into the batch buffer.
Call CTRecord::EndBatch() to indicate that no more records will be inserted.

In case of errors, CTRecord::InsertBatch() throws a CTException.

Return

void

Example


try
{
  // set the batch operation
  hRecord.SetBatch(CTBATCH_INS, 0, 0);
  // prepare the first record
  hRecord.Clear();
  hRecord.SetFieldAsSigned("Invoice", Invoice);// invoice
  hRecord.SetFieldAsSigned("ItemNbr", 1);      // invoice item
  hRecord.SetFieldAsSigned("Quantity", 100);   // item quantity
  hRecord.SetFieldAsSigned("ItemCode", 1001);  // item code
  hRecord.InsertBatch();                       // insert
  // prepare the second record
  hRecord.Clear();
  hRecord.SetFieldAsSigned("Invoice", Invoice);// invoice
  hRecord.SetFieldAsSigned("ItemNbr", 2);      // invoice item
  hRecord.SetFieldAsSigned("Quantity", 200);   // item quantity
  hRecord.SetFieldAsSigned("ItemCode", 1002);  // item code
  hRecord.InsertBatch();                       // insert
  // terminate the batch operation
  hRecord.EndBatch();
}
catch (CTException& err)
{
  printf("Batch failed with error %d\n", hRecord.GetError());
}

See Also

CTRecord::BatchLoaded(), CTRecord::BatchLocked(), CTRecord::BatchMode(), CTRecord::BatchTotal(), CTRecord::EndBatch(), CTRecord::IsBatchActive(), CTRecord::NextBatch(), CTRecord::SetBatch()

CTRecord::IsBatchActive

Indicates if a batch operation is under way or not.

Declaration

CTBOOL CTRecord::IsBatchActive();

Description

CTRecord::IsBatchActive() indicates if a batch operation is active or not. This is equivalent to CTRecord::BatchMode() returning CTBATCH_NONE.

Return

Value	Symbolic Constant	Explanation
0	NO	No batch operation is under way.
1	YES	A batch operation is under way.

Example


// check if a batch operation is active
if (CTRecord::IsBatchActive())
    printf("Batch operation underway\n");
else
    printf("No batch operation\n");

See Also

CTRecord::BatchLoaded(), CTRecord::BatchLocked(), CTRecord::BatchMode(), CTRecord::BatchTotal(), CTRecord::EndBatch(), CTRecord::InsertBatch(), CTRecord::NextBatch(), CTRecord::SetBatch()

CTRecord::IsEdited

Syntax

CTBOOL IsEdited( ) const

Parameters

This method has no parameters.

Description

Indicates if a record buffer has been modified.

Return

IsEdited() returns YES if the record has been modified, NO otherwise

See also

Write(), SetEdited()

CTRecord::IsFiltered

Indicates if a filter condition is active for this record object.

Declaration

CTBOOL CTRecord::IsFiltered();

Description

IsFiltered indicates whether a filter condition is active for this record object.

Return

Value	Symbolic Constant	Explanation
0	NO	No filter condition is active.
1	YES	A filter condition is active.

Example

// if the record filter is active, retrieve the filter expression
if  (hRecord.IsFiltered())
{
    CTString expr;
    hRecord.GetFilter(expr);
    printf("Filter expression %s\n", expr.c_str());
}

See Also

CTRecord::SetFilter(), CTRecord::GetFilter()

CTRecord::IsFullTextSearchOn

Indicate if Full-Text Search is active on the record.

See CTRecord::IsFullTextSearchOn

CTRecord::IsNew

Syntax

CTBOOL IsNew( ) const

Parameters

This method has no parameters.

Description

Indicates if a record buffer is cleared.

Return

IsNew() returns YES if the record buffer is cleared, NO otherwise.

See also

Clear(), SetNew()

CTRecord::IsNullField

Syntax

CTBOOL IsNullField(NINT FieldNumber)
CTBOOL IsNullField(const CTString& FieldName)

Parameters

FieldNumber [in] The field number.
FieldName [in] The field name.

Description

Indicates if the field specified by field number or name is a null field.

Return

IsNullField() returns YES if the field is null, NO otherwise.

CTRecord::IsRangeOn

Indicate if an index range operation is active for this record handle.

Declaration

bool CTRecord::IsRangeOn()

Description

CTRecord::IsRangeOn() returns YES if a index range operation is active for this record handle, or NO is no index range is active.

Return

Value	Symbolic Constant	Explanation
0	NO	No index range is active.
1	YES	An index range is active.

Example


if (pRec->IsRangeOn())
    printf("Range is on\n");

See Also

CTRecord::RangeOn(), CTRecord::RangeOff()

CTRecord::IsRecordSetOn

Declaration

CTBOOL CTRecord::IsRecordSetOn();

Description

Indicates if a record set is active or not. A record set is active after a successful call to RecordSetOn(). A record set can be switched off by calling RecordSetOff().

Return Values

Returns YES if a record set if active and NO if a record set is not active.

See Also

CTRecord::RecordSetOn(), CTRecord::RecordSetOff()

CTRecord::IsVariableField

Syntax

CTBOOL IsVariableField(NINT FieldNbr)
CTBOOL IsVariableField(const CTString& FieldName)

Parameters

FieldNbr [in] The field number.
FieldName [in] The field name.

Description

Indicates if a field is in the variable portion of a record

Return

IsVariableField() returns YES if a field is in the variable portion of a record, and NO otherwise

CTRecord::Last

Syntax

CTBOOL Last ( )

Parameters

This method has no parameters.

Description

Moves to the last record in the table.

Return

Last() returns YES if the record is found, NO otherwise.

See also

First(), Next(), Prev(), Find()

CTRecord::LockRecord

Syntax

void LockRecord(CTLOCK_MODE mode)

Parameters

mode [in] the lock mode. Valid values for the lock mode are shown in Record Lock Modes.

Description

Locks the current record. In order to use this method, a record must be considered current. A record is set as the current record by update methods (Write()) or search methods (Find(), FindTarget(), First(), Next(), Prev(), Last(), SeekRecord()).

After a Record has been cleared (Clear()), no current record buffer is kept, and LockRecord() cannot be used. In this case, use the CTBase Lock method.

UnlockRecord() may be used to free the record lock. LockRecord(CTLOCK_FREE) has the same effect. Unlock() and Lock(CTLOCK_FREE) free all session wide locks but DO NOT free any records locked with LockRecord().

A record that is locked with one of the READ locks available allows any other user with a READ lock to read that record. No one can update one record using a READ lock. When one user gets a WRITE lock in a record, it means he/she may update that particular record, and until the record is freed, no one else is able to read that particular record.

Notice that LockRecord() should be called BEFORE modifying the record contents; otherwise, the changes will be lost.

When working with LockRecord(), the user must be certain to release the lock before moving to the next record or will need to use CTTable::UnlockTable() to release all record locks from a table at once. Do not mix the use of CTBase::Lock() and LockRecord() since an error DLOK_ERR, indicating record already locked, may occur.

Return

None.

See also

UnlockRecord(), CTBase::Lock(), Locking

CTRecord::Next

Syntax

CTBOOL Next( )

Parameters

This method has no parameters.

Description

Moves to the next record in the table. Before calling Next for the first time in a table, one of the Record search methods must be used: Find() or First().

Return

Next() returns YES if the record is found, NO otherwise.

Example


pRec->First();
do {
     printf("\nName: %s", pRec ->
              GetFieldAsString("name").c_str()); }
while (pRec->Next());

See also

First(), Prev(), Last(), Find()

CTRecord::NextBatch

Retrieves the next record from the batch buffer.

Declaration

void CTRecord::NextBatch()

Description

If the mode of the batch operation is CTBATCH_GET, CTBATCH_RANGE, or CTBATCH_PHYS then it may be necessary to retrieve all records that match the batch criteria. The records are retrieved by calling CTRecord::NextBatch() method.

CTRecord::NextBatch() method retrieves a record data from the batch buffer maintained by FairCom DB API’s record object. After a successful call to CTRecord::NextBatch() method, the field data can be retrieved by calling the appropriate CTRecord::GetFieldAs...() methods.

In case of error, CTRecord::NextBatch() throws an exception.

Return

The user will receive an exception if the batch has ended.

Example

CTRecord hRecord;
	while (true)
	{
		try
		{
			hRecord.NextBatch();
		}
		catch (CTException err)
		{
			if (err.GetErrorCode() == INOT_ERR)
				break;
			else
				throw err;
		}
		CTString invoice = hRecord.GetFieldAsString("Invoice");
		CTString item = hRecord.GetFieldAsString("Item");
		printf("%-11s %s\n", invoice.c_str(), item.c_str());
	}

See Also

CTRecord::BatchLoaded(), CTRecord::BatchLocked(), CTRecord::BatchMode(), CTRecord::BatchTotal(), CTRecord::EndBatch(), CTRecord::InsertBatch(), CTRecord::IsBatchActive(), CTRecord::SetBatch()

CTRecord::NextInBatch

Retrieves the next batch of records from batch retrieval operation.

Declaration

bool CTRecord::NextInBatch();

Description

If the mode of the batch operation is one of CTBATCH_GET, CTBATCH_RANGE or CTBATCH_PHYS then it may be necessary to retrieve all records that match the batch criteria. The records are retrieved by calling NextInBatch() method. NextInBatch() method retrieve the record data from the batch buffer maintained by FairCom DB API's record handle. After a successful call to NextInBatch() function the field data can be retrieved by calling the appropriate GetFieldAs...() methods.

Return

YES if succesful, NO if no more record match the criteria.

Throws a CTException on error.

NextInBatch() does not throw an exception when the end of the batch is reached.

See Also

BatchLocked(), BatchMode(), EndBatch(), InsertBatch(), IsBatchActive(), NextBatch(), SetBatch(), BatchLoaded

CTRecord::NumberOfKeyEntries

Syntax

LONG CTRecord::NumberOfKeyEntries(const CTString& indexName);

Parameters

indexName The name of the index to read the number of entries from.

Description

NumberOfKeyEntries() retrieves the number key entries in an index file identified by indexName.

Return

NumberOfKeyEntries() returns the number of key entries in the index. If an error is detected, NumberOfKeyEntries() throws a CTException exception.

See also

CTRecord::EstimateSpan()

CTRecord::Prev

Syntax

CTBOOL Prev( )

Parameters

This method has no parameters.

Description

Moves to the previous record in the table. Before calling Prev() for the first time in a table, one of the Record search methods must be used: Find() or Last().

Return

Prev() returns YES if the record is found, NO otherwise.

See also

First(), Next(), Prev(), Find()

CTRecord::RangeOff

Terminates a record index range operation established by CTRecord::RangeOff().

Declaration

void CTRecord::RangeOff()

Description

CTRecord::RangeOff() terminates a range operation.

Return

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	CTRecord::RangeOff() returns CTDBRET_OK on success or FairCom DB API SDK error code on failure.

See "FairCom DB API Errors and Return Values" for a complete listing of valid FairCom DB API error codes and return values.

Example

pRec->RangeOff();

See also

CTRecord::RangeOn(), CTRecord::IsRangeOn()

CTRecord::RangeOn

Establish a new index range on a record handle.

Declaration

void CTRecord::RangeOn(NINT SegCount, pVOID lRange, pVOID uRange, pNINT operators)

Description

CTRecord::RangeOn() establishes a new range based on the key segment values passed on lRange and uRange buffers, and the operators for each segment. Once the range is set, use CTRecord::First(), CTRecord::Next(), CTRecord::Prev() and CTRecord::Last() to navigate the records in the specified range. The range is set for all index entries that are situated between the lower bounds and upper bounds values. The segment values are stored in lRange and uRange buffers in the same order and type of the index segment definition. If a previous range exists for this index, the previous range is released and the new range is established. Ranges take precedence over sets. If a record handle has a set established, record from a range will fetched instead of records from a range. Once the range is terminated, the records from a set is established.

SegCount indicates the number of index segments values that should be used for setting the range, and the number of operators, since there must be one operator for each key segment in lRange and/or uRange.
lRange is a buffer with the lower range segment values. Use the function CTRecord::BuildTargetKey() to build the lRange buffer.
uRange is a buffer with the upper range segment values. Use the function CTRecord::BuildTargetKey() to build the uRange buffer.
operators operators is an array of operators. There must be one operator for each key segment in lRange and/or uRange. The operators CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT are open ended and use only the lRange buffer for range values and the equivalent key segment in uRange is ignored and maybe set to null (ascii \0 values). The operators CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE and CTIX_NOTBET use both lRange and uRange buffers to establish the lower and upper bound values.

Return

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	CTRecord::RangeOn() returns CTDBRET_OK on success or FairCom DB API SDK error code on failure.

See "FairCom DB API Errors and Return Values" for a complete listing of valid FairCom DB API error codes and return values.

See also

CTRecord::RangeOff(), CTRecord:IsRangeOn()

CTRecord::Read

Syntax

void Read( )

Parameters

This method has no parameters.

Description

Reads the current record.

Return

None.

See also

Clear(), Write(), Delete(), Reset()

CTRecord::RecordSetOff

Syntax

void RecordSetOff( )

Parameters

This method has no parameters.

Description

Deactivates record sets.

Return

None.

Example


pRec->RecordSetOn(5);
pRec->SetDefaultIndex("last name");
pRec->SetFieldAsString("last name", "silva");
pRec->First();
pRec->RecordSetOff();

See also

RecordSetOn()

CTRecord::RecordSetOn

Syntax

void RecordSetOn(NINT siglen)

Parameters

siglen [in] The number of key bytes.

Description

Activates record sets. After activating a record set, set the fields and index desired in the search, and then perform the search using the regular search functions. Notice that it is necessary to set the first siglen bytes from the index segments.

Return

None.

Example


// display all records in set - no error checking
void DisplayAll(CTRecord& pRec)
{
   NINT count = 0;

   pRec.Clear();
   pRec.SetDefaultIndex("index_name");
   pRec.SetFieldAsString(0, "silva");
   pRec.RecordSetOn(5);
   if (pRec.First())
   {
      do
      {
         count++;
         PrintRecord(pRec);
      }
      while (pRec.Next());
   }
   printf("%d records in set\n", count);
}

See also

RecordSetOff()

CTRecord::Reset

Syntax

void Reset( )

Parameters

This method has no parameters.

Description

Resets the record buffer to its initial condition.

Return

None.

See also

Clear(), Read(), Write(), Delete()

CTRecord::SeekRecord

Syntax

void SeekRecord(CTOFFSET offset)

Parameters

offset [in] The record offset position.

Description

Moves the record to the position pointed to by offset.

Return

None.

See also

GetRecordPos(), SetRecordPos(), SetRecordOffset()

CTRecord::SetBatch

Perform operations on a group of records.

Declaration

void CTRecord::SetBatch(CTBATCH_MODE mode, VRLEN targetLen, VRLEN bufferLen);

Description

CTRecord::SetBatch() attempts to initiate a specified operation on a group of records with keys matching a partial key value, an index range expression, or the entire table by physical order.

The mode parameter specify which batch operation is to take place. You must choose at least one of the mandatory modes. You may or one or more of the optional mode to specify further parameters for the batch operation. Please refer to the description of the modes below.

targetLen - the number of significant bytes of the partial target key when the batch mode is CTBATCH_GET or CTBATCH_DEL.
bufferLen - the size of the buffer used internally by FairCom DB API code to handle batch operations. A zero value for this parameter is an indication that the default value size should be used. The default buffer size is calculated as the size of the fixed portion of the record multiplied by 128.

In case of errors, CTRecord::NextBatch() throws a CTException.

Mandatory modes

MODE	Description
CTBATCH_GET	Retrieve a group of related records by partial key
CTBATCH_RANGE	Retrieve a group of related records based on an index range expression
CTBATCH_PHYS	Retrieve records from a table in physical order. The starting record for the batch retrieval may be specified.
CTBATCH_DEL	Delete a group of related records by partial key
CTBATCH_INS	Insert a group of records

Optional modes

Mode	Description
CTBATCH_GKEY	Process records with a greater than or equal key match with the target key. When this mode is specified, the number of matched records is not readily available. ctdbBatchLocked() and CTRecord::BatchLocked() returns a value one greater than ctdbBatchLoaded() to indicate there may be more records to process.This mode is applicable only with CTBATCH_GET and CTBATCH_DEL modes and can not be used with CTBATCH_LKEY.
CTBATCH_LKEY	Process records that have a less than or equal key match with the target key.This mode is applicable only with CTBATCH_GET and CTBATCH_DEL modes and can not be used with CTBATCH_GKEY.
CTBATCH_VERIFY	Verify that the keys in the index match the values in the key fields of the record.
CTBATCH_LOCK_KEEP	Keep all records locked after ...EndBatch() is called. Without this mode, all records locks are released when ...EndBatch() is called. This option is only in effect when used with CTBATCH_LOCK_READ or CTBATCH_LOCK_WRITE.
CTBATCH_LOCK_READ	Place a read lock on each record that matches the partial key.
CTBATCH_LOCK_WRITE	Place a write lock on each record that matches the partial key.
CTBATCH_LOCK_BLOCK	Convert a CTBATCH_LOCK_READ or CTBATCH_LOCK_WRITE to blocking read and blocking write locks, respectively.
CTBATCH_LOCK_ONE	Implement an alternative locking strategy: only locks the record during the record read; original locking strategy keeps locks on during entire batch processing.
CTBATCH_COMPLETE	...SetBatch() returns a success code only if all matching records are successfully locked. You must specify either CTBATCH_LOCK_READ or CTBATCH_LOCK_WRITE.

Retrieving records by partial key

All records with key matching a partial target key are loaded into a buffer region maintained internally by FairCom DB API. If the selected records do not fit in the buffer, those that fit are loaded, and subsequent calls will retrieve the remaining records.

The following steps must be taken to perform a retrieval batch operation based on a partial key:

Clear a record buffer by calling the CTRecord::Clear() method.
Use the CTRecord::SetFieldAs...() methods to set the fields that form the partial target key that will be used to select a group of records.
Call the CTRecord::SetBatch() method, with CTBATCH_GET mode, to start a new record retrieval batch operation.
If the CTRecord::SetBatch() method returns with no errors, call the CTRecord::NextBatch() method repeatedly until all related records are retrieved. CTRecord::NextBatch() returns BTMT_ERR (428) to indicate no more records are available.

When you are done with the batch records, call the CTRecord::EndBatch() method to terminate the batch operation. Please note that another batch operation can only start after the current batch operation is terminated.

Retrieving records by index range

All records that match an index range expression are loaded into a buffer region maintained internally by FairCom DB API. If the selected records do not fit in the buffer, those that fit are loaded, and subsequent calls will retrieve the remaining records.

The following steps must be taken to perform an index range batch retrieval of records:

Establish an index range by calling CTRecord::RangeOn() method;
Call the CTRecord::SetBatch() method with the CTBATCH_RANGE mode to start a new record retrieval batch operation.
If the CTRecord::SetBatch() method returns with no errors, call the CTRecord::NextBatch() method repeatedly until all related records are retrieved. CTRecord::NextBatch() returns BTMT_ERR (428) to indicate no more records are available.
When you are done with the batch records, call the CTRecord::EndBatch() method to terminate the batch operation.
Call the CTRecord::RangeOff() method to terminate index range operation.

Retrieving records by physical order

All records of a table are loaded by physical order into a buffer region maintained internally by FairCom DB API. If the selected records do not fit in the buffer, those that fit are loaded, and subsequent calls will retrieve the remaining records.

The following steps must be taken to perform a physical order batch retrieval of records:

Call the CTRecord::SetBatch() method with the CTBATCH_PHYS mode to start a new record retrieval batch operation.
If the CTRecord::SetBatch() method returns with no errors, call the CTRecordNextBatch() method repeatedly until all related records are retrieved. CTRecord::NextBatch() returns BTMT_ERR (428) to indicate no more records are available.
When you are done with the batch records, call the CTRecord::EndBatch() method to terminate the batch operation.

Note Setting a batch with CTBATCH_PHYS will cause slightly different behavior from setting it with CTBATCH_GET.

If the number of records exceeds the size of the buffer set when calling SetBatch, the total returned by BatchTotal will be only the number of records that fit into the batch buffer for CTBATCH_PHYS batches. If the batch was set with the CTBATCH_GET mode, the total number of records satisfying the batch will be returned, regardless if they all fit in the batch buffer. If a precise count of the number of records in a file is necessary, use GetRecordCount when you are in CTBATCH_PHYS mode.

This difference also affects record locking. If the batch was set with CTBATCH_PHYS, the records are locked when they are read into the buffer, so only the records that have been read into the batch buffer are locked. If the batch was set with CTBATCH_GET, all records are locked on the initial call.

Deleting a group of records

If the intended batch operation is to delete a group of selected records, you need to initially set the partial target key to select the group of related records and then start the batch operation to delete the selected records.

Even if no records are retrieved with the delete operation, CTRecord::EndBatch() must be called to terminate the current batch operation.

The following steps must be taken to perform a batch delete record operation:

Clear a record buffer by calling the CTRecord::Clear() method.
Use the CTRecord::SetFieldAs...() methods to set the fields that form the partial target key that will be used to select a group of records.
Call the CTRecord::SetBatch() methods with CTBATCH_DEL mode to delete a group of related records.
Call the CTRecord::EndBatch() method to terminate the delete record batch operation.

Inserting a group of records

A group of new records are loaded into a buffer region maintained internally by FairCom DB API and this group of records are inserted into a table.

When the batch buffer fills up, the group of records stored in the batch buffer are inserted into the table. If CTRecord::EndBatch() is called and the batch buffer still contains records, a new insert record operation is performed for the remaining records before the batch operation is terminated.

Note currently, all records insertion operations will not perform any conversion of records images, key values and records position for heterogeneous client/server implementations.

The following steps must be taken to perform a batch insert record operation:

Call the CTRecord::SetBatch() method with CTBATCH_INS mode to insert a group of records.
For each record to be inserted perform the following operations:
call CTRecord::Clear() to initialize a record buffer
for each field in the record call one of the CTRecord::SetFieldAs...() method to set the field data;
call CTRecord::InsertBatch() to insert the record into the batch buffer
Call CTRecord::EndBatch() to indicate that no more records will be inserted.

Return

void

Example


void GetInvoiceItems(CTRecord& hRecord, NINT Invoice)
{
  NINT count = 0;
 
  try
  {
    // set the partial target key */
    hRecord.Clear();
    hRecord.SetFieldAsSigned("Invoice", Invoice);
    // set the batch operation
    hRecord.SetBatch(CTBATCH_GET, sizeof(Invoice), 0);
    {
      // retrieve records
      while (hRecord.NextBatch())
          count++;
      // terminate batch operations
      hRecord.EndBatch();
    }
    printf("%d records found\n", count);
  }
  catch (CTException& err)
  {
    printf("Batch failed [error %d]\n", hRecord.GetError());
  }
}

See Also

CTRecord::BatchLoaded(), CTRecord::BatchLocked(), CTRecord::BatchMode(), CTRecord::BatchTotal(), CTRecord::EndBatch(), CTRecord::InsertBatch(), CTRecord::IsBatchActive(), CTRecord::NextBatch()

CTRecord::SetDefaultFullTextIndex

Set the new record default Full Text index number.

See CTRecord::SetDefaultFullTextIndex

CTRecord::SetDefaultIndex

Syntax

void SetDefaultIndex(NINT indexno)
void SetDefaultIndex(const CTString& name)

Parameters

indexno [in] The new default record index number.
name [in] The new default record index name.

Description

Sets the new record default index. Unless this function is called, the first index is the default.

To force a physical data table traversal without using any indexes, specify the following constant:

CTDB_DATA_IDXNO

Return

None.

Example


myRecord->SetDefaultIndex("name");
// change the default index to "name"
myRecord->First();  
// find the first record ordered by "name"

See also

GetDefaultIndex()

CTRecord::SetEdited

Syntax

void SetEdited(CTBOOL flag)

Parameters

flag [in] The new Change Record flag.

Description

Sets the changed record flag.

Return

None.

See also

IsEdited()

CTRecord::SetFieldAsBigint

Syntax

void SetFieldAsBigint(NINT FieldNumber, const CTBigint& value)
void SetFieldAsBigint(const CTString& FieldName, CTBigint& value)

Parameters

FieldNumber [in] The field number.
value [in] The big integer object
FieldName [in] The field name.

Description

Sets the field contents as a big integer object (64-bit).

Return

None.

CTRecord::SetFieldAsBlob

Syntax

void SetFieldAsBlob (NINT FieldNumber, CTBlob& value)
void SetFieldAsBlob(const CTString& FieldName, CTBlob& value)

Parameters

FieldNumber [in] The field number.
value [in] The blob object
FieldName [in] The field name.

Description

Sets the field contents as a blob object.

Return

None.

CTRecord::SetFieldAsBool

Syntax

void SetFieldAsBool(NINT FieldNumber, CTBOOL value)
void SetFieldAsBool(const CTString& FieldName, CTBOOL value)

Parameters

FieldNumber [in] The field number.
value [in] The boolean value
FieldName [in] The field name.

Description

Sets the field contents as a boolean value

Return

None.

CTRecord::SetFieldAsByte

Syntax

void SetFieldAsByte (NINT FieldNumber, UTEXT value)
void SetFieldAsByte(const CTString& FieldName, UTEXT value)

Parameters

FieldNumber [in] The field number.
value [in] The byte value
FieldName [in] The field name.

Description

Sets the field contents as a byte value (unsigned one-byte integer)

Return

None.

CTRecord::SetFieldAsChar

Syntax

void SetFieldAsChar (NINT FieldNumber, TEXT value)
void SetFieldAsChar(const CTString& FieldName, TEXT value)

Parameters

FieldNumber [in] The field number.
value [in] The byte value
FieldName [in] The field name.

Description

Sets the field contents as a TEXT value (signed one-byte integer).

Return

None.

CTRecord::SetFieldAsCurrency

Syntax

void SetFieldAsCurrency(NINT FieldNumber, const CTCurrency& value)
void SetFieldAsCurrency(const CTString& FieldName, const CTCurrency& value)

Parameters

FieldNumber [in] The field number.
value [in] The byte value
FieldName [in] The field name.

Description

Sets the field contents as a CTCurrency (64-bit) object.

Return

None.

CTRecord::SetFieldAsDate

Syntax

void SetFieldAsDate (NINT FieldNumber, const CTDate& value)
void SetFieldAsDate(const CTString& FieldName, const CTDate& value)

Parameters

FieldNumber [in] The field number.
value [in] The byte value
FieldName [in] The field name.

Description

Sets the field contents as a date object.

Return

None.

CTRecord::SetFieldAsDateTime

Syntax

void SetFieldAsDateTime (NINT FieldNumber, const CTDateTime& value)
void SetFieldAsDateTime(const CTString& FieldName, const CTDateTime& value)

Parameters

FieldNumber [in] The field number.
value [in] The byte value
FieldName [in] The field name.

Description

Sets the field contents as a date and time object.

Return

None.

CTRecord::SetFieldAsFloat

Syntax

void SetFieldAsFloat (NINT FieldNumber, CTFLOAT value)
void SetFieldAsFloat(const CTString& FieldName, CTFLOAT value)

Parameters

FieldNumber [in] The field number.
value [in] The byte value
FieldName [in] The field name.

Description

Sets the field contents as a double value

Return

None.

CTRecord::SetFieldAsMoney

Syntax

void SetFieldAsMoney (NINT FieldNumber, const CTMoney& value)
void SetFieldAsMoney(const CTString& FieldName, const CTMoney& value)

Parameters

FieldNumber [in] The field number.
value [in] The byte value
FieldName [in] The field name.

Description

Sets the field contents as a money object.

Return

None.

CTRecord::SetFieldAsNumber

Syntax

void SetFieldAsNumber(NINT FieldNumber, const CTNumber& value)
void SetFieldAsNumber (const CTString& FieldName, const CTNumber& value)

Parameters

FieldNumber [in] The field number.
value [in] The byte value
FieldName [in] The field name.

Description

Sets the field contents as a CTNumber object.

Return

None.

CTRecord::SetFieldAsShort

Syntax

void SetFieldAsShort (NINT FieldNumber, COUNT value)
void SetFieldAsShort(const CTString& FieldName, COUNT value)

Parameters

FieldNumber [in] The field number.
value [in] The byte value
FieldName [in] The field name.

Description

Sets the field contents as a 2-bytes signed integer (COUNT).

Return

None.

CTRecord::SetFieldAsSigned

Syntax

void SetFieldAsSigned (NINT FieldNumber, CTSigned value)
void SetFieldAsSigned(const CTString& FieldName, CTSIGNED value)

Parameters

FieldNumber [in] The field number.
value [in] The byte value
FieldName [in] The field name.

Description

Sets the field contents as an integer signed value

Return

None.

CTRecord::SetFieldAsString

Syntax

void SetFieldAsString (NINT FieldNumber, const CTString& value)
void SetFieldAsString(const CTString& FieldName, const CTString& value)

Parameters

FieldNumber [in] The field number.
value [in] The byte value
FieldName [in] The field name.

Description

Sets the field contents as a string object.

Return

None.

CTRecord::SetFieldAsTime

Syntax

void SetFieldAsTime (NINT FieldNumber, const CTTime& value)
void SetFieldAsTime(const CTString& FieldName, const CTTime& value)

Parameters

FieldNumber [in] The field number.
value [in] The time object
FieldName [in] The field name.

Description

Sets the field contents as a time object.

Return

None.

CTRecord::SetFieldAsUnsigned

Syntax

void SetFieldAsUnsigned (NINT FieldNumber, CTUNSIGNED value)
void SetFieldAsUnsigned(const CTString& FieldName, CTUNSIGNED value)

Parameters

FieldNumber [in] The field number.
value [in] The unsigned integer value
FieldName [in] The field name.

Description

Sets the field contents as an integer unsigned value

Return

None.

CTRecord::SetFieldAsUTF16

Sets the field with a Unicode UTF-16 string.

Declaration

void CTRecord::SetFieldAsUTF16(NINT FieldNumber, pWCHAR value);

Description

FieldNumber is a number representing the field number.
value is the wide (UTF-16) string buffer.

SetFieldAsUTF16() sets the field with a UNICODE UTF-16 string. If the underlying field type is not one of the UNICODE field types, the UTF-16 string is converted to the appropriate type before the data is stores in the field.

Return

void

Example


void AddData(CTRecord& hRecord, const CTString& str, NINT val)
{
	WCHAR WStr[32];
 
	hRecord.Clear();
	ctdb_u8TOu16(str, WStr, sizeof(WStr));
	hRecord.SetFieldAsUTF16(0, WStr);
	hRecord.SetFieldAsSigned(1, (CTSIGNED)val);
	hRecord.Write();
}

CTRecord::SetFieldAsWord

Syntax

void SetFieldAsWord (NINT FieldNumber, UCOUNT value)
void SetFieldAsWord(const CTString& FieldName, UCOUNT value)

Parameters

FieldNumber [in] The field number.
value [in] The UCOUNT value
FieldName [in] The field name.

Description

Sets the field contents as an unsigned two-byte integer (UCOUNT) value.

Return

None.

CTRecord::SetFilter

Sets or clears a record filter condition.

Declaration

void CTRecord::SetFilter(const CTString& cndexpr);

Description

cndexpr [in] the filtering expression. The valid expressions are shown in the table below.

int atoi( char* String )	ASCII to integer.
int atol( char* String )	ASCII to long.
double atof( char* String )	ASCII to float.
int cabs( into Value )	Calculate the absolute value of a complex number.
int labs( into Value )	Calculate the absolute value of a long integer.
double fabs( double Value )	Calculate the absolute value of a float.
double ceil( double Value )	Calculate the ceiling of a value.
double floor( double Value )	Calculate the floor of a value.
double fmod( double r, double t )	Calculate the floating-point remainder.
int strlen( char* String )	Get the length of a string.
int strcmp( char* s, char* t )	Compare strings.
int stricmp( char* s, char* t )	Compare strings without regard to case.
int strncmp( char* s, char* t, int length )	Compare characters of two strings.
int strnicmp( char* s, char *t, int length )	Compare characters of two strings without regard to case.

Description

CTRecord::SetFilter() is used to set the filtering for a table. When set, all records retrieved from the table will be filtered against the expression, and just those records that match this criteria will be returned. Notice that this feature will be temporary, and just the user who sets the filter will have its records filtered. The filter is turned off when the table is closed, or when CTRecord::SetFilter() is called with NULL in the parameter cndexpr. If a new expression is set to a table with a current filter, the old filter is replaced with the new one. Only one filter may be active per table per user at a given time.

When used in the client/server model, this feature has the potential to increase the performance because only the records matching the criteria will be returned, reducing the network traffic. If used in conjunction with sets (CTRecord::RecordSetOn()), it it may behave as a simple query.

Return

void

Example


// scan all records from California
void ScannAllRecord(CTTable &hTable)
{
	CTRecord hRecord(hTable);

	hRecord.SetFilter("stricmp(state, \"CA\") == 0");
	if (hRecord.First())
	{
		do
		{
			DisplayRecord(hRecord);
		}
		while (hRecord.Next());
	}
}

See Also

CTRecord::GetFilter(), CTRecord::IsFiltered()

CTRecord::SetNew

Syntax

void SetNew(CTBOOL flag)

Parameters

flag [in] The new Record flag.

Description

Sets the new record flag.

Return

None.

See also

IsNew()

CTRecord::SetRecordOffset

Syntax

void SetRecordOffset(CTOFFSET offset)

Parameters

offset [in] The record offset position.

Description

Updates the record offset. The current record pointer is not moved and no record data is updated.

Return

None.

See also

GetRecordPos(), SetRecordPos(), SeekRecord()

CTRecord::SetRecordPos

Syntax

void SetRecordPos(CTOFFSET offset)

Parameters

offset [in] The record offset.

Description

Sets the current record offset position. The record buffers are not updated. In order to update the record buffer, Read must be called.

Return

None.

See also

GetRecordPos(), Read(), SetRecordOffset(), SeekRecord()

CTRecord::SwitchContext

Force a c-tree Plus ISAM context switch.

Declaration

void CTRecord::SwitchContext()

Description

Force a switch to the c-tree Plus ISAM context indicated by the record object. Each record object has its own c-tree ISAM context id.

When most FairCom DB API record handling functions are called, they automatically perform a c-tree ISAM context switch. SwitchContext() may be useful before calling specific c-tree ISAM or low level calls to make sure the correct ISAM context is active before making those calls.

Return

Value	Symbolic Constant	Explanation
none		SwitchContext return no value.

See "c-tree Plus Error Codes" in c-tree Plus Programmer’s Reference Guide for a complete listing of valid c-tree Plus error values.

EXAMPLE


// force a context switch
hRecord.SwitchContext();
// call ResetRecord
if (ResetRecord((COUNT)hTable.GetDatno(), SWTCURI))
    printf("ResetRecord failed\n");

See also

CTBase::SwitchInstance(), CTTable::GetDatno(), CTTable::GetIdxno(), CTIndex::GetIdxno()

CTRecord::UnlockRecord

Syntax

void UnlockRecord( )

Parameters

None.

Description

Unlocks the current record. To free all record locks from one specific table obtained with LockRecord(), use CTTable::UnlockTable().

Return

None.

See also

LockRecord(), CTTable::UnlockTable(), Locking

CTRecord::Write

Syntax

void Write( )

Parameters

This method has no parameters.

Description

Writes the record buffer to disk. In multi-user environments, the record should be locked before an update.

Return

None.

See also

Clear(), Read(), Delete(), Reset(), LockRecord(), CTBase::Lock(), Locking

CTRecord::~CTRecord

Syntax

~CTRecord

Parameters

This destructor has no parameters.

Description

This is the destructor for the CTRecord class. It frees the allocated memory to the Record.

See also

CTRecord()

CTRecord Class

class CTRecord

CTRecord Methods

CTRecord::AtPercentile

CTRecord::BatchLoaded

CTRecord::BatchLocked

CTRecord::BatchMode

CTRecord::BatchTotal

CTRecord::BuildTargetKey

CTRecord::Clear

CTRecord::ClearField

CTRecord::CTRecord

CTRecord::Delete

CTRecord::EndBatch

CTRecord::EstimateSpan

CTRecord::Find

CTRecord::FindRowid

CTRecord::FindTarget

CTRecord::First

CTRecord::FullTextSearchOff

CTRecord::FullTextSearchOn

CTRecord::GetDefaultIndex

CTRecord::GetDefaultIndexName

CTRecord::GetErrorIndex

CTRecord::GetFieldAddress

CTRecord::GetFieldAsBigint

CTRecord::GetFieldAsBlob

CTRecord::GetFieldAsBool

CTRecord::GetFieldAsBytes

CTRecord::GetFieldAsCurrency

CTRecord::GetFieldAsDate

CTRecord::GetFieldAsDateTime

CTRecord::GetFieldAsFloat

CTRecord::GetFieldAsMoney

CTRecord::GetFieldAsNumber

CTRecord::GetFieldAsShort

CTRecord::GetFieldAsSigned

CTRecord::GetFieldAsString

CTRecord::GetFieldAsString

CTRecord::GetFieldAsTime

CTRecord::GetFieldAsUnsigned

CTRecord::GetFieldAsUTF16

CTRecord::GetFieldAsWord

CTRecord::GetFieldByName

CTRecord::GetFieldLength

CTRecord::GetFieldName

CTRecord::GetFieldOffset

CTRecord::GetFieldSize

CTRecord::GetFieldType

CTRecord::GetFilter

CTRecord::GetFullTextSearchErrorDetails

CTRecord::GetRecordBuffer

CTRecord::GetRecordCount

CTRecord::GetRecordKeyPos

CTRecord::GetRecordLength

CTRecord::GetRecordPos

CTRecord::GetRecordSize

CTRecord::GetRowid

CTRecord::InsertBatch

CTRecord::IsBatchActive

CTRecord::IsEdited

CTRecord::IsFiltered

CTRecord::IsFullTextSearchOn

CTRecord::IsNew

CTRecord::IsNullField

CTRecord::IsRangeOn

CTRecord::IsRecordSetOn

CTRecord::IsVariableField

CTRecord::Last

CTRecord::LockRecord

CTRecord::Next

CTRecord::NextBatch

CTRecord::NextInBatch

CTRecord::NumberOfKeyEntries

CTRecord::Prev

CTRecord::RangeOff

CTRecord::RangeOn

CTRecord::Read

CTRecord::RecordSetOff

CTRecord::RecordSetOn