BLIDISFRG        (Clipper Summer'87)
------------------------------------------------------------------------------

  Function : Display Clipper Summer '87 free pool fragmentation

  Syntax   : BLIDISFRG([nuHandle])

  Return   : None

  This function is used to display a summary of Clipper's dynamic memory
  to show the degree of fragmentation, and takes as an optional parameter
  the output destination file handle. Each character position represents
  up to 512 bytes, and adjacent equal characters represent contiguous
  blocks larger than 512 bytes.

  Two memory areas are mapped by this function; the largest area is the
  far heap, often referred to as the FREE POOL, where most of Clipper's
  memory allocations are made, and the near heap, a much smaller block of
  contiguous memory (maximum size 64kb), which Clipper will use if an
  allocation cannot be satisfied from the free pool.

  The * and o characters are used to indicate blocks of free memory which
  are unused by Clipper, and the two graphics characters + and + are used
  to indicate blocks of memory which are in use, i.e. have been allocated.
  The character & is used to indicate the point at which the next memory
  allocation will occur. A key is shown below the memory map.

  The reason for having two different characters for free blocks and two
  different characters for used blocks is to show where a free or used
  area is made up of more than one block of memory. If only one character
  was used for each then the display would not show the full extent of
  fragmentation of memory into very small blocks.

  The relative sizes of blocks are shown by identical repeated characters,
  since a single character indicates a memory block of less than 512
  bytes, and a row of four blocks indicates a memory block of
  approximately 2kb.

  The relative fragmentation is shown by the proportion of free blocks to
  used blocks and by the alternation between free and used blocks
  throughout the display.

  Once free areas are separated by used areas the free areas become
  virtually unusable except for the storage of small temporary values,
  which is why MEMORY(0) gradually deteriorates and operations which
  require larger blocks of memory such as MEMOEDIT() or indexing will then
  fail.

  The BLIDISFRG() function may be used during the execution of an
  application to monitor the fragmentation of memory as execution
  continues. It may also be used to view the improvements gained using the
  BLINKER MEMORY PACK command and the BLIMEMPAK() function.

  Note that the Clipper Summer'87 free pool is allocated from DOS on an
  'as-needed' basis. Unless MEMORY(0), BLIMEMPAK(-1) or BLIMEMBLK() are
  executed (which cause Clipper to allocate all available memory to the
  free pool from DOS), this function will reflect only the currently
  allocated free pool.

  Example  :
  *  Display the memory fragmentation
  *
  BLIDISFRG(4)   && Send to the printer