class CTBase

Description

The CTBase Class is the basic class, upon which most of the other classes are built

See Also

CTSession, CTDatabase, CTTable

Preconditions

In general, this class is not directly used. However, since most of the other classes are based on this, there are some important methods described in here that are applicable to most of the derived classes.

CTBase Public Members

CTHANDLE m_handle

CTBase Methods

Constructor / Destructor

• CTBase(): Creates a CTBase object
• ~CTBase(): Destroys a CTBase Object and resets all the dependent objects

Error Handling

• GetError(): Returns the error code associated with the handle
• SetError(): Sets the error code
• ClearError(): Resets the error code

Transaction Processing

• IsTransActive(): Indicates if a transaction has been started with a call to Begin(), but not terminated with a call to Commit or Abort.
• Begin(): Begins a transaction.
• Commit(): Commits a transaction started with a call to Begin().
• Abort(): Aborts a transaction started with a call to Begin().
• SetSavePoint(): Sets a new transaction save point.
• RestoreSavePoint(): Restores a previously set save point.
• Lock(): Enables or disable record locks, using one of the c-tree lock modes
• Unlock(): Disables record locks

Handle

• GetHandle(): Returns the handle
• GetHandleId(): Returns the handle ID
• SetHandle(): Sets the handle

Type Definition

• GetDefFloatFormat(): Retrieves the default floating point string format to be used in sprintf() and sscanf()
• GetDefDateType(): Retrieves the default date type
• GetDefTimeType(): Retrieves the default time type
• SetDefFloatFormat(): Sets the default floating point string format to be used in sprintf() and sscanf()
• SetDefDateType(): Sets the default date type
• SetDefTimeType(): Sets the default time type

Other

• GetAutoCommit(): Retrieves the FairCom DB API auto commit mode.
• GetUserTag(): Retrieves the user tag.
• SetUserTag(): Sets the user tag.
• SwitchInstance(): Force a c-tree Plus instance switch.
• GetKeepLock(): Gets the Keep Lock mode in use.
• SetKeepLock(): Sets the Keep Lock mode in use.

See also Locking.

CTBase::CTBase

Syntax

CTBase ( )

Parameters

This constructor has no parameters.

Description

This is the constructor for the CTBase class.

See also

~CTBase()

CTBase::~CTBase

Syntax

~CTBase

Parameters

This destructor has no parameters.

Description

This is the destructor for the CTBase class.

See also

CTBase()

CTBase::Abort

Syntax

void Abort ( )

Parameters

This method has no parameters.

Description

Aborts a transaction started with a call to Begin(). Note that Abort does not free any locks. Locks acquired during the transaction need to be released with a call to Unlock or CTRecord::UnlockRecord().

Return

None.

Example

pSession->Begin;
try {
              pDatabase->AddTable("custmast", "");
              printf("\nTable added to database.");
              pSession->Commit;
       }
catch (CTException& err)
       {
              Abort(  );
              printf("\n\n%d  %s",err.GetErrorCode, err.GetErrorMsg);
       }
 

See also

Begin(), Commit(), IsTransActive(), SetKeepLock(), Locking

CTBase::GetAutoCommit

Declaration

CTBOOL CTBase::GetAutoCommit();

Description

CTBase::GetAutoCommit() retrieves the FairCom DB API auto commit mode. The auto commit of transactions are invoked automatically when records are added or updated by CTRecord::Write() method.

Return Values

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

See Also

CTBase::SetAutoCommit() CTBase::SetOperation() CTBase::GetOperation()

CTBase::Begin

Syntax

void Begin ( )

Parameters

This method has no parameters.

Description

Marks the beginning of a transaction. If all the operations intended for the particular transaction are finished correctly, use Commit() to commit the transaction. Otherwise, use Abort() to abort the transaction.

The Begin() method does not lock or set the flags to lock any records. In order to request the lock of the records to be updated inside the transaction, the Lock() or CTRecord::LockRecord() should be used.

Return

None.

Example

pSession->Begin;
try {
              pDatabase->AddTable("custmast", "");
              printf("\nTable added to database.");
              pSession->Commit;
       }
catch (CTException& err)
       {
              Abort(  );
              printf("\n\n%d  %s",err.GetErrorCode, err.GetErrorMsg);
       }
 

See also

Abort(), Commit(), IsTransActive(), Lock()

CTBase::ClearError

Syntax

void ClearError ( )

Parameters

This method has no parameters.

Description

Clear the current error and set the error to CTDBRET_OK.

Return

None.

