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

Remember that CTHANDLE and CTDBRET are unknown types in .NET. To use the CTHANDLE keyword you must include one of the following lines at the top of your application:

C#:

using CTHANDLE = System.IntPtr;

using CTDBRET = System.Int32;

Visual Basic:

Imports CTHANDLE = System.IntPtr

Imports CTDBRET = System.Int32

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
• IsLockActive(): Indicates whether a session wide lock is active
• GetLockMode(): Retrieves the current record lock mode for session wide locks
• GetKeepLock(): Retrieves the current keep lock mode
• SetKeepLock(): Set the extended keep lock mode

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 sConsole.Write() 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 sConsole.Write() and sscanf()
• SetDefDateType(): Sets the default date type
• SetDefTimeType(): Sets the default time type

Other

• GetUserTag(): Retrieves the user tag.
• GetHandleType(): Retrieve the handle type
• GetTableType(): Retrieve the table type
• SetUserTag(): Sets the user tag.
• SwitchInstance(): Force a switch to the c-tree Plus instance indicated by the Session object.

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

ASession.Begin();

try

{

ADatabase.AddTable("custmast", "");

Console.Write("\nTable added to database.");

ASession.Commit();

}

catch (CTException err)

{

ASession.Abort();

Console.Write("\n\n{0} {1}",err.GetErrorCode(), err.GetErrorMsg());

}

See Also

Begin(), Commit(), IsTransActive()

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

ASession.Begin();

try {

ADatabase.AddTable("custmast", "");

Console.Write("\nTable added to database.");

ASession.Commit();

}

catch (CTException err)

{

ASession.Abort();

Console.Write("\n\n{0} {1}",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.ClearSavePoint

Syntax

void ClearSavePoint ( )

Parameters

This method has no parameters.

Description

Clears the last transaction save point.

Return

None.

See Also

SetSavePoint(), RestoreSavePoint()

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

ASession.Begin;

try

{

ADatabase.AddTable("custmast", "");

Console.Write("\nTable added to database.");

ASession.Commit();

}

catch (CTException err)

{

ASession.Abort( );

Console.Write("\n\n{0} {1}",err.GetErrorCode(), err.GetErrorMsg());

}

 

See Also

Begin(), Abort(), IsTransActive()

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

Syntax

DATE_TYPE GetDefDateType ( )

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

String GetDefFloatFormat ()

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

TIME_TYPE GetDefTimeType ( )

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

Parameters

This method has no parameters.

Description

Returns the handle.

Return

GetHandle() returns the c-tree Plus for .NET C API handle.

See Also

GetHandleId(), SetHandle()

CTBase.GetHandleId

Syntax

int GetHandleId ( )

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

SYNTAX

int GetHandleType ( )

PARAMETERS

This method has no parameters.

DESCRIPTION

Returns the handle type.

RETURN

GetHandleType() returns the handle type.

SEE ALSO

GetTableType()

CTBase.GetKeepLock

Syntax

KEEP_MODE GetKeepLock ( )

Parameters

This method has no parameters.

Description

Retrieves the current keep lock mode associated with the session. The valid keep lock modes are shown in SetKeepLock() description.

Return

GetKeepLock() returns the session wide keep lock mode.

See Also

SetKeepLock()

CTBase.GetLockMode

Syntax

LOCK_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 (LOCK_MODE enum)". If LOCK_MODE.LOCK_FREE is returned, no locks are currently active.

Return

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

See Also

Lock(), Unlock(), IsLockActive()

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

Declaration

LONG 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 Values

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

Example

The following example checks if TRANPROC was turned on during system compilation.
// check if TRANPROC was turned on

if (hSession.GetSystemConfig( ctTRANPROC ))

printf("TRANPROC was turned on during compilation\n");

else

printf("TRANPROC was turned off during compilation\n");

See Also

CTBase.GetTableType

SYNTAX

TABLE_TYPE GetTableType( )

PARAMETERS

This method has no parameters.

DESCRIPTION

Retrieve the table type.

RETURN

The valid types are:

If the parameter Handle is NULL or not a handle that can produce a table handle, GetTableType() return NONE.

SEE ALSO

GetHandleType()

CTBase.GetTransactionMode

Declaration

CTBEGIN_MODE CTBase.GetTransactionMode()

Description

Returns the transaction mode used when starting a transaction.

FairCom DB 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 FairCom DB options, such as PREIMG, might be advantageous.

Return Values

See Also

CTBase.GetTransactionMode()

CTBase.GetUserTag

Syntax

System.IntPtr GetUserTag()

Parameters

This method has no parameters.

Description

Retrieves the user tag.

Return

GetUserTag() returns the user tag.

See Also

SetUserTag()

CTBase.IsLockActive

Syntax

bool 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 true if the session wide lock is active and false otherwise.

See Also

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

CTBase.IsTransActive

Syntax

bool IsTransActive ( )

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 true if there is one transaction pending and yes otherwise.

See Also

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

CTBase.Lock

Syntax

void Lock(LOCK_MODE mode)

Parameters

• mode [in] the lock mode. The valid values for mode are shown in Lock Modes.

Description

Enables or disables session-wide locks.

After a call to Lock with any mode but LOCK_MODE.LOCK_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 LOCK_MODE.LOCK_FREE also releases the session wide locks.

Return

None.

Example

Record1.Lock();

Record1.SetFieldAsString("name", "Johny Wild");

Record1.Find(FIND_MODE.EQ);

See Also

Unlock(), IsLockActive(), GetLockMode(), CTRecord.LockRecord(), Locking

CTBase.RestoreSavePoint

Syntax

void RestoreSavePoint (int 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

SetAutoCommit() sets the 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 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 .NET session lock state is active or not.

Return Values

See Also

CTBase.GetAutoCommit() CTBase.SetOperation() CTBase.GetOperation()

CTBase.SetDefDateType

Syntax

void SetDefDateType (DATE_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(string 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(TIME_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(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

Syntax

void SetKeepLock(KEEP_LOCK mode)

Parameters

• Mode [in] is one of the KEEP_LOCK modes (see description).

Description

SetKeepLock() sets the extended keep lock mode applied when an active transaction is committed or aborted, by calling Commit() or Abort(). The valid keep lock modes is one of the following values:

• FREE_KEEP release all locks. Clear LKISAM state. This is the default mode when a session handle is allocated.
• LOCK_KEEP keep all locks acquired before and during transaction. Does not clear LKISAM state.
• OUT_KEEP release only locks obtained within transaction and/or locks on records updated within transaction. Does not clear LKISAM state.
• OUTALL_KEEP unconditionally keep all locks acquired before the transaction began. Free locks obtained obtained within the transaction. Does not clear LKISAM state.

Return

None

See Also

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:

See Also

CTBase.GetOperation()

CTBase.SetSavePoint

Syntax

uint 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.SetTransactionMode

Declaration

void CTBase.SetTransactionMode(CTBEGIN_MODE mode)

Description

FairCom DB 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 FairCom DB 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.SetUserTag

Syntax

void SetUserTag(System.IntPtr tagptr)

Parameters

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

Description

Sets the user tag.

Return

None.

See Also

GetUserTag()

CTBase.SwitchInstance

Syntax

void SwitchInstance ( )

Parameters

This method has no parameters.

Description

Force a switch to the FairCom DB instance indicated by the Session object. Each session object has its unique c-tree instance id. When most FairCom DB API .NET methods are called, they automatically perform a c-tree instance switch. SwitchInstance() may be useful before calling specific c-tree ISAM or low level calls to make sure the correct instance is active before making those calls. If any errors are detected, a CTException is thrown.

Return

None.

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