|
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).
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.
|