See also

GetError(), SetError()

CTBase::Commit

Syntax

void Commit ( )

Parameters

This method has no parameters.

Description

Commits a transaction started with a call to Begin(). Notice that Commit does not free any locks. Locks acquired during the transaction need to be released with a call to Unlock() or CTRecord::UnlockRecord().

Return

None.

Example

pSession->Begin;
try {
              pDatabase->AddTable("custmast", "");
              printf("\nTable added to database.");
              pSession->Commit;
       }
catch (CTException& err)
       {
              Abort(  );
              printf("\n\n%d  %s",err.GetErrorCode, err.GetErrorMsg);
       }
 

See also

Begin(), Abort(), IsTransActive(), SetKeepLock()

CTBase::GetDefDateType

Syntax

CTDATE_TYPE GetDefDateType ( ) const

Parameters

This method has no parameters.

Description

Retrieves the default date type. The valid values for the date type are shown in "Data Types".

Return

GetDefDateType() returns the default date type. For more information on the valid values for the date type, see the description above.

See also

SetDefDateType()

CTBase::GetDefFloatFormat

Syntax

CTString GetDefFloat ( )Format

Parameters

This method has no parameters.

Description

Retrieves the floating point string format to be used as a default in sprintf() and sscanf(). The default value initially is set to "%f", and may be changed to reflect the desired printing format.

Return

GetDefFloatFormat() returns the default floating point format.

See also

SetDefFloatFormat()

CTBase::GetDefTimeType

Syntax

CTTIME_TYPE GetDefTimeType ( ) const

Parameters

This method has no parameters.

Description

Retrieves the default time type. The valid values for the time type are shown is "Data Types".

Return

GetDefTimeType() returns the default time type. For more information on the valid values for the time type, see the description above.

See also

SetDefTimeType()

CTBase::GetError

Syntax

CTDBRET GetError ( )

Parameters

This method has no parameters.

Description

Returns the error code associated with the handle.

Return

GetError() returns the error code associated with the handle or CTDBRET_NULHANDLE (4002) if the handle is unallocated.

See also

SetError(), ClearError()

CTBase::GetHandle

Syntax

CTHANDLE GetHandle ( ) const

Parameters

This method has no parameters.

Description

Returns the handle.

Return

GetHandle() returns the FairCom DB API C API handle

See also

GetHandleId(), SetHandle()

CTBase::GetHandleId

Syntax

NINT GetHandleId ( ) const

Parameters

This method has no parameters.

Description

Returns the handle ID.

Return

GetHandleId() returns the handle ID or 0 on error.

See also

GetHandle(), SetHandle()

CTBase::GetKeepLock

Syntax

CTKEEP_MODE CTBase::GetKeepLock();

Parameters

This method has no parameters.

Description

When a transaction is terminated by calling either the CTBase::Commit() or CTBase::Abort() function, all locks are automatically freed, including the locks acquired outside the transaction. An application might want to control which locks are kept when the transaction ends. To support this ability, FairCom DB API introduced a function to control how locks are handled when a transaction terminates.

CTBase::GetKeepLock() returns the current keep lock status.

Return

See also

CTBase::Abort(), CTBase::Begin(), CTBase::Commit(), CTBase:::SetKeepLock()

CTBase::GetLockMode

Syntax

CTLOCK_MODE GetLockMode ( )

Parameters

This method has no parameters.

Description

Retrieves the current record lock mode for session wide locks. Valid values for the session wide lock mode are shown in "Session Wide Lock Modes". If CTLOCK_FREE is returned, it does indicate that no locks are currently active.

Return

GetLockMode() returns the session wide lock mode, as described in "Session Wide Lock Modes".

See also

Lock(), Unlock(), IsLockActive(), Locking

CTBase::GetOperation

Syntax

CTOPS_MODE CTBase::GetOperation();

Description

GetOperation() retrieves the operation modes for special performance-related functionality and test operational states for critical events.

Return

GetOperation() return the current operations state, which is a combination of the following modes:

See Also

CTBase::SetOperation CTBase::GetAutoCommit CTBase::SetAutoCommit

CTBase::GetSystemConfig

Retrieve c-tree Plus system configuration values.

Syntax

LONG CTBase::GetSystemConfig(NINT index);

Description

GetSystemConfig() retrieves c-tree Plus system configuration values, as well as some of the important dynamic aspects of the system, such as the memory usage and the number of files in use. To determine if a particular system configuration option is active, call GetSystemConfig(), passing the corresponding pre-define constant for that option, and check if the value returned is non-zero.

