FairCom DB API .NET Definitions

Field Types

FairCom DB API, FairCom DB API .NET, and FairCom DB API VCL support all original FairCom DB field types and include redefinition for new field types. For compatibility reasons, the original c-tree Plus field types can be used, but FairCom suggests using the new field types.

Note that these do not represent new field types. They substitute a new name for existing FairCom DB field types. The new naming convention is used within the FairCom DB SQL product line, and offers a better description of the fields.

The new field types offer an improved path for future compatibility and better program reading. For more information, see Field type equivalencies across APIs.

FairCom DB API
Field Type		 FairCom DB
Field Type		 Equivalent
Data Type		 Implementation
 
CT_BOOL CT_BOOL CTBOOL One-byte Boolean
CT_TINYINT CT_CHAR CTSIGNED Signed one-byte integer.
CT_UTINYINT CT_CHARU CTUNSIGNED Unsigned one-byte integer.
CT_SMALLINT CT_INT2 CTSIGNED Signed two-byte integer.
CT_USMALLINT CT_INT2U CTUNSIGNED Unsigned two-byte integer.
CT_INTEGER CT_INT4 CTSIGNED Signed four-byte integer.
CT_UINTEGER CT_INT4U CTUNSIGNED Unsigned four-byte integer.
CT_MONEY CT_MONEY CTMONEY Signed four-byte integer interpreted as number of pennies (two fixed decimal places) up to a precision of 9.
CT_DATE CT_DATE CTDATE Unsigned four-byte integer interpreted as date. No time information.
CT_TIME CT_TIME CTTIME

Unsigned four-byte integer interpreted as time with whole second precision. No date information.

This data type does not support millisecond precision. CTTIMEMS functions are recommended for millisecond precision.
CT_TIME_MS CT_TIME_MS CTTIMEMS Similar to CTTIME but with millisecond precision.
CT_FLOAT CT_SFLOAT CTFLOAT Four-byte floating point.
CT_DOUBLE CT_DFLOAT CTFLOAT Eight-byte floating point.
CT_TIMESTAMP CT_TIMES CTDATETIME

Time stamp including date and time with millisecond precision.

This data type support millisecond precision.
CT_EFLOAT CT_EFLOAT CTFLOAT Extended precision floating point (not supported as a key segment).
CT_BINARY CT_F2STRING
(CT_ARRAY*) 		pTEXT, pUTEXT Arbitrary fixed-length data. Fixed-length binary data. 64-kilobytes maximum length.
CT_CHARS CT_FSTRING pTEXT Fixed-length delimited data. Fixed-length string data. 64-kilobytes maximum length.
CT_FPSTRING CT_FPSTRING pTEXT Fixed-length data with 1-byte length count. 255-bytes maximum length.
CT_F2STRING CT_F2STRING pTEXT Fixed-length data with 2-byte length count.
CT_F4STRING CT_F4STRING pTEXT Fixed-length data with 4-byte length count.
CT_BIGINT CT_BIGINT CTBIGINT Eight-byte signed integer.
CT_NUMBER CT_NUMBER CTNUMBER Scaled BCD number.
CT_CURRENCY CT_CURRENCY CTCURRENCY Eight-byte signed integer interpreted as currency value with four fixed decimal digits.
CT_PSTRING CT_PSTRING pTEXT Varying length field data with 1-byte length count.
CT_VARBINARY CT_2STRING pTEXT Varying length field data with 2-byte length count. Variable length binary data of up to 65535 bytes. 0 indicates no maximum. If not 0, must be set to at least a minimum of 3.
CT_LVB CT_4STRING pTEXT Varying length field data with 4-byte length count. Variable length binary data of up to 4294967295 bytes. 0 indicates no maximum. If not 0, must be set to at least a minimum of 5.
CT_VARCHAR or CT_LVC CT_STRING pTEXT Varying length field delimited data. Variable length string data. 0 indicates no maximum. If not 0, must be set to at least a minimum of 2.
CT_UBIGINT CT_INT8U CTUBIGNINT 8-byte unsigned integer.
CT_NCHAR CT_F2UNICODE   Fixed-length UNICODE char data.
CT_NVARCHAR CT_2UNICODE   Variable-length UNICODE char data.

*CT_BINARY field type was changed in FairCom DB V9 to CT_F2STRING.

