FairCom DB API for C

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 implements the following numeric types:

In This Section

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.

Function	Operation
ctdbBigIntToLong	Convert a CTBIGINT value to a long (32 bit signed integer). If the CTBIGINT value is too large for the conversion, ctdbBigIntToLong() return either CTDBRET_OVERFLOW or CTDBRET_UNDERFLOW errors.
ctdbLongToBigInt	Convert a long value to CTBIGINT.
ctdbBigIntToFloat	Convert a CTBIGINT value to CTFLOAT.
ctdbFloatToBigInt	Convert a CTFLOAT value to CTBIGINT.
ctdbBigIntToString	Convert a CTBIGINT value to string.
ctdbStringToBigInt	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 with 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 provides the following set of functions to manipulate CTMONEY values, including functions for performing the basic arithmetic operations on CTMONEY values. These set of basic arithmetic operations are 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 operation. By using the CTMONEY API provided by FairCom DB API, the user will be able to operate correctly with CTMONEY values.

Function	Operation
ctdbMoneyToLong	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.
ctdbLongToMoney	Convert LONG to CTMONEY .
ctdbMoneyToFloat	Convert CTMONEY value to CTFLOAT.
ctdbFloatToMoney	Convert CTFLOAT value to CTMONEY .
ctdbMoneyToString	Convert CTMONEY value to string.
ctdbStringToMoney	Convert string to CTMONEY value.
ctdbMoneyAdd	Add two CTMONEY values left and right and store the result in pResult. The mathematical equivalent of this function would be pResult = left + right.
ctdbMoneySub	Subtract two CTMONEY values left and right and store the result in pResult. The mathematical equivalent of this function would be pResult = left - right.
ctdbMoneyMul	Multiply two CTMONEY values and store the result in pResult. The mathematical equivalent of this function would be pResult = left * right.
ctdbMoneyDiv	Divide two CTMONEY values and store the result in pResult. The mathematical equivalent of this function would be pResult = left / right. If the value of right is zero, ctdbMoneyDiv() returns CTDBRET_DIVBYZERO.
ctdbMoneyCmp	Compare two CTMONEY values left and right and return zero value if left is equal to right. Return negative value if left is less than right and return a positive value if left is greater than right.
ctdbMoneyAbs	Return the absolute value of a CTMONEY value.

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. Example: a currency value of 123.45 is represented with 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.

pResult provides the following set of functions to manipulate CTCURRENCY values, including functions for performing the basic arithmetic operations on CTCURRENCY values. This set of basic arithmetic operations are 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 pResult , the user will be able to operate correctly with CTCURRENCY values.

FairCom DB API Function	Operation
ctdbMoneyToCurrency	Convert a CTMONEY value to CTCURRENCY value.
ctdbCurrencyToMoney	Convert a CTCURRENCY value to CTMONEY value.
ctdbCurrencyToLong	Convert a CTCURRENCY value to a LONG value.
ctdbLongToCurrency	Convert a LONG value to CTCURRENCY value.
ctdbCurrencyToBigInt	Convert a CTCURRENCY value to CTBIGINT value.
ctdbBigIntToCurrency	Convert a CTBIGINT value to CTCURRENCY value.
ctdbCurrencyToFloat	Convert a CTCURRENCY value to a CTFLOAT value.
ctdbFloatToCurrency	Convert a CTFLOAT value to CTCURRENCY value.
ctdbCurrencyToString	Convert a CTCURRENCY value to a string.
ctdbStringToCurrency	Convert a string to a CTCURRENCY value.
ctdbCurrencyAdd	Add two CTCURRENCY values left and right and store the result in pResult. The mathematical equivalent of this function would be pResult = left + right.
ctdbCurrencySub	Subtract two CTCURRENCY values left and right, and store the result in pResult. The mathematical equivalent of this function would be pResult = left - right.
ctdbCurrencyMul	Multiply two CTCURRENCY values left and right and store the result in pResult. The mathematical equivalent of this function would be pResult = left * right.
ctdbCurrencyDiv	Divide two CTCURRENCY values left, and right and store the result in pResult. The mathematical equivalent of this function would be pResult = left / right. If the value of right is zero, ctdbCurrencyDiv() returns CTDBRET_DIVBYZERO.
ctdbCurrencyCmp	Compare two CTCURRENCY values. If the value of left and right are equal, ctdbCurrencyCmp() return zero. If left is greater than right return a positive value. If the value of left is less than right return a negative value.
ctdbCurrencyAbs	Return the absolute value of CTCURRENCY value.
ctdbCurrencyRound	Round the CTCURRENCY value to the number of decimal places specified by scale.

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.

pResult provides the following set of functions to manipulate this very powerful number representation.

Function	Operation
ctdbMoneyToNumber	Convert CTMONEY to CTNUMBER.
ctdbNumberToMoney	Convert CTNUMBER to CTMONEY.
ctdbNumberToLong	Convert CTNUMBER to LONG.
ctdbLongToNumber	Convert LONG to CTNUMBER.
ctdbNumberToBigInt	Convert CTNUMBER to CTBIGINT.
ctdbBigIntToNumber	Convert CTBIGINT to CTNUMBER.
ctdbNumberToCurrency	Convert CTNUMBER to CTCURRENCY.
ctdbCurrencyToNumber	Convert CTCURRENCY to CTNUMBER.
ctdbNumberToFloat	Convert CTNUMBER to CTFLOAT.
ctdbFloatToNumber	Convert CTFLOAT to CTNUMBER.
ctdbNumberToString	Convert CTNUMBER to string.
ctdbStringToNumber	Convert String to CTNUMBER.
ctdbNumberAdd	Add two CTNUMBER values left and right and store the result in pResult. The mathematical equivalent of this function would be pResult = left + right.
ctdbNumberSub	Subtract two CTNUMBER values left and right and store the result in pResult. The mathematical equivalent of this function would be pResult = left - right.
ctdbNumberMul	Multiply two CTNUMBER values left and right and store the result in pResult. The mathematical equivalent of this function would be pResult = left * right.
ctdbNumberDiv	Divide two CTNUMBER values left and right and store the result in pResult. The mathematical equivalent of this function would be pResult = left / right. If the value of right is zero, ctdbNumberDiv() return CTDBRET_DIVBYZERO.
ctdbNumberZero	Set the value pointed by pNumber to zero.
ctdbIsNumberZero	Return YES if the value pointed by pNumber is zero.
ctdbNumberCmp	Compare two CTNUMBERs and return zero if both numbers are equal. Return a negative value if pLeft is less than pRight. Return a positive value if pLeft is greater than pRight.
ctdbNumberAbs	Return the absolute value of the number pointed to by pResult.
ctdbNumberNegate	Invert the sign of the value pointed to by pSource and place the result in pResult. The mathematical equivalent of this function would be pResult = -pSource.
ctdbNumberCopy	Copy the value of the number pointed to by pSource into pDest. In other words, assign the value of pSource into pDest.
ctdbNumberRound	Round the value pointed to by num to the number of decimal digits (digits to the right of the decimal point) indicated by scale.
ctdbNumberGetDecimal	Given the CTNUMBER data, ctdbNumberGetDecimal() retrieves the number of digits to the left of the decimal point and store it in digit_before and retrieves the number of digits to the right of decimal point and stores it in digit_after.