_xgrab()
 Allocate memory, generating an error if unsuccessful
------------------------------------------------------------------------------
 C Prototype

     #include "fm.api"
     void far * _xgrab(
                        unsigned int uiSize
                      )

 Arguments

     uiSize is the number of bytes to allocate.

 Returns

     _xgrab() returns a pointer to the allocated memory.

 Description

     _xgrab() lets a C or Assembly language function allocate memory from
     CA-Clipper's fixed heap.  If the allocation request is unsuccessful,
     CA-Clipper raises an unrecoverable internal error.  Thus, _xgrab()
     always returns a valid pointer (never NULL).

     Use _xfree() to free memory allocated with _xgrab() after use.

     Warning!  Fixed memory returned from _xgrab() is not cleared by the
     system and is, therefore, in an uninitialized state.

     Note:  In Fm.api, _exmgrab() is defined (using #define) to _xgrab()
     to maintain compatibility with Summer '87.

 Examples

     .  From C:

        char *mem;
        mem = (char)_xgrab(320);

     .  From Assembly language:

        EXTRN __xgrab:FAR
              mov   ax, 320
              push  ax
              call  __xgrab            ; pointer in DX:AX
              add   sp, 2              ; reset stack pointer

 Files  Library is CLIPPER.LIB, header file is Fm.api.