Transferring data to and from a hiperspace

Before it can reference data or manipulate data in a hiperspace, the program must bring the data into the address space. The HSPSERV macro performs the transfer of data between the address space and the hiperspace.

On the HSPSERV macro, the write operation transfers data from the address space to the hiperspace. The read operation transfers the data from the hiperspace to the address space. HSPSERV allows multiple reads and writes to occur at one time. This means that one HSPSERV request can transfer the data in more than one data area in a hiperspace to an equal number of data areas in an address space. Likewise, one HSPSERV request can write data from more than one buffer area in an address space to an equal number of areas in a hiperspace.

Figure 1 shows three virtual storage areas that you need to identify when you request a data transfer:

The hiperspace
The buffer area in the address space that is the source of the write operation and the target of the read operation
The data area in the hiperspace that is the target of the write operation and the source of the read operation.

On the HSPSERV macro, you identify the hiperspace and the areas in the address space and the hiperspace:

STOKEN specifies the STOKEN of the hiperspace.
RANGLIST specifies a list of ranges that indicate the boundaries of the buffer areas in the address space and the data area in the hiperspace.
NUMRANGE optionally specifies the number of data areas the system is to read or write. The default is one data area.

Figure 1. Illustration of the HSPSERV write and read operations

This images shows an HSPSERV write and read operation: The box on the right is an address space that contains the HSPSERV macro and a buffer box. The buffer box points to a list that says: After a write operation, for standard hiperspaces, the data is unpredictable. The buffer area is available for reuse. The box on the left is a hiperspace that contains a data area and points to a list that says For ESO hiperspaces, the data is preserved unless you specify KEEP=NO. After a read operation, for standard hiperspaces, the data is preserved unless you specify RELEASE=YES. For ESO hiperspaces, the data is preserved, yet volatile. Between the two boxes arrows show the buffer area writing to the data area and the data area reading to the data area.

HSPSERV has certain restrictions on these areas. Two restrictions are that the data areas must start on a 4K byte boundary and their size must be in multiples of 4K bytes. Other requirements are listed in the description of HSPSERV in z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG. Read the requirements carefully before you issue the macro.

The system does not always preserve the data in the areas that are the source for the read and write operations. Figure 1 tells you what the system does with the areas after it completes the transfer. The sections Read and write operations for standard hiperspaces and Read and write operations for expanded storage only hiperspaces describe how you use the HSPSERV macro.