The requirements for the caller are:

• If you code the HSPALET parameter on the HSPSERV macro, you must first issue the SYSSTATE macro to indicate the ASC mode of your program.
• If you code the HSPALET parameter on the HSPSERV macro, you must provide a 144-byte save area in the caller's primary address space.
• The range list must be addressable in the caller's primary address space.

None.

Before issuing the HSPSERV macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

None.

The following figure describes the characteristics and restrictions for the use of standard hiperspaces, the hiperspaces that allow your program to scroll through large areas of data.

Figure 1. Characteristics and Restrictions for Standard Hiperspaces

The standard form of the HSPSERV macro for standard hiperspaces is written as follows:

The parameters are explained as follows:

SREAD

Requests that the system read data from a standard hiperspace to an address space.

STOKEN and RANGLIST are required parameters on the SREAD request. NUMRANGE, RELEASE, HSPALET, RSNCODE, and RETCODE are optional parameters.

SWRITE

Requests that the system write data to a standard hiperspace from an address space.

Notes:

• When HSPSERV returns to the caller after the SWRITE operation, the contents of the address space storage range are not preserved. You can use the address space area again.
• If the hiperspace maps a data-in-virtual object, do not issue an SWRITE request while a DIV SAVE request is current.

STOKEN and RANGLIST are required parameters on the SWRITE request. NUMRANGE, HSPALET, RETCODE, and RSNCODE are optional parameters.

,STOKEN=stoken-addr

Specifies the address of the eight-character variable that contains the STOKEN for the standard hiperspace from which the data is to be read or into which the data is to be written. Restrictions on standard hiperspaces are described in Figure 1.

,HSPALET=alet-addr

Specifies either the address of a fullword or a register that contains the ALET for the hiperspace that is to be accessed. The ALET must be for a hiperspace that is on the caller's DU-AL or PASN-AL.

The HSPALET parameter is optional except for the following case: If the calling program accesses a shared hiperspace, is in problem state, and uses PSW key 8 - F, HSPALET is required.

If you code HSPALET, do not code RELEASE=YES.

If you code HSPALET, your recovery routine cannot attempt retry at the time of error.

,NUMRANGE=n

,NUMRANGE=num-addr

Specifies the number of entries, from 1 to 50, or specifies a fullword that identifies the number of entries in the range list (that the RANGLIST parameter points to), or specifies a register containing the address of a fullword containing the number of entries. The default is NUMRANGE=1.

If you omit NUMRANGE, HSPSERV reads or writes one entry in the range list.

,RANGLIST=list-addr

Specifies a fullword that contains an address of a list of ranges that the system is to read or write, or specifies a register that contains the address of the fullword pointer to the range list. The range list consists of a number of entries (specified by NUMRANGE) where each entry specifies (1) a storage location in an address space, (2) a storage location in a hiperspace, and (3) the number of blocks of data the system is to read or write.

Each entry in the range list consists of three words as follows:

First Word

The starting virtual address in the address space into which the data is to be read or from which the data is to be written

Second Word

The starting virtual address in the hiperspace from which the system is to read or into which the system is to write

Third Word

The number of blocks the system is to read or write

Note that the address is the block number followed by 12 binary zeros.

An example of how to code the RANGLIST parameter when NUMRANGE=3 is as follows:

Restrictions on the areas in the address space and the hiperspace are described in Figure 1.

On return, only if the caller issued the HSPSERV macro with the HSPALET parameter, the range list values might be different from the input values if the system could not at first successfully complete the read or write operation. In that case, the system changes the range list values, but does not restore the input values when it finally returns control to the caller.

,RELEASE=NO

,RELEASE=YES

Specifies whether or not the system is to release the hiperspace pages after it completes the SREAD operation. RELEASE is valid only with SREAD.

RELEASE=NO specifies that the system does not release the hiperspace pages after it completes the SREAD operation. (Unless a subsequent SWRITE request changes the data, the same data will be available again on the next SREAD request.) RELEASE=NO is the default.

RELEASE=YES specifies that, after the SREAD request, the system is to release the storage that backed the data in the hiperspace.

If you code RELEASE=YES, do not code HSPALET.

,RSNCODE=rsn-addr

Specifies the location where the system is to store the reason code. The reason code is also in GPR 0.

,RETCODE=ret-addr

Specifies the location where the system is to store the return code. The return code is also in GPR 15.

,MF=S

Specifies the standard form of the macro. This form generates code to place the parameters into an inline parameter list and invoke the service.

HSPSERV might abnormally terminate with abend code X'01D'. See z/OS MVS System Codes for an explanation of abend code X'01D'.

When control returns from HSPSERV SREAD or HSPSERV SWRITE, GPR 15 (and ret-addr, if you coded RETCODE) contains one of the following hexadecimal return codes. GPR 0 (and rsn-addr, if you coded RSNCODE) contains one of the following hexadecimal reason codes.