The following pre-defined constant should be passed to GetSystemConfig():

The following constants only apply to client-server implementations:

The following constants are static compile time values:

The constants above and the pre-initialization resources section below have client and c-tree Server versions, except for the following three subscripts:

Constants ending with ‘app’ are specific to the client side of a client/server application. To check the same system setting for the c-tree Server, use the same subscript without the app extension. For example, to determine if Conditional Index support is active on the c-tree Server, use cfgCONDIDX as the subscript and cfgCONDIDXapp for the client side.

The pre-initialization resource constants below may be specified prior to a FairCom DB API initialization call, i.e ctdbLogon(), CTSession::Logon(), or CTSession.Logon(), in addition to having both a client and c-tree Server version, as discussed above.

1Pascal length byte

FairCom DB supports two different methods for specifying the length byte in a pascal data type. The original and non-traditional approach does not include the length byte in the byte count. For example, with a 1-byte data type, CT_FPSTRING, the smallest valid length byte would be 0. The new method follows the more traditional pascal convention of including the length byte in the byte count. For example, with the traditional approach, the smallest valid length for a 1-byte data type would be 1. Therefore, if cfgPASCALstapp or cfgPASCAL24app return a non-zero value, the new traditional approach is active.

To receive a valid return value from cfgPATH_SEPARATOR, ctPATH_SEP must be defined. The default definition found in ctopt2.h is:

#define ctPATH_SEP   '?'

This definition specifies that the system default path separator will be used. To use the same separator for all platforms, you might want to choose one of the following:

#define ctPATH_SEP   '\\'
/* define for Windows */
 
#define ctPATH_SEP   '/'
/* define for most Unix systems */
 
#define ctPATH_SEP   ':'
/* define for Mac OSX */
 
/* where the Uninitialized value is NINT_ERR for a client or FINT_ERR for a bound application */

The following constants can be used to capture system-wide cache and buffer statistics, (cache pages hold data record images and buffers hold index nodes), allowing an application to track the use of these resources.

Return

Returns a value that depends on the configuration constant passed to GetSystemConfig().

Example

// check if TRANPROC was turned
if (hSession.GetSystemConfig(ctTRANPROC))
    printf("TRANPROC was turned on during compilation\n");
else
    printf("TRANPROC was turned off during compilation\n");
 

See Also

none

CTBase::GetTransactionMode

Declaration

CTBEGIN_MODE CTBase::GetTransactionMode()

Description

Returns the transaction mode used when starting a transaction.

c-tree Plus offers a rich array of data integrity options. Full transaction processing offers the safest and best performance of all the available options. There are times when other c-tree Plus options, such as PREIMG, might be advantageous.

Return Values

See Also

CTBase::GetTransactionMode()

CTBase::GetUserTag

Syntax

pVOID GetUserTag ( )

Parameters

This method has no parameters.

Description

Retrieves the user tag.

Return

GetUserTag() returns the user tag.

See also

SetUserTag()

CTBase::IsLockActive

Syntax

CTBOOL IsLockActive ( )

Parameters

This method has no parameters.

Description

Indicates whether a session wide lock is active. A session wide lock is a lock that has been started with a call to Lock, with one of the READ, WRITE, and RESTORE mode variations, but not terminated with a call to Unlock or Lock with the mode parameter as FREE or SUSPEND.

IsLockActive() does not indicate if record lock is active. Record lock is one that is obtained with a call to CTRecord::LockRecord().

Return

IsLockActive() returns YES if the session wide lock is active and NO otherwise.

See also

Lock(), Unlock(), GetLockMode(), IsTransActive()

CTBase::IsTransActive

Syntax

CTBOOL IsTransActive ( ) const

Parameters

This method has no parameters.

Description

Indicates if a transaction has been started with a call to Begin, but not terminated with a call to Commit() or Abort().

Return

IsTransActive() returns YES if there is one transaction pending and NO otherwise.

See also

Begin(), Abort(), Commit(), IsLockActive()

CTBase::Lock

Syntax

void Lock(CTLOCK_MODE mode)

Parameters

• mode [in] the lock mode. The valid values for mode are shown in "FairCom DB API definitions".

Description

Enables or disables session-wide locks.

After a call to Lock with any mode but CTLOCK_FREE, any record that becomes a current record will be locked. For instance, all records read after a call to Lock will be locked. Notice that in the moment Lock is called, no file or record is locked. Instead, a flag is set internally to indicate that all new records read will lock the record. To simply lock the current record, use CTRecord::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 a record using a READ lock. When a 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 obtain any lock on that particular record. Yet anyone can still read the record.

