STORAGE

The STORAGE command allows the acquisition of system storage that can be used in place of variables for parameters to REXXTDLI and REXXIMS calls.

Format

Read syntax diagramSkip visual syntax diagramSTORAGEOBTAIN!tokenlengthKEEPBELOWRELEASE!token
Call Name DB/DC DBCTL DCCTL DB Batch TM Batch
STORAGE X X X X X

Usage

Although REXX allows variables to start with characters (!) and (#), these characters have special meanings on some commands. When using the REXXTDLI interface, you must not use these characters as the starting characters of variables.

The !token variable name identifies the storage, and it consists of an exclamation mark followed by a 1- to 16-character case-independent token name. The length variable name is a number or variable containing size in decimal to OBTAIN in the range 4 to 16777216 bytes (16 MB). The storage class has two possible override values, BELOW and KEEP, of which only one can be specified for any particular token. The BELOW function acquires the private storage below the 16 MB line. The KEEP function marks the token to be kept after this EXEC is terminated. The default action gets the storage in any location and frees the token when the EXEC is terminated.

Use the STORAGE command to get storage to use on DL/I calls when the I/O area must remain in a fixed location (for example, Spool API) or when it is not desirable to have the LLZZ processing. Once a token is allocated, you can use it in REXXTDLI DL/I calls or on the STORAGE RELEASE command.

When using STORAGE:

  • When used on DL/I calls, none of the setup for LLZZ fields takes place. You must fill the token in and parse the results from it just as required by a non-REXX application.
  • You cannot specify both KEEP and BELOW on a single STORAGE command.
  • The RELEASE function is only necessary for tokens marked KEEP. All tokens not marked KEEP and not explicitly released by the time the EXEC ends are released automatically by the IMS adapter for REXX.
  • When you use OBTAIN, the entire storage block is initialized to 0.
  • The starting address of the storage received is always on the boundary of a double word.
  • You cannot re-obtain a token until RELEASE is used or the EXEC that obtained it, non-KEEP, terminates. If you try, a return code of -9 is given and the error message DFS3169 is issued.
  • When KEEP is specified for the storage token, it can be accessed again when this EXEC or another EXEC knowing the token's name is started in the same IMS region.
  • Tokens marked KEEP are not retained when an ABEND occurs or some other incident occurs that causes region storage to be cleared. It is simple to check if the block exists on entry with the IMSQUERY(!token) function.

Example

This example shows how to use the STORAGE command with Spool API. 
/* Get 4K Buffer below the line for Spool API Usage */
Address REXXIMS 'STORAGE OBTAIN !MYTOKEN 4096 BELOW'
/* Get Address and length (if curious) */
Parse Value IMSQUERY('!MYTOKEN') With My_Token_Addr My_Token_Len.
Address REXXIMS 'SETO ALTPCB !MYTOKEN SETOPARMS SETOFB'
⋮ 
Address REXXIMS 'STORAGE RELEASE !MYTOKEN'