>>-STORAGE(address-+------------------------+-)----------------><
                   '-,-+--------+-+-------+-'     
                       '-length-' '-,data-'       

STORAGE returns length bytes of data from the specified address in storage. The address is a character string containing the hexadecimal representation of the storage address from which data is retrieved.

The address can be a 31-bit address, represented by 1 to 8 hexadecimal characters. The address can also be a 64-bit address represented by 9 to 17 characters which consists of 8 to 16 hexadecimal characters plus an optional underscore ("_") character separating the high order half and low order half of the 64-bit address. If an "_" is part of the 64-bit address, it must be followed by exactly 8 hexadecimal digits in the low order (or right) half of the 64-bit address.

Optionally, you can specify length, which is the decimal number of bytes to be retrieved from address. The default length is one byte. When length is 0, STORAGE returns a null character string.

If you specify data, STORAGE returns the information from address and then overwrites the storage starting at address with data you specified on the function call. The data is the character string to be stored at address. The length argument has no effect on how much storage is overwritten; the entire data is written.

If the REXX environment under which STORAGE is executing is configured to allow STORAGE to run in read-only mode, then the STORAGE function can be used to read but not alter storage. In this case, do not specify a data argument. If you do specify a new value in the third argument while executing in read-only mode, error message IRX0241I will be issued and the STORAGE function will end in error.

You can use the STORAGE function in REXX execs that run in any MVS™ address space (TSO/E and non-TSO/E).

If the STORAGE function tries to retrieve or change data beyond the storage limit, only the storage up to the limit is retrieved or changed.

Virtual storage addresses may be fetch protected, update protected, or may not be defined as valid addresses to the system. Any particular invocation of the STORAGE function may fail if it references a non-existent address, attempts to retrieve the contents of fetch protected storage, or attempts to update non-existent storage or is attempting to modify store protected storage. In all cases, a null string is returned to the REXX exec.

The STORAGE function returns a null string if any part of the request fails. Because the STORAGE function can both retrieve and update virtual storage at the same time, it is not evident whether the retrieve or update caused the null string to be returned. In addition, a request for retrieving or updating storage of a shorter length might have been successful. When part of a request fails, the failure point is on a decimal 4096 boundary.

Examples:

The following are some examples of using STORAGE:

1. To retrieve 25 bytes of data from address 000AAE35, use the STORAGE function as follows:

   storret = STORAGE(000AAE35,25)

2. To replace the data at address 0035D41F with ‘TSO/E REXX’, use the following STORAGE function:

   storrep = STORAGE(0035D41F,,'TSO/E REXX')

   This example first returns one byte of information found at address 0035D41F and then replaces the data beginning at address 0035D41F with the characters ‘TSO/E REXX’.

   Note: Information is retrieved before it is replaced.
3. Some areas may be accessible to be fetched but not written. That storage can be read as the actual hex data. You can then use the X2D function to then display that hex data in displaceable character format.

   say '<'C2X(STORAGE(10,4))'>'         /* Returns <00FDC248>, perhaps.  This
                                        area in PSA is update protected, but
                                        not fetch protected.  The CVT addr.*/

   Trying to update this same area will fail because address x'10' is a write protected area in PSA at PSA+x'10'.

   say '<'C2X<STORAGE(10,4,'XXXX'))'>'  /* Returns <> (a null string)
                                        because the storage at x'10' is at
                                        PSA+x'10' and is write protected and
                                        cannot be overwritten by STORAGE  */

4. STORAGE can access 31-bit storage (including 24-bit areas), as well as 64-bit storage. The following shows some possible STORAGE addresses, and the resulting binary addresses that is actually accessed by the STORAGE function.

   Table 1. Valid and invalid 31-bit addresses

   Hex Address passed to STORAGE	Binary Address used by STORAGE	Comment
   10	'00000010'x	- Valid 31-bit.
   00000010	'00000010'x	- Valid 31-bit.
   80000010	'00000010'x	- Valid 31-bit. High order sign bit ignored in a 31-bit addr.
   B2BC8DF8	'12BC8DF8'x	- Valid 31-bit addr. High-order sign bit ignored in a 31-bit addr.
   200EF00	'0200EF00'x	- Valid 31-bit addr.

   Table 2. Valid and invalid 64-bit addresses

   Hex Address passed to STORAGE	Binary Address used by STORAGE	Comment
   _00000010	'0000000000000010'x	- Valid 64-bit addr. (Padded to left with 0's to 64-bits.) Addresses same area as 31-bit '00000010'x addr.
   0_00000010	'0000000000000010'x	- Valid 64-bit addr. Addresses same area as _00000010.
   0_80000010	'0000000080000010'x	- Valid 64-bit addr. Addr is 2GB beyond the 0_00000010 addr..
   000001EF10	'000000000001EF10'x	- Valid 64-bit addr.
   1EF_80000010	'000001EF80000010'x	- Valid 64-bit addr.
   1EF80000010	'000001EF80000010'x	- Valid 64-bit addr without "_" separator.
   000001EF_80000010	'000001EF80000000'x	- Valid 64-bit addr.
   000001EF_10	Invalid Addr	- Right half of 64-bit addr <8 chars.
   00000001EF_000010	Invalid Addr	- Left hald of addr >8 chars, right half <8 chars.
   0000001EF_000001000	Invalid Addr	- More than 16 hex chars.
   Note: As an example of what you might expect, consider STORAGE used to retrieve 24 bytes from a 64-bit addressable area: say '<'C2X(STORAGE(1ef_80000010,25))'>' /* Returns ... <IARST64 COMM SIZE 000512 > perhaps */