If a record is read without any lock, it means that any other user can change the record contents. If a record is read with a READ lock, it means that any other user may still read the same record, but no user may obtain a WRITE lock, assuring the record will not be changed while a READ lock is kept on the record. When a record is read with a WRITE lock, the user who obtained the lock may update the record, but no other user may obtain a lock on the record.

A lock obtained with a call to CTBase::Lock(), no matter what object does the call, is always a Session lock, in the sense that any table operation after this call is subject to the locks.

A call to Abort(), Commit(), or Unlock() will release all session wide locks. A call to Lock with CTLOCK_FREE also releases the session wide locks.

Return

None.

Example

pRecord1->Lock();
pRecord1->SetFieldAsString("name", "Johny Wild");
pRecord1->Find(CTFIND_EQ);
 

See also

Unlock(), IsLockActive(), GetLockMode(), CTRecord::LockRecord(), CTBase::SetKeepLock(), Locking

CTBase::RestoreSavePoint

Syntax

void RestoreSavePoint (const NINT SavePoint)

Parameters

• SavePoint [in] a previously saved savepoint.

Description

Restore a previously set save point.

Return

None.

See also

SetSavePoint()

CTBase::SetAutoCommit

Declaration

void CTBase::SetAutoCommit(CTBOOL flag);

Description

CTBase::SetAutoCommit() sets the FairCom DB API auto commit mode.

• flag indicates if auto commit mode should be enabled or not.

The auto commit of transactions are invoked automatically when records are added or updated by a CTRecord::Write() call. Automatic transactions may increase performance by reducing network traffic for single record updates since this is equivalent of performing the following functions:

hRecord.Begin();
try
{
	hRecord.Write();
	hRecord.Commit();
}
catch (CTException)
{
	hRecord.Abort();
}

The following applies when an automatic transaction is performed:

1. An automatic transaction will only free locks acquired by the CTRecord::Write() function.
2. If an automatic transaction is aborted because of errors detected by CTRecord::Write() all locks acquired by CTRecord::Write() are released.
3. If locks are active, by calling CTBase::Lock() function, an automatic transaction will not release any locks when it commits or aborts the CTRecord::Write() operation.
4. If OPS_UNLOCK_UPD is on, both commits and aborts on automatic transactions release only locks obtained within trans and/or locks on records updated within transaction, regardless if the FairCom DB API session lock state is active or not.

Return Values

Example

/* 
	Example Code
*/
 

See Also

CTBase::GetAutoCommit() CTBase::SetOperation() CTBase::GetOperation()

CTBase::SetDefDateType

Syntax

void SetDefDateType (CTDATE_TYPE DateType)

Parameters

• DateType [in] the new default date type. For more information on the valid date types, see the Description below.

Description

Sets the default date type. The valid values for the date type are discussed in "Data Types".

Return

None.

See also

GetDefDateType()

CTBase::SetDefFloatFormat

Syntax

void SetDefFloatFormat(const CTString& format)

Parameters

• format [in] the default floating point string format.

Description

Sets the default floating point string format to be used in sprintf(). The default value initially is set to "%f", and may be changed to reflect the desired printing format.

Return

None.

See also

GetDefFloatFormat()

CTBase::SetDefTimeType

Syntax

void SetDefTimeType(CTTIME_TYPE TimeType)

Parameters

• TimeType [in] The new default time type. For more information on the valid time types, see the Description below.

Description

Sets the default time type. The valid values for the time type are shown in "Data Types".

Return

None.

See also

GetDefTimeType()

CTBase::SetError

Syntax

void SetError(const CTDBRET code)

Parameters

• code [in] the new error code.

Description

Sets the error code.

Return

None.

See also

GetError(), ClearError()

CTBase::SetHandle

Syntax

void SetHandle(CTHANDLE Handle)

Parameters

• Handle [in] is the object. Depending on the instance, it can be the Session, Database, Table, Record, Field, Index or Segment object.

Description

Sets the object.

Return

None.

See also

GetHandleId(), GetHandleId()

CTBase::SetKeepLock

Set the current keep lock mode when a transaction is committed or aborted.

Syntax

void CTBase::SetKeepLock(CTKEEP_MODE mode);

Description

When a transaction is terminated by calling either the CTBase::Commit() or CTBase::Abort() function, all locks are automatically freed, including the locks acquired outside the transaction. An application might want to control which locks are kept when the transaction ends. To support this ability, FairCom DB API introduced a function to control how locks are handled when a transaction terminates.

