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 that is processed by that parameter is initialized to the specified value. Otherwise, it remains 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 that contains 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 STOrage ( heap_alloc_value , heap_free_value , dsa_alloc_value , reserve_size )
heap_alloc_value
The initialized value of any heap storage that is allocated by the storage manager. You can specify heap_alloc_value as:
  • A single character that is enclosed in quotation marks. If you specify a single character, every byte of heap storage that is 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. NONE is the default.
heap_free_value
The value of any heap storage that is freed by the storage manager is overwritten. You can specify heap_free_value as:
  • A single character that is 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. NONE is the default.
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 that are allocated outside the Language Environment stack are never initialized.

You can specify dsa_alloc_value as:
  • A single character that is enclosed in quotation marks. If you specify a single character, any dynamically acquired stack storage that is 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. NONE is the default.
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.

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 32 K to support Language Environment condition handling and messaging internal routines as well as the user condition handler. If you are 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 that is 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 quotation mark, double it within the string that is delimited by single quotation marks or surround it with a pair of double quotation marks. Both of the following are correct ways to specify a single quotation mark: 
      STORAGE('''')
  STORAGE("'")
    Similarly, double quotation marks must be doubled within a string that is delimited by double quotation marks, or surrounded by a pair of single quotation marks. 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

The use of the STORAGE runtime option to set values within heap and stack storage can have a negative impact on the performance of a Language Environment application.
  • For applications that use the STORAGE heap_alloc_value to initialize large areas of heap storage, if there are pages of storage that would otherwise have not been referenced, then unnecessary first reference page faults will cause additional overhead.
  • A similar problem can occur with applications that use the STORAGE heap_free_value to set free storage to a given value, since Language Environment will initialize newly-obtained heap segments to this value. This could also cause unnecessary first reference page faults.
  • Performance can also be negatively impacted for applications that use the STORAGE dsa_alloc_value to initialize stack frames, since this requires the runtime to assist on every call to a routine

IBM strongly recommends that you use STORAGE(NONE,NONE,NONE,0K) when you are not debugging, especially with any performance-critical applications. Do not set the STORAGE runtime option to values other than NONE at the system or region level if at all possible, because settings at those levels affect many more programs than might otherwise need it. Instead, use language mechanisms to ensure that automatic variables and data structures, including those contained within COBOL LOCAL-STORAGE and WORKING-STORAGE, are properly initialized.