Advanced Topic: FORCE's memory allocation routines

        Author: David Holmes

        Assumed Knowledge:
                I'm going to assume that you know what pointers are and
        hopefully you've at one point or another used functions like
        C's malloc(), or new() in Pascal or C++.

        Examples: Fsort, iCopy, Heap library

        General discussion and easy FAQ answers:
        -----------------------------------------------------------------
        Q:      Ack!  I heard someone talking about FORCE's malloc()
                function, but I can't find it anywhere!

        A:      That's because this is one of FORCE's internal routines.
        Actually, it's not even that.  malloc(), calloc(), realloc(),
        free(), and some other routines were added to the FORCE library
        when FORCE was made compatible with the Microsoft and Borland C
        libraries.  They weren't really intended to be called from FORCE
        functions, because they deal with pointers, and pointers can be
        difficult to use in FORCE.

                I've provided a header file called ALLOC.HDR that gives
        the FORCE prototypes for malloc(), calloc() etc, but stay with me,
        because there are some things that you'll need to know before you
        start dynamically allocating FORCE memory.

                FORCE has several internal memory handling routines that
        were designed to be called from other assembly language routines.
        In order to get C functions that called the standard C memory
        routines to work with FORCE, several functions were designed as
        "wrappers" around the FORCE internal routines.  Some work, and
        some are just for show, having no real equivalent in FORCE.

                For example, the malloc() routine does nothing more than
        convert the given number of bytes into paragraphs, and then
        calls the internal function _$allocate with service 1.  Then it
        returns the pointer to the memory (don't try this yourself).
        The free() routine is even simpler.  It just passes the memory
        pointer to a function called _$deallocate and let's it deal
        with freeing the memory (don't try that yourself either).

                However, there are some differences between the FORCE
        allocation functions and their C equivalents.  First and
        foremost, if you call either malloc() or calloc() and there is
        not enough memory to fulfill your request, you will get error
        #275 (memory chain destroyed) if you're lucky, or most likely
        your computer will just lock up.  There's another function
        called realloc() which looks like it should work correctly,
        but I've had so much difficulty with it that I've removed it
        from there header file.


                Because of these problems, I've written two functions
        called alloc() and kalloc() which replace malloc() and calloc().
        They are exactly like their counterparts except that they check
        the free memory before calling the FORCE internal memory
        functions.  You'll find them in the header file, and the library,
        object code, and the source code will be included with this
        special edition of the FAQ.  Also included is another function
        called mavail() which returns the available memory.

        Final Comments:
        ------------------------------------------------------------------
        You'll find that the FORCE memory handling routines can finally
        give you that last little bit of control that you always wanted
        from FORCE... if you're willing to work a little harder to get
        it.  If you're a hardcore FORCE fan (and if you've read this
        far you must be), I'd suggest writing your own toolkits like
        the heap library, which not only shows you how to fake pointers,
        it shows you how to fake structures and pointers to pointers.
        You can then have your toolkits deal with the pointers approp-
        riately so that you won't have to worry about it.

                Once you have your toolkits, you'll speed up your
        application development tenfold.