HEAP

HEAP controls the allocation of the initial heap, controls allocation of additional heaps created with the CEECRHP callable service, and specifies how that storage is managed.

Heaps are storage areas where you allocate memory for user-controlled dynamically allocated variables such as:

C variables allocated as a result of the malloc(), calloc(), and realloc() functions
COBOL WORKING-STORAGE data items
PL/I variables with the storage class CONTROLLED, or the storage class BASED

The HEAP option is always in effect. If you do not specify HEAP, Language Environment allocates the default value of heap storage when a call is made to get heap storage.

Language Environment does not allocate heap storage until the first call to get heap storage is made. You can get heap storage by using language constructs or by making a call to CEEGTST.

Non-CICS default: HEAP=((32K,32K,ANYWHERE,KEEP,8K,4K),OVR)
CICS® default: HEAP=((4K,4080,ANYWHERE,KEEP,4K,4080),OVR)

init_size

Determines the minimum initial allocation of heap storage. Specify this value as n, nK, or nM bytes of storage. The actual amount of allocated storage is rounded up to the nearest multiple of 8 bytes.

incr_size

Determines the minimum size of any subsequent increment to the heap storage. Specify this value as n, nK, or nM bytes of storage. The actual amount of allocated storage is rounded up to the nearest multiple of 8 bytes.

ANYWHERE|ANY

Specifies that you can allocate heap storage anywhere in storage. If there is no available storage above the line, storage is acquired below the 16 MB line.

The only valid abbreviation of ANYWHERE is ANY.

ANYWHERE is the default.

BELOW

Specifies that you must allocate heap storage below the 16-MB line in storage that is accessible to 24-bit addressing.

KEEP

Specifies that storage that is allocated to HEAP increments is not released when the last of the storage is freed. KEEP is the default.

FREE

Specifies that storage that is allocated to HEAP increments is released when the last of the storage is freed.

initsz24

Determines the minimum initial size of the heap storage that is obtained when an application that is running AMODE 24 (ALL31(OFF)) requests storage and ANYWHERE wa specified. An AMODE 31 application running with ALL31(OFF) uses the regular heap allocation size. Specify initsz24 as n, nK, or nM number of bytes. The amount of storage is rounded up to the nearest multiple of 8 bytes.

initsz24 applies to the initial heap and other with the CEECRHP callable service that are not allocated strictly below the 16-MB line.

incrsz24

Determines the minimum size of any subsequent increment to the heap area that is obtained when an application running AMODE 24 (ALL31(OFF)) requests storage and ANYWHERE was specified. An AMODE 31 application that is running with ALL31(OFF) uses the regular heap allocation size. Specify incrsz24 as n, nK, or nM number of bytes. The amount of storage is rounded up to the nearest multiple of 8 bytes.

The incrsz24 applies to the initial heap and other heaps created with the CEECRHP callable service that are not allocated strictly below the 16-MB line.

OVR

Specifies that the option can be overridden. OVR is the default.

NONOVR

Specifies that the option cannot be overridden.

CICS considerations

Both the initial HEAP allocation and HEAP increments are rounded to the next higher multiple of 8 bytes (not 4K bytes). If HEAP(0) is specified the initial HEAP is obtained on the first use and will be based on the increment size.

If HEAP(,,ANYWHERE,,,) is in effect, the maximum size of a heap segment is 1 gigabyte (1024 MB). These restrictions are subject to change from one release of CICS to another.

The default increment size under CICS is 4080 bytes, rather than 4096 bytes, to accommodate the 16 bytes CICS storage check zone. Without this accommodation, an extra page of storage is allocated (only when the storage allocation is below the 16 MB line).

z/OS® UNIX considerations

The HEAP option applies to the enclave.

Under z/OS UNIX, heap storage is managed at the thread level using pthread_key_create, pthread_setspecific, and pthread_getspecific.

Usage notes

Applications running in AMODE 24 that request heap storage get the storage below the 16 MB line regardless of the setting of ANYWHERE | BELOW.
For PL/I, the only case in which storage is allocated above the line is when all of the following conditions exist:
- The user routine requesting the storage is running in 31-bit addressing mode.
- HEAP(,,ANY,,,) is in effect.
- The main routine is AMODE 31.
AMODE(31) and RMODE(31) are the default settings for Enterprise PL/I applications. To run an application in AMODE(24) you must:
1. Compile all PL/I source with the compiler option NORENT
2. Link with the SIBMAM24 data set concatenated in front of the SCEELKED data set
3. Run with the Language Environment runtime option ALL31(OFF),HEAP(,,BELOW,,,) and STACK(,,BELOW,,,)

COBOL considerations: You can use the HEAP option to provide function similar to the VS COBOL II space management tuning table.
PL/I MTF considerations: In a PL/I MTF application, HEAP specifies the heap storage allocation and management for a PL/I main task.

Performance considerations

To improve performance, use the storage report numbers that are generated by the RPTSTG runtime option as an aid in setting the initial and increment size for HEAP.

For more information

See z/OS Language Environment Programming Guide for more information about Language Environment heap storage or about specifying runtime options at application invocation.
For more information about the CEECRHP callable service, or the CEEGTST callable service, see z/OS Language Environment Programming Reference.
See RPTSTG for more information about the RPTSTG runtime option.