STACK

STACK controls the allocation of the thread's stack storage for both the upward and downward- growing stacks. Typical items residing in the upward-growing stack are C or PL/I automatic variables, COBOL LOCAL-STORAGE data items, and work areas for runtime library routines. The downward-growing stack is allocated only in an XPLINK environment.

The default value for non-CICS® applications is STACK(128K,128K,ANYWHERE,KEEP,512K,128K).

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

Read syntax diagramSkip visual syntax diagram STACk ( usinit_size , usincr_size , ANYWHEREANYBELOW , KEEPFREE , dsinit_size , dsincr_size )
usinit_size
Determines the initial allocation of the upward-growing stack 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.

usinit_size can be preceded by a minus sign. In environments other than CICS, if you specify a negative number Language Environment® uses all available storage minus the amount specified for the initial stack storage.

A size of "0" or "-0" requests half of the largest block of contiguous storage in the region below the 16-MB line.

usincr_size
Determines the minimum size of any subsequent increment to the upward-growing stack storage. This value can be specified as n, nK, or nM bytes of storage. The actual amount of allocated storage is the larger of two values— usincr_size or the requested size—rounded up to the nearest multiple of 8 bytes.

If you specify usincr_size as 0, only the amount of the storage needed at the time of the request, rounded up to the nearest multiple of 8 bytes, is obtained.

The requested size is the amount of storage a routine needs for a stack frame.

In the following example:
  • usincr_size is specified as 8K
  • The requested size is 9000 bytes
  • The currently allocated stack storage has less than 9000 bytes available
As a result, Language Environment allocates enough storage to hold the 9000 byte request.

If the requested size is smaller than 8K, Language Environment allocates 8K of stack storage.

ANYWHERE|ANY
Specifies that stack storage can be allocated anywhere in storage. If there is no available storage above the line, storage is acquired below the 16 MB line.

ANYWHERE is the default.

BELOW
Specifies that stack storage is allocated below the 16M line in storage.
KEEP
Specifies that an increment to stack storage is not released when the last of the storage within that increment is freed.

KEEP is the default.

FREE
Specifies that an increment to stack storage is released when the last of the storage within that increment is freed.
dsinit_size
Determines the initial allocation of the downward-growing stack 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 16 bytes.
dsincr_size
Determines the minimum size of any subsequent increment to the downward-growing stack storage. This value can be specified as n, nK, or nM bytes of storage. The actual amount of allocated storage is the larger of two values— dsincr_size or the requested size—rounded up to the nearest multiple of 16 bytes.

CICS consideration

  • dsinit_size and dsincr_size suboptions are ignored under CICS.
  • The maximum initial and increment size for CICS above 16 MB is 1 gigabyte (1024 MB).
  • The minimum for the initial size is 4K.
  • STACK(0), STACK (-0), and STACK (-n) are all interpreted as STACK(4K) under CICS.
  • 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.

z/OS® UNIX considerations

  • The STACK option specifies the characteristics of the user stack for the initial thread. In particular, it gets the initial size of the user stack for the initial thread. The characteristics that indicate incr_size, ANYWHERE, and KEEP | FREE apply to any thread created using pthread_create. Language Environment gets the initial stack size from the threads attribute object specified in the pthread_create function. The default size to be set in the thread's attribute object is obtained from the initial size of the STACK runtime option.
  • The default setting for STACK under z/OS UNIX is STACK=(12K,12K,ANYWHERE,KEEP,512K,128K).

Usage notes

  • Applications running with ALL31(OFF) must specify STACK(,,BELOW,,,) to ensure that stack storage is addressable by the application.
  • When an application is running in an XPLINK environment, the STACK runtime option is forced to STACK(,,ANY,,,). Only the third suboption of the STACK runtime option is changed by this action, to indicate that stack storage can be allocated anywhere in storage. No message is issued to indicate this action. In this case, if a Language Environment runtime options report is generated using the RPTOPTS runtime option, the STACK option will be reported as "Override" under the LAST WHERE SET column.
  • If the initial routine of the Language Environment application is AMODE 24, the STACK runtime option is forced to STACK(,,BELOW). Only the third suboption of the STACK runtime option is changed by this action. No message is issued to indicate this action. However, if a Language Environment runtime options report is generated using the RPTOPTS runtime option, the STACK option is reported as "Override" under the LAST WHERE SET column.
  • The dsinit_size and dsincr_size values are not the actual amounts of storage obtained. The actual size of the storage obtained is 4K larger (8K if a 4K page alignment cannot be guaranteed) to accommodate the guard page.
  • PL/I consideration—PL/I automatic storage above the 16-MB line is supported under control of the Language Environment STACK option. When the Language Environment stack is above, PL/I temporaries (dummy arguments) and parameter lists (for reentrant/recursive blocks) also reside above.

    The stack frame size for an individual block is constrained to 16 MB. Stack frame extensions are also constrained to 16 MB. Therefore, the size of an automatic aggregate, temporary variable, or dummy argument cannot exceed 16 MB. Violation of this constraint might have unpredictable results.

    If an OS PL/I application does not contain any edited stream I/O and if it is running with AMODE 31, you can relink it with Language Environment to use STACK(,,ANY,,,). Doing so is particularly useful under CICS to help relieve below-the-line storage constraints.

  • PL/I MTF consideration—The STACK option allocates and manages stack storage for the PL/I main task only.

Performance consideration

You can improve performance with the STACK 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 STACK runtime option.

For more information

  • See ALL31 for more information about the ALL31 runtime option.
  • See RPTSTG for more information about the RPTSTG runtime option.
  • See XPLINK for more information about the XPLINK runtime option.