STORAGE

STORAGE controls the initial content of storage when allocated and freed. It also controls the amount of storage that is reserved for the out-of-storage condition. If you specify one of the parameters in the STORAGE runtime option, all allocated storage processed by that parameter is initialized to the specified value. Otherwise, it is left uninitialized. You can use the STORAGE option to identify uninitialized application variables, or prevent the accidental use of previously freed storage. STORAGE is also useful in data security. For example, storage containing sensitive data can be cleared when it is freed.

The default value for non-CICS applications is STORAGE(NONE,NONE,NONE,0K).

The default value for CICS® applications is STORAGE(NONE,NONE,NONE,0K).

The default value for AMODE 64 applications is STORAGE(NONE,NONE,NONE).

Read syntax diagramSkip visual syntax diagram
Syntax

>>-STOrage--(--+------------------+--,--+-----------------+----->
               '-heap_alloc_value-'     '-heap_free_value-'   

>--,--+-----------------+--,--+--------------+--)--------------><
      '-dsa_alloc_value-'     '-reserve_size-'      
heap_alloc_value
The initialized value of any heap storage allocated by the storage manager. You can specify heap_alloc_value as:
  • A single character enclosed in quotation marks. If you specify a single character, every byte of heap storage allocated by the storage manager is initialized to that character's EBCDIC equivalent. For example, if you specify a as the heap_alloc_value, heap storage is initialized to X'818181...81' or aaa...a.
  • Two hex digits without quotation marks. If you specify two hex digits, every byte of the allocated heap storage is initialized to that value. For example, if you specify FE as the heap_alloc_value, heap storage is initialized to X'FEFEFE...FE'. A heap_alloc_value of 00 initializes heap storage to X'0000...00'.
  • NONE If you specify NONE, the allocated heap storage is not initialized.
heap_free_value
The value of any heap storage freed by the storage manager is overwritten. You can specify heap_free_value as:
  • A single character enclosed in quotation marks. For example, a heap_free_value of 'f' overwrites freed heap storage to X'868686...86'; 'B' overwrites freed heap storage to X'C2C2C2...C2'.
  • Two hex digits without quotation marks. A heap_free_value of FE overwrites freed heap storage with X'FEFEFE...FE'.
  • NONE If you specify NONE, the freed heap storage is not initialized.
dsa_alloc_value
The initialized value of stack frames from the Language Environment stack. A stack frame is storage that was acquired dynamically and is composed of a standard register save area and the area available for automatic storage. The dsa_alloc_value has no effect on the XPLINK or AMODE 64 downwards growing stack.

If specified, all Language Environment stack storage, including automatic variable storage, is initialized to dsa_alloc_value. Stack frames allocated outside the Language Environment stack are never initialized.

You can specify dsa_alloc_value as:
  • A single character enclosed in quotation marks. If you specify a single character, any dynamically acquired stack storage allocated by the storage manager is initialized to that character's EBCDIC equivalent. For example, if you specify 'A' as the dsa_alloc_value, stack storage is initialized to X'C1C1C1...C1'. A dsa_alloc_value of 'F' initializes stack storage to X'C6C6C6...C6', 'd' to X'848484...84'.
  • Two hex digits without quotations. If you specify two hex digits, any dynamically-acquired stack storage is initialized to that value. For example, if you specify FE as the dsa_alloc_value, stack storage is initialized to X'FEFEFE...FE'. A dsa_alloc_value of 00 initializes stack storage to X'00', FF to X'FFFFFF...FF'.
  • CLEAR If you specify CLEAR, any unused portion of the initial upward growing stack segment is initialized to binary zeros, just before the main procedure gains control. This value has no effect on any stack increments or on the XPLINK or AMODE 64 downward growing stack.
  • NONE If you specify NONE, the stack storage is not initialized.
reserve_size
The amount of storage for the Language Environment storage manager to reserve in the event of an out-of-storage condition. You can specify the reserve_size value as n, nK, or nM bytes of storage. The amount of storage is rounded to the nearest multiple of 8 bytes.

Restriction: This option is ignored in a 64–bit environment.

If you specify reserve_size as 0, no reserve segment is allocated. The default reserve_size is 0, so no reserve segment is allocated. If you do not specify a reserve segment and your application exhausts storage, the application terminates with abend 4088 and a reason code of 1024.

If you specify a reserve_size that is greater than 0 on a non-CICS system, Language Environment does not immediately abend when your application runs out of storage. Instead, when the stack overflows, Language Environment uses the reserve stack as the new segment and signals a CEE0PD out of storage condition. This allows a user-written condition handler to gain control for this signal and release storage. If the reserve stack segment overflows while this is happening, Language Environment® terminates with abend 4088 and reason code of 1004. The reserve stack segment is not freed until thread termination. It is acquired from 31-bit storage if the STACK(,,ANY,,,) runtime option is set or 24-bit storage when STACK(,,BELOW,,,) is requested. If a determination is made to activate the reserve stack, the reserve size should be set to a minimum of 32K to support Language Environment condition handling and messaging internal routines as well as the user condition handler. When using the reserve stack in a multithreaded environment, it is recommended that the ALL31(ON) and STACK(,,ANY,,,) options also be in effect.

To avoid such an overflow, increase the size of the reserve stack segment with the STORAGE(,,,reserve_size) runtime option. The reserve stack segment is not freed until thread termination.

CICS consideration

The out-of-storage condition is not raised under CICS.

z/OS® UNIX considerations

A reserve stack of the size specified by the reserve_size suboption of STORAGE is allocated for each thread.

Usage notes

  • The heap_alloc_value, heap_free_value, and dsa_alloc_value can all be enclosed in quotation marks. To initialize heap storage to the EBCDIC equivalent of a single quote, double it within the string delimited by single quotes or surround it with a pair of double quotation marks. Both of the following are correct ways to specify a single quote: 
      STORAGE('''')
  STORAGE("'")
    Similarly, double quotation marks must be doubled within a string delimited by double quotation marks, or surrounded by a pair of single quotes. The following are correct ways to specify a double quotation mark: 
      STORAGE("""")
  STORAGE('"')
  • CLEAR is not a valid option for AMODE 64 applications.
  • COBOL consideration—If using WSCLEAR in VS COBOL II, STORAGE(00,NONE,NONE,8K) is recommended.

Performance considerations

  • Use STORAGE(NONE,NONE,NONE) when you are not debugging.
  • Using STORAGE to control initial values can increase program runtime. If you specify a dsa_alloc_value, performance is likely to be poor. Therefore, use the dsa_alloc_value option only for debugging, not to initialize automatic variables or data structures.
  • You should not use STORAGE(,,00) in any performance-critical application.
Parent topic: Using the Language Environment runtime options