A heap is a byte-stream file which is buffered in available memory.
The status word specified when the heap is created is associated with each heap. It is written to when an operation on the heap fails. Each heap is thereby attached to a particular program, namely the program which contains the heap's status word, and is automatically deallocated (unless it has already been explicitly deallocated by a call to CBL_CLOSE_VFILE) when that program is canceled.
A heap is identified by a heap identifier word. This can be passed around between programs so that the heap can be read or written by any program. However, in order to check for failure, the program needs to have access (using a pointer variable, for example, or via normal linkage section mapping) to the associated status word.
Alternatively the RETURN-CODE register can be examined to catch a general heap function failure. The specific error can then be determined by examining the heap status word.
If the read/write succeeds, the RETURN-CODE is zero. If it fails, the RETURN-CODE is nonzero and the heap status first byte contains "9", with detail in the second byte.
The buffer used with CBL_READ_VFILE and CBL_WRITE_VFILE can reside anywhere in the Data or Linkage Section, or it can be dynamically allocated using the CBL_ALLOC_MEM routine.
Each heap is paged, if necessary. A heap is paged into a separate file on disk with name sourcename.Vnn, where sourcename is the base-name of the program to which the heap is attached and nn is an integer from 1 to 99. Once nn reaches 99, the V is overwritten. The maximum number allowed for the extension is 384.
The number of local heaps is configurable, up to 65535.
You can use reference modification in the buffer call parameter to declare the heap buffer in the middle of a COBOL record. This is compiled efficiently provided the length is given as fixed; since the length is ignored by the call interface, you can give it as one.