Set a callback function for handling HEAP errors. For the memory HEAP, this is limited to failure to allocate a new memory with the MemNew macro.

A custom handler provides options other than terminating the program. It can be used ti simply return a NULL pointer if allocation fails. Or, perform cache like behaviour by releasing old memory and retrying the allocation.

When the custom handler is called, the following information is provided:

• ds = code segment
• bx = offset to memory controller data block
• dx:ax = amount of memory requested rounded up to a full paragraph.

On return from the custom error handler, the direction flag must remain cleared and all registers (except BX) must be preserved.

Return values for BX:

• bx = 1, return nil & carry flag to caller
• bx = 2, retry allocation
• bx = anything else, terminate program

Example:

    MemError HEAP_ERR  ; set memory allocation failure routine

See also: MemNew, MemFree and MemAvail.