Scalar Types
FairCom DB API .NET takes advantage of the vast choice of types available in .NET and uses these types every time it is possible.
Users that are accustomed with standard FairCom DB or FairCom DB API types may still use these types provided a mapping is established as explained later.
The following table shows some of the c-tree types mapped to corresponding .NET types.
| c-tree Plus/FairCom DB API | .NET |
|---|---|
| TEXT | char (System.Char) |
| UTEXT | byte (System.Byte) |
| COUNT | short (System.Int16) |
| UCOUNT | ushort (System.UInt16) |
| NINT | int (System.Int32) |
| UINT | uint (System.UInt32) |
| LONG | int (System.Int32) |
| ULONG | uint (System.UInt32) |
| CTTIME | uint (System.UInt32) |
| VRLEN | int (System.Int32) |
| pVOID | Intptr |
| CTBOOL | bool (Sustem.Boolean) |
| CTSIGNED | int (System.Int32) |
| CTUNSIGNED | uint (System.UInt32) |
| DOUBLE | double (System.Double) |
| CTFLOAT | single (System.Single) |
| CTHANDLE | IntPtr (System.IntPtr) |
The usual c-tree types may still be used provided they are mapped to .NET types with the following syntax:
C#
using CTHANDLE = System.IntPtr;
VB.NET
Imports CTHANDLE = System.IntPtr
The CTString class used by FairCom DB API is not used in FairCom DB API .NET. Instead, the standard .NET String class for unvariable strings or the StringBuilder class is used.
Date Types
CTDATE is declared as an unsigned 32-bit integer stored as the number of days since March 1st 1700. It is compatible with FairCom’s r-tree and ODBC products. A CTDATE value of 1 matches the date March 1st 1700, a value of 2 means March 2nd 1700, etc.
Since CTDATE is a 32-bit unsigned integer, numerical operations with dates can be done using standard C operators. For example, to add 10 days to a date use the normal C operation date + 10 (assuming that date is a CTDATE type). To get the difference in days of two dates, just subtract one date from another.
FairCom DB API .NET provides the class CTDate that exposes the following set of methods to allow manipulation of the CTDATE type in applications:
| Method | Operation |
|---|---|
| Pack() | Pack a date as year, month and day and store the result in pDate. The date is checked and ctdbDatePack() returns CTDBRET_OK if the date was packed correctly. |
| Unpack() | Update a CTDATE value into year, month and day. |
| ToString() | Convert a packed CTDATE value into string. The format of the date in string form is given by DateType(). |
| StringToDate() | Convert a date in string format to a packed CTDATE value. The format of the date in string form is given by DateType() as described above. |
| Day() | Retrieve the day component of a packed date type. |
| Month() | Retrieve the month component of a packed date type. |
| Year() | Retrieve the year component of a packed date type. |
| IsLeapYear() | Indicate if the year component of the packed date type is a leap year. |
| DayOfWeek() | Retrieve the day of the week for a given packed date type. Sunday is 0, Monday is 1, Tuesday is 2, and so on. |
| CurrentDate() | Retrieve the current system date and store it in CTDATE packed format. |
Date formats for string conversion are defined in the DATE_TYPE enum and are shown in the following table.
The possible date formats for string conversion are:
| FairCom DB API Symbolic Constant |
FairCom DB API .NET Symbolic Constant |
Description |
|---|---|---|
| CTDATE_MDCY | MDCY_DATE | Date is mm/dd/ccyy |
| CTDATE_MDY | MDY_DATE | Date is mm/dd/yy |
| CTDATE_DMCY | DMCY_DATE | Date is dd/mm/ccyy |
| CTDATE_DMY | DMY_DATE | Date is dd/mm/yy |
| CTDATE_CYMD | CYMD_DATE | Date is ccyymmdd |
| CTDATE_YMD | YMD_DATE | Date is yymmdd |
Time Types
CTTIME is declared as a 32-bit unsigned integer, stored as the number of seconds since midnight. It is compatible with FairCom's r-tree and ODBC products. c-tree Plus for .NET provides the class CTTime that exposes the following set of methods to manipulate the CTTIME type:
| Method | Operation |
|---|---|
| Pack() | Pack a time from hour, minute, and second into a CTTIME form. |
| Unpack() | Unpack a CTTIME time into hour, minute, and second. |
| TimeToString() | Convert a packed time value into string format. |
| StringToTime() | Convert a time in string form into a packed time. TimeType() gives the string form of the time value. |
| Hour() | Retrieve the hour component of a packed time. The hour returned is a 24-hour value. Example 11 pm is returned as 23. |
| Minute() | Retrieve the minute component of a packed time. |
| Second() | Retrieve the second component of a packed time. |
| CurrentTime() | Retrieve the current system time. |
String conversion are defined in the TIME_TYPE enum and are shown in the following table.
Time Types can be one of the following string time formats:
| FairCom DB API Symbolic Constant |
FairCom DB API .NET Symbolic Constant |
Description |
|---|---|---|
| CTTIME_HMSP | HMSP_TIME | Time is hh:mm:ss am|pm |
| CTTIME_HMP | HMP_TIME | Time is hh:mm am|pm |
| CTTIME_HMS | HMS_TIME | Time is hh:mm:ss (24 hour) |
| CTTIME_HM | HM_TIME | Time is hh:mm (24 hour) |
| CTTIME_MIL | MIL_TIME | Time is hhmm (military) |
| CTTIME_HHMST | Time is hh:mm:ss.ttt (24 hour) |
Date/Time (Timestamp) Types
CTDATETIME is declared as a double type and stores both the date and time. This type is also called a time stamp. The date component of a CTDATETIME value is stored as the value on the left of the decimal point, while the time component is stored as the value on the right side of the decimal point.
For additional precision, there is also the CTDATETIME100NS data type, which is the same as CTDATETIME, except that it has a precision of 7 digits to the right of the timestamp's decimal point (.1 microseconds). For example: 2026-01-01T00:00:00.1234567Z.
FairCom DB API .NET provides the class CTDateTime that exposes the following set of methods to manipulate the CTDATETIME (or CTDATETIME100NS) type.
| Method | Operation |
|---|---|
| Pack() | Pack a date and time into a CTDATETIME value. |
| Unpack() | Unpack a CTDATETIME value into year, month, day, hour, minute, and second. |
| GetDate() | Retrieve the CTDATE component of a CTDATETIME value. |
| GetTime() | Retrieve the CTTIME component of a CTDATETIME value. |
| DateTimeToString() | Convert a CTDATETIME to string. |
| StringToDateTime() | Convert a string to i. |
Numeric Types
Numeric types are used to manipulate numeric values that are too large for the scalar types or numeric values representing currency values. FairCom DB API .NET implements the following numeric types.
CTBIGINT
CTBIGINT is a 64-bit signed integer type. Today most C compilers are capable of dealing with 64-bit integers. In the Windows operating system, Borland, Microsoft and Watcom use a __int64 type to represent native 64-bit integers, while in other operating systems such as Unix and Linux, 64-bit integers are represented as long long types.
The following set of functions converts of CTBIGINT into other FairCom DB API types.
Note: Conversions to CTBIGINT in C# use a constructor in the format: CTBigint(const [CT type]& value) and are represented below as CTBigint([CT type]).
| Method | Operation |
|---|---|
| AsLong | Convert a CTBIGINT value to a long (32-bit signed integer). If the CTBIGINT value is too large for the conversion, AsLong() returns CTDBRET_OVERFLOW or CTDBRET_UNDERFLOW errors. |
| AsFloat | Convert a CTBIGINT value to CTFLOAT. |
| AsString | Convert a CTBIGINT value to string. |
| CTBigint(CTString) | Convert a string to CTBIGINT value. |
CTMONEY
CTMONEY represents a currency value in a 32-bit signed integer. The last two decimal digits of the value are used as the decimal part of the value. For example, a currency value of 123.45 is represented in a CTMONEY as 12345. A currency value of 1 is represented in CTMONEY as 100.
Since all the operations performed on CTMONEY values are integer operations, this type offers exact currency value capabilities that do not need large values or large precision at excellent performance that is very close to 32-bit integer performance.
FairCom DB API .NET provides the class CTMoney that exposes the following set of methods to manipulate the CTMONEY values, including functions for performing the basic arithmetic operations on CTMONEY values. This set of basic arithmetic operations is especially important in multiplication and division of CTMONEY values. Take for example the multiplication of two values such as 123.45 and 67.89. These values are represented in a CTMONEY type as 12345 and 6789 respectively. An integer multiplication on the values above would give the result 83810205, which is 838102.05 in CTMONEY representation. This result is clearly wrong since the expected result would be 8381.02. The same principle applies to division operations. By using the CTMONEY API provided by FairCom DB API .NET, the user will be able to operate correctly with CTMONEY values.
Also, C# overrides operators (such as +, -, *, and /) so that the result returned is the same type as the items operated upon. For example, the following command would put the result in c as type CTMoney. In C#, comparison operators can be used for any CT types; the return is a Boolean indicating true or false.
c = (CTMoney) a + (CTMoney) b;
| Method | Operation |
|---|---|
| AsLong() | Convert a CTMONEY value to LONG. Only the integer portion of the CTMONEY value is converted to LONG, as the decimal portion of the CTMONEY value is ignored for the conversion. |
| AsFloat() | Convert CTMONEY value to CTFLOAT. |
| AsString() | Convert CTMONEY value to string. |
CTCURRENCY
CTCURRENCY represents a currency value in a 64-bit signed integer. The last four decimal digits of the value are used as the decimal part of the value. For example, a currency value of 123.45 is represented in a CTCURRENCY type as 1234500. A currency value of 1 is represented in CTCURRENCY as 10000.
Since all the operations performed on CTCURRENCY values are integer operations, this type offers exact currency value capabilities with large value capabilities and good precision at excellent performance that is very close to 64-bit integer performance.
FairCom DB API .NET provides the class CTCurrency that exposes the following set of methods to manipulate CTCURRENCY values, including functions for performing the basic arithmetic operations on CTCURRENCY values. This set of basic arithmetic operations is especially important in multiplication and division of CTCURRENCY values. Take for example the multiplication of two values such as 123.45 and 67.89. These values are represented in a CTCURRENCY type as 1234500 and 678900 respectively. An integer multiplication on the values above would yield 838102050000, which is 83810205.0000 in CTCURRENCY representation. This result is clearly wrong since the expected result would be 8381.02. The same principle applies to division operation. By using the CTCURRENCY API provided by FairCom DB API .NET, the user will be able to operate correctly with CTCURRENCY values.
Also, C# overrides operators (such as +, -, *, and /) so that the result returned is the same type as the items operated upon. For example, the following command puts the result in c as type CTCurrency. In C#, comparison operators can be used for any CT types; the return is a Boolean indicating true or false:
c = (CTCurrency) a + (CTCurrency) b;
| Method | Operation |
|---|---|
| CTCurrency(CTMoney) | Convert a CTMONEY value to CTCURRENCY value. |
| AsMoney() | Convert a CTCURRENCY value to CTMONEY value. |
| AsLong() | Convert a CTCURRENCY value to a LONG value. |
| AsBigint() | Convert a CTCURRENCY value to CTBIGINT value. |
| CTCurrency(CTBigint) | Convert a CTBIGINT value to CTCURRENCY value. |
| AsFloat() | Convert a CTCURRENCY value to a CTFLOAT value. |
| AsString() | Convert a CTCURRENCY value to a string. |
| StringToCurrency() | Convert a string to a CTCURRENCY value. |
CTNUMBER
CTNUMBER corresponds to a number with a given precision (maximum number of digits) and scale (the number of digits to the right of the decimal point). Numeric values can have maximum values of 32 digits precision and scale of 0 (this is 99999999999999999999999999999999), which can represent very large exact values.
FairCom DB API .NET provides the class CTNumber that exposes the following set of methods to manipulate this very powerful number representation.
| Method | Operation |
|---|---|
| AsMoney() | Convert CTNUMBER to CTMONEY. |
| AsLong() | Convert CTNUMBER to LONG. |
| AsBigint() | Convert CTNUMBER to CTBIGINT. |
| AsCurrency() | Convert CTNUMBER to CTCURRENCY. |
| AsFloat() | Convert CTNUMBER to CTFLOAT. |
| AsString() | Convert CTNUMBER to string. |
| Zero() | Set the value pointed by pNumber to zero. |
| IsZero() | Return true if the value is zero. |
| Round() | Round the value pointer by num to the number of decimal digits (digits to the right of the decimal point) indicated by scale. |
| DecimalDigits() | Given the CTNUMBER data, stores the number of digits to the left of the decimal point in digit_before and stores the number of digits to the right of decimal point in digit_after. |
Also, C# overrides operators (such as +, -, *, and /) so that the result returned is the same type as the items operated upon. For example, the following command would put the result in c as type CTNumber. In C#, comparison operators can be used for any CT types; the return is a Boolean indicating true or false.
c = (CTNumber) a + (CTNumber) b;