Read and write operations for expanded storage only hiperspaces

The system backs ESO hiperspaces with expanded storage, a finite resource that many programs compete for. Because an ESO hiperspace is backed with expanded storage, it can be accessed very quickly. However, because of the contention for expanded storage, the data in the hiperspace might not be there when you need it. Because of this uncertainty, your program must have an alternate way to retrieve or recreate the data.

HSPSERV CREAD transfers data from a source location in an ESO hiperspace to an address space. If all blocks requested are available in the hiperspace (that is, are backed by expanded storage) then the system performs the read operation. However, if one or more blocks to be read are no longer available in the hiperspace, then the system rejects the request and returns a failing return code. If the HSPSERV CREAD is successful, the system moves the data to the buffer area in your address space and preserves the data in the source area of the hiperspace, when possible.

HSPSERV CWRITE transfers data from a source location in an address space to a hiperspace. If the system is unable to write all the requested blocks to the hiperspace (because of a shortage of expanded storage), then it rejects the request. In this case, the data in the target area of the hiperspace is volatile. After the system rejects a HSPSERV CWRITE request, do not issue HSPSERV CREAD using that target area as the source for the CREAD until you have successfully completed a HSPSERV CWRITE to the same area.

You can request that the system preserve the source data in the address space after it successfully completes the HSPSERV CWRITE operation. If your program will use this same source data again, specify KEEP=YES on HSPSERV (or use the default). KEEP=NO tells the system that you will not be using the source data again. In this case, the system can reuse the pages that back the address space buffer area. In most cases, KEEP=NO gives your program better performance than KEEP=YES.

To use the HSPSERV macro for an ESO hiperspace, the buffer area that is the source of the CWRITE and the target of the CREAD can be in the caller's home address space as well as the caller's primary address space or the common storage area (CSA). This flexibility means that the caller can use the HSPSERV macro while in cross memory mode (that is, where PASN is not equal to HASN).

The following example shows a program transferring data to and from an ESO hiperspace. The address space has one buffer area to receive the hiperspace data. For an example of storing information into the range list, see Example of creating a standard hiperspace and using It.

* GENERATE DATA AND WRITE IT TO THE HIPERSPACE
         .
* BUILD RANGE LIST AND PLACE POINTER TO ADDRESS OF LIST IN RANGPTR
         .
         HSPSERV CWRITE,ADDRSP=HOME,STOKEN=HSSTOK,RANGLIST=RANGPTR,    X
             RETCODE=SRVRCODE,RSNCODE=SRSNCODE
         .

* READ FROM THE HIPERSPACE, IF EVERYTHING HAS BEEN SUCCESSFUL
         .
         HSPSERV CREAD,STOKEN=HSSTOK,RANGLIST=RANGPTR,                 X
             RETCODE=SRVRCODE,RSNCODE=SRSNCODE
         .

HSSTOK     DS  CL8           STOKEN RETURNED FROM DSPSERV CREATE
RANGPTR    DC  A(RANGLIST)   ADDRESS OF RANGLIST PARM AREA
RANGLIST   DS  0CL12
ASLOC      DS  AL4           ADDRESS OF START OF ADDRESS SPACE AREA
HSLOC      DS  AL4           ADDRESS OF HIPERSPACE AREA TO WRITE TO/FROM
NUMBLKS    DS  F             NUMBER OF BLOCKS TO READ/WRITE
SRVRCODE   DS  F             RETURN CODE
SRSNCODE   DS  F             REASON CODE