By default, the FairCom DB API begin transaction function, ctdbBegin(), will begin a transaction by invoking c-tree’s TRANBEG function with the ctTRNLOG and ctENABLE_BLK modes set. If the TRANBEG function succeeds, FairCom DB API’s ctdbBegin() function automatically calls LKISAM() to suspend locks enabled by TRANBEG, allowing users to enable any locks they wish: read locks, write locks, blocking or non-blocking. In this case, the FairCom DB API commit or abort transaction functions, ctdbCommit() and ctdbAbort(), call the appropriate c-tree ISAM functions to terminate the transaction and free all locks.

CTBase::SetKeepLock() set the extended keep lock mode applied when an active transaction is committed or aborted.

The keep lock mode is one of the following pre-defined constants:

Once the keep lock mode is set, it remains active until another keep mode is set or the keep mode is cleared by calling SetKeepLock() with mode CTKEEP_FREE.

Return

void

Example

// set the keep lock
hSession.SetKeepLock(CTKEEP_LOCK);

// begin a new transaction
hSession.Begin();

// do some operations and commit transaction
hSession.Commit();

// do some more operations and free all locks
hSession.Unlock();
 

See Also

CTBase::Abort(), CTBase::Begin(), CTBase::Commit(), CTBase::GetKeepLock()

CTBase::SetOperation

Syntax

void CTBase::SetOperation(CTOPS_MODE mode, CTOPS_STATE state);

Description

SetOperation() sets c-tree operation modes for special performance-related functionality and test operational states for critical events.

mode use a combination of the following values:

state must be set with one of the following state values:

Return Values

See Also

CTBase::GetOperation()

CTBase::SetSavePoint

Syntax

NINT SetSavePoint ( )

Parameters

This method has no parameters.

Description

Sets a new transaction save point, and returns this value.

Return

SetSavePoint() returns an integer with the save point number.

See also

RestoreSavePoint()

CTBase::SetUserTag

Syntax

void SetUserTag (pVOID tagptr)

Parameters

• tagptr [in] is the new tag to be set.

Description

Sets the user tag.

Return

None.

See also

GetUserTag()

CTBase::SetTransactionMode

Declaration

void CTBase::SetTransactionMode(CTBEGIN_MODE mode)

Description

c-tree Plus offers a rich array of data integrity options. Full transaction processing offers the safest and best performance of all the available options. There are times when other c-tree Plus options, such as PREIMG, might be advantageous.

Sets the transaction mode used when starting a transaction.

• mode is one of the following values:

This mode will be OR-ed in to form the transaction mode used when a c-tree transaction is started. If the transaction mode is CTBEGIN_NONE, the ctTRNLOG mode is used to start a new transaction.

Return Values

None.

See Also

CTBase::GetTransactionMode()

CTBase::SwitchInstance

Force a c-tree instance switch.

Declaration

void CTBase::SwitchInstance()

Description

Force a switch to the c-tree Plus instance indicated by the current session object. Each session object has its unique c-tree instance id.

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

Return

If any errors are detected, a CTException is thrown

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

Example

// declare a remote and local session objects
CTSession hRemove(CTSESSION_CTREE);
CTSession hLocal(CTSESSION_CTREE);

// logon to c-tree server using the remote session object
hRemote.Logon("FAIRCOMS", "ADMIN", "ADMIN");

// logon to local session using the local session object
hLocal.Logon("local", "ADMIN", "ADMIN);

// perform a c-tree instance switch and call //CtreeUserOperation function
hRemote.SwitchInstance();
CtreeUserOperation("!mkdir faircom", buffer, sizeof(buffer));
 

See also

CTRecord::SwitchContext(), CTTable::GetDatno(), CTTable::GetIdxno(), CTIndex::GetIdxno()

CTBase::Unlock

Syntax

void Unlock ( )

Parameters

This method has no parameters.

Description

Frees all session wide locks held by the program. The session wide locks obtained a call to Lock are also released by Abort() and Commit().

Notice that this call does not free the locks obtained with CTRecord::LockRecord(). CTRecord::UnlockRecord() can be used to free just one specific record lock, or CTTable::UnlockTable() can be used to release all records from one table, obtained with CTRecord::LockRecord().

Return

None.

See also

Lock(), IsLockActive(), GetLockMode(), Commit(), Abort(), CTRecord::UnlockRecord(), CTTable::UnlockTable(), Locking