FairCom DB API .NET FIELD_TYPE Enum

All the FairCom DB API .NET field types are defined using the FIELD_TYPE enum:

FairCom DB API .NET Field Type
BOOL
TINYINT
UTINYINT
SMALLINT
USMALLINT
INTEGER
UINTEGER
MONEY
DATE
TIME
FLOAT
DOUBLE
TIMESTAMP
EFLOAT
BINARY
CHARS
FPSTRING
F2STRING
F4STRING
BIGINT
NUMBER
CURRENCY
PSTRING
VARBINARY
LVB
VARCHAR/LVC

 

Find Modes

Use the following find modes with the record find methods:

FairCom DB API
Find mode		 FairCom DB API .NET
Find Mode		 Explanation
 
CTFIND_EQ EQ Find a record equal to the target
CTFIND_LT LT Find a record less than target
CTFIND_LE LE Find a record less or equal than target
CTFIND_GT GT Find a record greater than target
CTFIND_GE GE Find a record greater or equal than target

Note: The Find Mode CTFIND_EQ requires that the target contains values for all segments that compose the index and the index cannot allow duplicates.

Note: FairCom DB API .NET defines this mode with the FIND_MODE enum.

 

Key Types (KEY_TYPE enum)

FIXED_INDEX Fixed length key
LEADING_INDEX Fixed length keys that are likely to have leading character duplication among the key values
PADDING_INDEX Variable length keys for which not much leading character duplication is expected.
LEADPAD_INDEX Variable length keys for which much leading character duplication is expected.
ERROR_INDEX Index type error.

 

Record Lock Modes

The table below lists the lock modes that are to be used with the manual record locking function ctdbLockRecord().

These modes (except for the "_BLOCK" modes) are also returned by the ctdbGetRecordLock() function (see the explanations in parentheses).

FairCom DB API Record
Lock Modes		 FairCom DB API .NET
Lock Modes
Explanation
CTLOCK_FREE FREE_LOCK Free the data record lock / (the record lock is removed).
CTLOCK_READ READ_LOCK Non-blocking read locks / (the record has a read / shared lock).
CTLOCK_READ_BLOCK READ_BLOCK_LOCK Blocking read locks.
CTLOCK_WRITE WRITE_LOCK Non-blocking write locks / (the record has a write / exclusive lock). If the lock cannot be acquired, an error is returned.
CTLOCK_WRITE_BLOCK WRITE_BLOCK_LOCK Blocking write locks. The thread will block until the lock can be acquired.

Note: FairCom DB API .NET can find the Lock Modes listed in the LOCK_MODE enum.

See also Locking.

 

Session-Wide Lock Modes

FairCom DB API Lock Modes FairCom DB API .NET
Lock Modes
Explanation
CTLOCK_FREE FREE_LOCK Turn off session-wide record locking. Free all automatically-acquired locks (with certain exceptions, see below).
CTLOCK_READ READ_LOCK Non-blocking read locks. If the lock cannot be acquired an error is returned.
CTLOCK_READ_BLOCK READ_BLOCK_LOCK Blocking read lock. The thread will block until the lock can be acquired.
CTLOCK_WRITE WRITE_LOCK Non-blocking write lock. If the lock cannot be acquired an error is returned.
CTLOCK_WRITE_BLOCK WRITE_BLOCK_LOCK Blocking write lock. The thread will block until the lock can be acquired.
CTLOCK_RESET RESET_LOCK Equivalent to calling Lock with CTLOCK_FREE followed by Lock() with CTLOCK_WRITE. This releases currently-held record locks (with certain exceptions, see below).
CTLOCK_SUSPEND SUSPEND_LOCK Temporarily suspend session-wide record locking. While locking is suspended, new record reads, writes, and deletes will not be automatically locked. Existing record locks remain in place, though.
CTLOCK_RESTORE
_READ 		RESTORE_READ_LOCK To be used after a call to Lock with the CTLOCK_SUSPEND mode. This lock mode restores the lock mode as READ.
CTLOCK_RESTORE
_READ_BLOCK

RESTORE_READ

_BLOCK_LOCK

 To be used after a call to Lock with the CTLOCK_SUSPEND mode. This lock mode restores the lock mode as READ_BLOCK.
