HEAP

HEAP controls the allocation of user heap storage and specifies how that storage is managed. Heaps are storage areas containing user-controlled dynamically allocated variables or data. Examples of these are:

C data 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
Data allocated as a result of a call to the CEEGTST Language Environment® callable service

The default value for non-CICS applications is HEAP(32K,32K,ANYWHERE,KEEP,8K,4K).

The default value for CICS® applications is HEAP(4K,4080,ANYWHERE,KEEP,4K,4080).


Syntax

                                                .-ANYWHERE-.   
>>-Heap--(--+-----------+--,--+-----------+--,--+----------+---->
            '-init_size-'     '-incr_size-'     +-ANY------+   
                                                '-BELOW----'   

      .-KEEP-.                                        
>--,--+------+--,--+----------+--,--+----------+--)------------><
      '-FREE-'     '-initsz24-'     '-incrsz24-'

init_size: Determines the initial allocation of heap storage. This value can be specified as n, nK, or nM bytes of storage. If 0 is specified, the initial storage is obtained on the first use and is based on the increment size. 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 user heap storage. This value can be specified 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 user heap storage can be allocated anywhere in storage. If there is no available storage above the line, storage is acquired below the 16 MB line.
BELOW: Specifies that user heap storage is allocated below the 16M line in storage. Restriction: The HEAPPOOLS option is ignored when the BELOW suboption is specified.
KEEP: Specifies that an increment to user heap storage is not released when the last of the storage within that increment is freed.
FREE: Specifies that an increment to user heap storage is released when the last of the storage within that increment is freed.
initsz24: Determines the minimum initial size of user heap storage that is obtained below the 16M line for AMODE 24 applications that specify ANYWHERE in the HEAP runtime option. This value can be specified as n, nK, or nM number of bytes. If 0 is specified, the initial storage is obtained on the first use and is based on the increment size. The amount of allocated storage is rounded up to the nearest multiple of 8 bytes.
incrsz24: Determines the minimum size of any subsequent increment to user heap storage that is obtained below the 16M line for AMODE 24 applications that specify ANYWHERE in the HEAP runtime option. This value can be specified as n, nK, or nM number of bytes. The amount of allocated storage is rounded up to the nearest multiple of 8 bytes.

CICS consideration

If HEAP(,,ANYWHERE,,,) is in effect, the maximum size of a heap segment is 1 gigabyte (1024 MB).
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 when the storage allocation is below the 16 MB line.
Guideline: If you choose to change the increment size, you should adjust for the 16 byte CICS storage check zone.

z/OS® UNIX considerations

In a multithreaded environment, user heap storage is shared by all threads in the process.

Usage notes

Applications running in AMODE 24 that request heap storage get the storage below the 16M line regardless of the setting of ANYWHERE | BELOW.
COBOL consideration—You can use the HEAP option to provide function similar to the VS COBOL II space management tuning table.
PL/I consideration—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 runs in AMODE 31.
PL/I MTF consideration—In a PL/I MTF application, HEAP specifies the heap storage allocation and management for a PL/I main task.

Performance consideration

You can improve performance with the HEAP runtime option by specifying values that minimize the number of times the operating system allocates storage. See RPTSTG for information about how to generate a report you can use to determine the optimum values for the HEAP runtime option.

For more information

For more information about Language Environment heap storage, see z/OS Language Environment Programming Guide.
For more information about the CEECRHP callable service, see CEECRHP—Create new additional heap.
For more information about the CEEGTST callable service, see CEEGTST—Get heap storage.
For more information about the RPTSTG runtime option, see RPTSTG .