STORAGEX

Syntax:

STORAGEX(address[,length][,data])

Arguments:

address: a character string describing the starting address to be queried or modified. See "Specifying the Address" below for the exact syntax of this argument.
length: a REXX printable integer from 0 to 231-1 describing the number of bytes of storage to retrieve. If zero is specified no storage locations are retrieved or modified. If neither length nor data are specified (i.e., storage is to be retrieved only), a default length value of 1 is used. If data is specified, its length is the controlling length and the value of length, if specified, is ignored.
data: the data to store at the storage location identified by address. The entire length of data is stored, regardless of the value specified for length.

Module Name:

SWXSTORX

Service Description:

The STORAGEX function is used to retrieve and modify storage. If successful, STORAGEX always first retrieves the storage located at address. In addition, if data is specified, the storage locations starting at address are replaced with the bytes of data. If data is not specified no storage locations are modified.

WARNING: Use the storage modification function of STORAGEX with great care. Modification of certain REXX control blocks may make further execution in your address space impossible. Please note though, that STORAGEX cannot modify protected key storage or storage in another user's address space. It can only modify storage that could be modified by any problem-state program written in PL/I, COBOL, or assembler.

Specifying the Address:

The address argument of the STORAGEX function utilizes an indirect address notation. The following definitions are essential to understanding the notation:

current location: is the virtual address described by the address expression up to the current operator. The address argument is assumed to start at virtual address zero.
current operator: is the most recently parsed operator. The address argument is assumed to start with the plus operator.

The syntax of address is as follows:

addr-expr [{+|-}addr-expr...]

Where addr-expr is one of the following:

hex-off: a one to 8 character printable hexadecimal offset, identifying the location of the data. The offset is added to or subtracted from the current location using the current operator.
hex-off%: a one to 8 character printable hexadecimal offset, followed by a percent sign. The offset is added to or subtracted from the current location using the current operator. After this the current location is replaced with the address pointed to by the current location using 24 bit addressing (the low-order 3 bytes of the current location are used).
hex-off?: a one to 8 character printable hexadecimal offset, followed by a question mark. The offset is added to or subtracted from the current location using the current operator. After this the current location is replaced with the address pointed to by the current location using 31 bit addressing.
dec-offN: a one to 10 digit printable integer offset, identifying the location of the data. The number must immediately be followed with the letter "N". The offset is added to or subtracted from the current location using the current operator.
dec-offN%: a one to 10 digit printable integer offset, followed by the letter "N" and a percent sign. The offset is added to or subtracted from the current location using the current operator. After this the current location is replaced with the address pointed to by the current location using 24 bit addressing (the low- order 3 bytes of the current location are used).
dec-offN?: a one to 10 digit printable integer offset, followed by the letter "N" and a question mark. The offset is added to or subtracted from the current location using the current operator. After this the current location is replaced with the address pointed to by the current location using 31 bit addressing.

Returned Information:

The STORAGEX function returns the storage located at address. If you CALL the STORAGEX function, the returned value is contained in the RESULT special variable. The $SWXSGAD special variable contains the printable hex address of the storage location identified by address. The RC special variable is set to contain the STORAGEX return code.

The following STORAGEX RC values are possible:

0: The operation was successful.
4: A zero length was specified. No storage was retrieved or modified.
8: The address argument was in error. Either the syntax of the argument was incorrect, or one of the storage locations traversed was not accessible. Usually a message describing the problem accompanies this return code.
12: Storage retrieval/modification protection exception. Usually a message describing the problem accompanies this return code.
16: Storage modification not allowed. The current REXX environment's STORFL flag indicates that STORAGE processing is not allowed.

Examples:

Get the system SMF ID:

data = storagex('10?+c4?+10', 4)
say c2x(data)    '>'data'<'

Get the REXX Parmblock eyecatcher:

data = storagex('224%+6c?+20n%+20?+30?+16n?', 8)
say c2x(data)    '>'data'<'

Modify the storage located 4 bytes from the base address given in the variable BASE:
```
olddata = storagex(base'+4', ,'New data string')
```