CTLOCK_RESTORE
_WRITE 		RESTORE_WRITE_LOCK To be used after a call to Lock with the CTLOCK_SUSPEND mode. This lock mode restores the lock mode as WRITE.
CTLOCK_RESTORE
_WRITE_BLOCK

RESTORE_WRITE

_BLOCK_LOCK

 To be used after a call to Lock with the CTLOCK_SUSPEND mode. This lock mode restores the lock mode as WRITE_BLOCK.
CTLOCK_RESTORE
_PREVIOUS 		  To be used after a call to Lock with the CTLOCK_SUSPEND mode. This lock mode restores the same lock mode that was valid before suspending the lock.

FairCom DB API .NET Lock Modes are defined in the LOCK_MODE enum.

 

Segment Modes

By default, the preferred segment modes (see Index segment modes) sort in ascending order. This can be changed to descending sort order by OR-ing CTSEG_DESCENDING with the segment mode. If a custom sort order is desired, OR the segment mode with CTSEG_ALTSEG instead.

The preferred segment modes make FairCom DB API-based tables fully compatible with ISAM/Low-Level applications and/or FairCom DB SQL applications.

FairCom DB API Segment Modes FairCom DB API .NET
Segment Modes
Explanation
CTSEG_SCHSEG SCHSEG_SEG Absolute field number
CTSEG_USCHSEG USCHSEG_SEG Absolute field number - uppercase
CTSEG_VSCHSEG VSCHSEG_SEG Absolute field number - pad strings
CTSEG_UVSCHSEG UVSCHSEG_SEG Absolute field number - pad strings upper
CTSEG_SCHSRL SCHSRL_SEG Absolute field number - auto increment
CTSEG_DESCENDING DESCENDING_SEG Descending segment mode
CTSEG_ALTSEG ALTSEG_SEG Alternative collating sequence
CTSEG_ENDSEG ENDSEG_SEG END segment mode
CTSEG_BITSEG (none) Bitmask segment: soffset holds field number of null bit mask; slength holds field number of target field
CTSEG_ALLNULLDUPSEG (none) Allow duplicate key values when all of the indexed fields are NULL
CTSEG_ANYNULLDUPSEG (none) Allow duplicate key values when any of the indexed fields are NULL

The other segment modes are kept for compatibility with existing FairCom DB applications. Advanced FairCom DB API functions like ctdbAlterTable() may not work properly if the segment mode is not one of the preferred segment modes.

You may specify these segment modes with ctdbAddSegmentEx(), which expects an absolute record offset where the segment is to start (instead of a field indicator), the length in bytes of the segment, and the segment mode.

FairCom DB API Segment Modes FairCom DB API .NET
Segment Modes
Explanation
CTSEG_REGSEG REGSEG_SEG Absolute byte offset - No transformation
CTSEG_INTSEG INTSEG_SEG Absolute byte offset - unsigned int/long
CTSEG_UREGSEG UREGSEG_SEG Absolute byte offset - uppercase
CTSEG_SRLSEG SRLSEG_SEG Absolute byte offset - auto increment
CTSEG_VARSEG VARSEG_SEG Relative field number
CTSEG_UVARSEG UVARSEG_SEG Relative field number - uppercase
CTSEG_SGNSEG SGNSEG_SEG Absolute byte offset - signed int/long
CTSEG_FLTSEG FLTSEG_SEG Absolute byte offset - float/double
CTSEG_DECSEG DECSEG_SEG Absolute byte offset - not yet implemented
CTSEG_BCDSEG BCDSEG_SEG Absolute byte offset - not yet implemented
CTSEG_DESCENDING DESCENDING_SEG Descending segment mode
CTSEG_ALTSEG ALTSEG_SEG Alternative collating sequence

FairCom DB API .NET Segment Modes are defined in the SET_MODE enum.

See also Index segment modes.

 

Table Create Modes (CREATE_MODE enum)

File mode Value File mode Value
NORMAL_CREATE 0 NORECBYT_CREATE 32
PREIMG_CREATE 1 NOROWID_CREATE 64
TRNLOG_CREATE 2 CHECKREAD_CREATE 128
WRITETHRU_CREATE 4 HUGEFILE_CREATE 256
CHECKLOCK_CREATE 8 NODELFLD_CREATE 512
VRLEN_CREATE 16 NONULFLD_CREATE 1024


 

