Derivation: HEAP storage CHecKing

HEAPCHK performs diagnostic tests against the user heap.

The default value for non-CICS applications is HEAPCHK(OFF,1,0,0,0,1024,0,1024,0).

The default value for CICS® applications is HEAPCHK(OFF,1,0,0,0,1024,0,1024,0).

The default value for AMODE 64 applications is HEAPCHK(OFF,1,0,0,0,1024,0,1024,0).

Syntax

               .-OFF-.      
>>-HEAPChk--(--+-----+--,--------------------------------------->
               '-ON--'      

>--+-----------+--,--+-------+--,--+------------+--,--+-----------------+-->
   '-frequency-'     '-delay-'     '-call depth-'     '-pool call depth-'   

>--+----------------+--,--+-------------+--,-------------------->
   '-num of entries-'     '-pool number-'      

>--+-------------------+--,--+----------------+--)-------------><
   '-num of entries 31-'     '-pool number 31-'      

OFF

Indicates that no heap checking or tracing is done regardless of the values of the remaining suboptions.

ON

Indicates that heap checking or tracing is activated based on the values of the remaining suboptions.

frequency

The frequency at which the user heap is checked for damage to the heap control information. It is specified as n, nK or nM. A value of one (1) is the default and causes the heap to be checked at each call to a Language Environment heap storage management service. A value of n causes the user heap to be checked at every nth call to a Language Environment heap storage management service. A value of zero results in no check for damage to the user heap.

delay

A value that causes a delay before user heap is checked for damage, and is specified in n, nK or nM. A value of zero (0) is the default and causes the heap checking to begin with the first call to a Language Environment heap storage management service. A value of n causes the heap checking to begin following the nth call to a Language Environment heap storage management service.

call depth

Specifies the depth of calls displayed in the traceback for the heap storage diagnostics report. A value of zero is the default that turns heap storage diagnostics reporting off. The heap storage diagnostics report consists of a set of tracebacks. Each traceback is a snapshot of the stack (to a specified call depth) for each request to obtain user heap storage that has not had a corresponding free request. Use a value of 10 to ensure an adequate call depth is displayed so that you can identify the storage leak.

pool call depth

Specifies the depth of calls in the traceback for each trace entry of a heap pools trace. A value of zero is the default that turns heap pools tracing off. The heap pools trace is an in-core wrapping trace. Each heap pool has a separate trace table. The heap pools trace is only formatted from a system dump using the IPCS verbexit LEDATA. Use a value of 10 to ensure an adequate call depth is displayed so that you can identify the storage leak.

number of entries

Specifies the number of entries to be recorded in one heap pool trace table for the main user heap in the application. Each pool has its own trace table. If the number of entries is 0, the heap pool trace table is not generated.

pool number

Specifies which pools are traced for the main user heap in the application. You can either trace one pool or all pools. The value should be a valid pool number from 1 to 12. If the pool number is 0, all pools will be traced.

number of entries 31

Specifies the number of entries to be recorded in one heap pool trace table when an AMODE 64 application is using heap storage from 31–bit addressable storage (__malloc31()). Each pool has its own trace table. If the number of entries is 0, the heap pool trace table is not generated. This value is only supported in an AMODE64 environment.

pool number 31

Specifies which pools are traced when an AMODE 64 application is using heap storage from 31–bit addressable storage (__malloc31()). You can trace either one pool or all pools. The value should be a valid pool number from 1 to 12. If the pool number is 0, all pools will be traced. This value is only supported in an AMODE64 environment.

Usage notes

• When user heap damage is detected, Language Environment immediately issues an ABEND U4042 RC=0. To obtain a system dump of this abend, either specify TDUMP for the third suboption of the DYNDUMP runtime option or ensure that a SYSMDUMP DD is available.
• If HEAPCHK(ON) is used with STORAGE(,heap_free_value), all free areas of the heap are also checked.
• To request only a heap storage diagnostics report, you must specify a zero for frequency, a zero for pool call depth and a number n greater than zero for call depth. For example (HEAPCHK(ON,0,0,10,0)).
• Under normal termination conditions, if the call depth is greater than zero, the heap storage diagnostics report is written to the CEEDUMP report, independent of the TERMTHDACT setting.
• You can also generate a heap storage diagnostics report by calling CEE3DMP with the BLOCKS option.
• Guideline: Since HEAPCHK does not validate individual cells within a cell pool, you should specify HEAPPOOLS(OFF) when running HEAPCHK to diagnose storage overlays in the heap.
• To request heap pools tracing, set pool call depth to a nonzero value and number of entries (for AMODE 64 applications, number of entries, number of entries 31, or both) to a value. To request only heap pools tracing, in addition, set frequency to zero and call depth to zero. The heap pools trace is only formatted from a system dump using the IPCS verbexit LEDATA.
• For AMODE 64 applications, number of entries and pool number control tracing for the set of heap pools located in storage above the 2-GB bar. Number of entries 31 and pool number 31 control tracing for the set of heap pools located in storage above the 16-MB line and below the 2-GB bar. Pool call depth applies to both sets of heap pools.
• There is no interaction between specifying the HEAPZONES and HEAPCHK runtime options, but setting both at the same time is not recommended by IBM®.

Performance consideration

Specifying HEAPCHK(ON) can result in a performance degradation due to the user heap diagnostic testing that is performed.

For more information

For more information about creating and using the heap storage diagnostics report, see z/OS Language Environment Debugging Guide.