\he{LONGMATH - documentation of how to portably program with 32bit numbers}

Currently only one non-32bit-aware compiler is supported, so the interface
follows the one implemented with Micro-C.

Micro-C does natively support only one data type, all other types are
somehow mapped to it, it's \tok{(int)}. Because DOS is, by design, a 16bit
system, the \tok{(int)} data type is a 16bit integer number. Thus, no
32bit arethmetics is natively possible to be represented internally.

To compensate this problem the author of Micro-C implemented an integer
bigNumber function set dealing with \tok{LSIZE}-sized fix-point numbers.
Micro-C itself is shipped with functions precompiled with \tok{LSIZE == 4},
thus, 32bit numbers.

The set of functions includes to:
\item initialize a LONGMATH number with a 16bit number,
\item assign a LONGMATH number to another one,
\item add, subtract, multiply, divide and compare two LONGMATH numbers,
\item test a LONGMATH number, it it is zero,
\item shift a LONGMATH number one bit to the left or right, and
\item convert a LONGMATH number into an ASCIZ representation assuming
	the no decimal-point is to be included.
\endlist

LONGMATH numbers are to be implemented as:\example{|}
|	char num[LSIZE];
where \tok{LSIZE} is nowhere defined within the C header files, but
refered to in the documentation as the size of the bigNumber implementation.
Usually, \tok{LSIZE} is equal to \tok{4} as remarked above.

Here is a complete list of functions Micro-C offers, note: \para{num} always
refers to a LONGMATH number, \para{n} to a 16bit number:
\item \tok{longset(char *num, int n)}: \tok{num := n}
\item \tok{longcpy(char *num1, char *num2)}: \tok{num1 := num2}
\item \tok{longadd(char *num1, char *num2)}: \tok{num1 += num2}
\item \tok{longsub(char *num1, char *num2)}: \tok{num1 -= num2}
\item \tok{longmul(char *num1, char *num2)}: \tok{num1 *= num2}
\item \tok{longdiv(char *num1, char *num2)}: \tok{num1 /= num2} -and- \tok{Longreg := num1 % num2}
\item \tok{longcmp(char *num1, char *num2)}: 
	\newlist\item -1: if \tok{num1 < num2}
	\item 0: if \tok{num1 == num2}
	\item +1: if \tok{num1 >  num2}
	\endlist
\item \tok{longtst(char *num)}: \tok{num != 0}
\item \tok{longshl(char *num)}: \tok{num <<= 1}
\item \tok{longshr(char *num)}: \tok{num >>= 1}
\item \tok{atol(char *string, char *num, int radix)}: \tok{num := strtol(string)}
\item \tok{ltoa(char *num, char *string, int radix)}: \tok{sprintf(string, "%ld", num)}
\endlist
Micro-C also offers an useful return value for most of the functions.

The \subsys{longmath} now puts together the way a 32bit-aware compiler
handles 32bit numbers and the way Micro-C can do. First the indifferences
are taken from both implementations:
\enum Micro-C's LONGMATH implementation is assumed to follow: \tok{LSIZE == 4}:
	This way the range of the numbers of Micro-C and other compilers are
	equal.
\enum A \tok{longadd()} function seems to be represented by
	\tok{num1 += num2} in other compilers best, so the return values of
	functions cannot be used. Meaning that any side effects are cut from
	the functions and the primary functionality remains, e.g. to \em{add}
	two 32bit numbers.
\endlist

For all compilers the same data type shall be used to declare and
define 32bit numbers; the new data type \tok{dword} has been introduced.
As a side effect for the Micro-C implementation this data type is
a structure:\example{|}
|	struct dword_ {
|		int dw_hi;
|		unsigned dw_lo;
|	};
|	#define dword struct dword_
This way the 32bit numbers are compatible with the native LONGMATH implementation of Micro-C and also allows a fast access to both words. Other compilers
will simply use:\example{|}
|	typedef long dword;

When a 32bit number is passed as an argument to a function, Micro-C
differs heavily from other compilers, because:
\enum Micro-C is \em{unable} to represent 32bit constants, and
\enum Micro-C passes a \em{pointer} to a 32bit variable rather than
	the value of it.
\endlist
This implies the following rules:
\enum The \subsys{longmath} cannot include 32bit constants.
\enum Within a parameter list of a function a 32bit parameter is
	declared with the data type \tok{DWARG}. For Micro-C \tok{DWARG}
	expands to \tok{dword *}, otherwise to \tok{dword}.
\enum 