Table Open Modes

FairCom DB API File
Open Mode		 FairCom DB API .NET
File Open Mode
Explanation
CTOPEN_NORMAL NORMAL_OPEN Use this mode if no other open modes apply.
CTOPEN_DATAONLY DATAONLY_OPEN

Open only the data table. Used to rebuild a table that may or may not be missing indexes.

  • Caution: Updates made to a data file with this file mode will not have any necessary updates reflected in the associated index files.
CTOPEN_EXCLUSIVE EXCLUSIVE_OPEN This mode opens the table and the associated index as exclusive. If this mode is used, only one user can open a table at a time. If an application already has the file(s) open in any mode, no other application can open the table as CTOPEN_EXCLUSIVE. Once an application opens a table as CTOPEN_EXCLUSIVE, no other application can open it. Reads and writes are cached for the files opened with this file mode since there are no integrity issues with only one process in the file.
CTOPEN_PERMANENT PERMANENT_OPEN Many operating systems and/or C compiler run-time libraries limit the number of files that can be opened at one time. A permanent file open causes the table and index files to be opened and stay open until the program executes a file close. A non-permanent file open causes the table data and index files to be opened, but allows them to be transparently closed and reopened to allow other data and index files to be used. When it is necessary for a data and index file to be temporarily closed, FairCom DB selects the least recently used file. This file remains closed until it is used, at which time it will be automatically reopened. Non-permanent mode is the default and should be used unless you have a special circumstance. This strategy causes FairCom DB to use all available file descriptors.
CTOPEN_CORRUPT CORRUPT_OPEN

This mode opens tables with corrupted indexes, incompatible DODA definitions, or sometimes tables with corrupted data.

 

Corrupt indexes:

With FairCom DB API this mode is usually used in conjunction with the ctdbAlterTable() function to perform a rebuild: open the table with CTOPEN_CORRUPT mode then call ctdbAlterTable() with the CTDB_ALTER_INDEX action to force the rebuild of all indexes of the table.

You can also call ctdbAlterTable() with the (CTDB_ALTER_INDEX | CTDB_ALTER_PURGEDUP) actions to purge any duplicate records that may cause the index rebuild to fail.

 

Incompatible DODA definitions:

This mode can be used to open tables that would otherwise fail with error

4187(CTDBRET_INVFIELDDEF) or 4016 (CTDBRET_FIELDEXIST). It can then adjust and update the DODA.

 

Corrupt table:

If a table becomes corrupt, the table may be opened with CTOPEN_CORRUPT mode and then ctdbAlterTable() is invoked with the CTDB_ALL_FULL action to try to recover the table. Note that this is a last-ditch effort that could cause data loss. Please contact FairCom before you do this.
CTOPEN_CHECKLOCK CHECKLOCK_OPEN Tables opened with this mode require a record lock before a record can be updated. If a lock is not obtained, the error code DADV_ERR is returned.
CTOPEN_CHECKREAD CHECKREAD_OPEN Tables opened with this mode require a record lock as records are read. Obtain at least a read lock on a record before it can be read, otherwise the function will return error code DADV_ERR.
CTOPEN_READONLY READONLY_OPEN Opens the table in READONLY mode and does not allow any modifications to the table structure or data records.
CTOPEN_UNLOCKONCLOSE UNLOCKONCLOSE_OPEN Enables ctdbCloseTable() to explicitly call ctdbUnLockTable().

Note: FairCom DB API .NET users can find the open modes listed in the OPEN_MODE enum.

 

Table Permissions (TABLE_PERMS enum)

FairCom DB API
Permission Constant		 FairCom DB API .NET
Permission Constant
Explanation
OPF_READ O_READ owner read permission
OPF_WRITE O_WRITE owner write/update permission
OPF_DEF O_DEF owner file definition permission
OPF_DELETE O_DELETE owner file deletion permission
OPF_ALL O_ALL owner granted all permissions
OPF_NOPASS O_NOPASS owner grants read only without password
GPF_NONE G_NONE group access denied
GPF_READ G_READ group read permission
GPF_WRITE G_WRITE group write/update permission
GPF_DEF G_DEF group file definition permission
GPF_DELETE G_DELETE group file deletion permission
GPF_NOPASS G_NOPASS group read only access without password
WPF_NONE W_NONE world access denied
WPF_READ W_READ world read permission
WPF_WRITE W_WRITE world write/update permission
WPF_DEF W_DEF world file definition permission
WPF_DELETE W_DELETE world file deletion permission
WPF_NOPASS W_NOPASS world read only access without password


