z/TPF - Group home

PJ45598 – Recoverable system heap support

By Colton Cox posted Thu March 12, 2020 08:16 PM


Recoverable system heap is a new system heap area where contents are maintained across most IPLs. 


Data in the recoverable system heap area survives an IPL unless one of the following conditions occurs:

  • A hard IPL with clear is done.
  • A memory configuration change happens during the IPL.
  • The z/TPF system is IPLed on another machine.


With recoverable system heap support applied, there are the following system heap areas in the z/TPF system.

  • 31-bit system heap
    • Resides below 2 GB in memory.
    • The size is determined by remaining unmapped memory below 2 GB.  A required minimum size is defined by the SHP parameter on the ZCTKA command or in SIP CORREQ.
    • The memory area is backed by 1 MB frames when needed.
    • Data is lost when the system is IPLed.
  • 64-bit system heap
    • Resides above 4 GB.
    • There are two areas:
      • A preallocated area can be used.  The size is defined by the SHA parameter on command ZCTKA or in SIP CORREQ.
      • A virtual memory area exists that is backed by 1 MB frames.
    • Data is lost when the system is IPLed.
  • Recoverable system heap
    • Resides above 4 GB.
    • Memory is in a preallocated area.  The size is defined by the RSH parameter on command ZCTKA or in SIP CORREQ.
    • Data is recovered across most IPLs.


Recoverable system heap is intended to hold large data areas and caches.  If it takes a large amount of I/O or processing to re-create the data areas following an IPL, these data areas should be in recoverable system heap.


New APIs have been created to manage recoverable system heap.  The APIs are SHEAPC for assembler programs and tpf_sheapc() for C programs.  Recoverable system heap buffers can only be managed (get, release, and find) by using the SHEAPC or tpf_sheapc() API.  In addition, SHEAPC or tpf_sheapc() can be used to manage buffers in the 31-bit system heap and 64-bit system heap areas.  One key requirement for the SHEAPC and tpf_sheapc() APIs are that a unique token must be provided.  The unique token must be a character string that can be up to 64 characters.


Having a system heap area that survives an IPL creates new management challenges such as fragmentation and memory leaks (a.k.a. orphaned buffers).  The ZMRSH command was created to help manage these challenges.


Recoverable system heap is allocated and used when PJ45598 is installed.  A minimum of 10 MB of recoverable system heap must be allocated.  A CCCPSE internal trace table is allocated in recoverable system heap so that dump information can survive a catastrophic dump.


For more information, see APAR PJ45598.