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 run-time 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.

Non-CICS default

STORAGE=((NONE,NONE,NONE,0K),OVR)

CICS® default

STORAGE=((NONE,NONE,NONE,0K),OVR)

Amode 64 default

STORAGE=((NONE,NONE,NONE,),OVR)

Syntax

>>-STORAGE--=--(--(--heap_alloc_value--,--heap_free_value--,---->

                                           .-OVR----.      
>--dsa_alloc_value--,--reserve_size--)--,--+-NONOVR-+--)-------><

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'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 dynamically acquired storage that is composed of a standard register save area and the area available for automatic storage.

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'C1'. A dsa_alloc_value of 'F' initializes stack storage to X'C6', 'd' to X'84'.
• Two hex digits without quotation marks. 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'FE'. A dsa_alloc_value of 00 initializes stack storage to X'00', FF to X'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 suboption is ignored for AMODE 64 applications.

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 reserve_size as 0, 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 1004.

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 KB to support Language Environment condition handling and messaging internal routines as well as the user condition handler. When the reserve stack is used in a multithreaded environment, it is suggested that the ALL31(ON) and STACK(,,ANY,,,) options also be in effect.

If unsuccessful, Language Environment temporarily adds the reserve stack segment to the overflowing stack, and signals the out-of-storage condition. This causes a user-written condition handler to gain control and release storage. If the reserve stack segment overflows while this is happening, Language Environment terminates with abend 4088 and reason code of 1004.

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

OVR

Specifies that the option can be overridden.

NONOVR

Specifies that the option cannot be overridden.

CICS considerations

• The out-of-storage condition is not raised under CICS. Therefore, the reserve stack size (fourth suboption) is ignored under CICS and displays as 0 in all options reports

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 behavior of the dsa_alloc_value suboption of the STORAGE runtime option is different for an XPLINK stack. The DSA is only initialized for routines that perform an explicit check for stack overflow. (For C/C++, the compiler option XPLINK(NOGUARD) can be used to force the compiler to generate prologs with explicit checks for stack overflow.)
• 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 delimited by single quotation mark or surround it with a pair of double quotation marks. Both of the following examples are correct ways to specify a single quotation mark:

    STORAGE('''')
    STORAGE("'")

  Similarly, double quotation marks must be doubled within a string 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.
• If the initial stack segment is too small to contain the main procedure, it is allocated from the stack increment, and is not be cleared even if the CLEAR option is specified.
• 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. If a small initial stack segment size is specified, the DSA of the main procedure can be allocated in the stack increment, not in the initial stack segment. In this case, the variables of the main procedure cannot be initialized to binary zeros because they are in the stack increment, not the initial stack. To prevent this, the size of the initial stack segment needs to be increased.

COBOL considerations

If you are using WSCLEAR in VS COBOL II, STORAGE(00,NONE,NONE,0K) is recommended.

Performance considerations

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.

Use STORAGE(NONE,NONE,NONE,0K) when you are not debugging.