Lib Types (LIB_TYPE enum)

FairCom DB API .NET Symbolic Constant Explanation
 
SINGLE Single User
MUSER Multi User
CLIENT Client
LOCLIB Loclib
SERVER Server Side Library
THREA Multithread
TRAN Transaction Processing
HUGE Hugefile Support


User Profile (USER_PROF enum)

FairCom DB API .NET Symbolic Constant Explanation
 

NTKEY

 Do not perform auto tfrmkey

SAV_ENV

 savenv mode for transactions

SQL

 Enable SQL support

SERIAL

 Enable strict serialization

MEMABS

 Internal memory management

NDATA

 Do not perform auto data unifrmat conversion

LOCLIB

 Use a local library: not srvr

PTHTMP

 Add tmpname to input pathotherwise use system
tmpname

CODCNV

 Auto language conversion

CLRCHK

 Clear transaction logs

CUSTOM

 Custom server application

ENCRYPT

 Enable encryption

ADMSPCL

 Full admin logon

LOGRED

 Read-only active log open


Index Types (IDXNO enum)

FairCom DB API .NET Symbolic Constant Explanation
 
RECBYT_NO Recbyt index
ROWID_NO Rowid index
DATA_NO Data Mode (no index)


Table Types (TABLE_TYPE enum)

FairCom DB API .NET Symbolic Constant Explanation
 
NONE Not table handle or table not active
SESSION_DICT Session dictionary table
DATABASE_DICT Database dictionary table
SQL_CATALOG c-treeSQL catalog table
USER User table


System Filters (SYS_FILTER enum)

FairCom DB API .NET Symbolic Constant Explanation
 
NONE Indicate no system wide record filter
READ Indicate a read system wide filter
WRITE Indicate a write system wide filter

 

Index Key Types

FairCom DB API
Index Type		 FairCom DB API .NET
Index Type
Description
CTINDEX_FIXED FIXED_INDEX Fixed-length key
CTINDEX_LEADING LEADING_INDEX Fixed-length keys that are likely to have leading character duplication among the key values
CTINDEX_PADDING PADDING_INDEX Variable-length keys for which not much leading character duplication is expected.
CTINDEX_LEADPAD LEADPAD_INDEX Variable-length keys for which much leading character duplication is expected.
CTINDEX_ERROR ERROR_INDEX Index type error.
CTINDEX_DFRIDX DFRIDX_INDEX. Indicates a deferred index (V11 and later).
CTINDEX_NOMOD NOMOD_INDEX Indicates an index with unmodifiable ISAM and FairCom DB API keys (V11 and later).
CTINDEX_BCKLOAD BCKLOAD_INDEX Perform initial key load in background.
(V11.7 and later)
CTINDEX_VARIABLE VARIABLE_INDEX Node-level compression with trailing spaces and metadata compression to fit more in each page block
CTINDEX_VARIABLE_RLE VARIABLE_RLE_INDEX Use sRLE key compression for shorter index entries / smaller index files

Note: FairCom DB API .NET Index Key Types are defined in the KEY_TYPE enum.

Deferred Indexing (V11 and later)

The FairCom DB API add, delete, and update operations perform key insert and deletes on every index associated with a data file:

  • a record add inserts a key value for each associated index.
  • a record delete deletes a key value for each associated index.
  • a record update deletes the old key and inserts the new key for each associated index (for those keys whose values changed).

However, each additional index operation can impose measurable performance loss, especially when numerous indexes are involved. If these immediate key operations could be held off for a period of time, applications can gain substantial performance in many circumstances. In V11 (and later), FairCom addressed these challenges with deferred maintenance modes. By delaying select index operations, applications can quickly create and/or update files with large numbers of indexes very quickly.

Background Loading (V11.7 and later)

ctdbCheckIndexBackgroundLoad() function can be used to monitor the status of the index loading on tables.

See Also:

NAV (FairCom DB API) API Variable Length Keys with Compression

 

 

.net database faircom api

Was this article helpful?

Give feedback about this article

Related Articles