Read and write services for ESO hiperspaces

The requirements for the caller who requests CREAD and CWRITE are:

• If you code the HSPALET parameter on the HSPSERV macro, you must first code 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.

If you code HSPALET, and you have an FRR recovery routine that gains control while HSPSERV is executing, your recovery routine cannot attempt retry at the time of error.

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 ESO hiperspaces, the hiperspaces that act as a high-speed buffer or cache for data.

Figure 1. Characteristics and Restrictions for ESO Hiperspaces

The standard form of the HSPSERV macro for ESO hiperspaces follows.

The parameters are explained as follows:

CREAD

Requests that the system read data from an ESO hiperspace

If all blocks requested to be read are available in the hiperspace, then the system performs the read operation. However, if one or more of the blocks to be read are no longer available in the hiperspace, then the system returns a failing return code. (See return code 08.) In this case, the system does not tell you which blocks it successfully reads, if any.

STOKEN and RANGLIST are required parameters on the CREAD request. ADDRSP, NUMRANGE, RSNCODE, and RETCODE are optional parameters.

CWRITE

Requests that the system write data to an ESO hiperspace. If the system cannot write all the requested blocks to the hiperspace, then it doesn't write any and rejects the request. (See return code 08.) In this case, the data in the specified range in the hiperspace is unpredictable. Therefore, after an unsuccessful write, do not issue another CREAD against the failing hiperspace range of virtual storage until an intervening CWRITE is successful.

STOKEN and RANGLIST are required parameters on the CWRITE request. ADDRSP, NUMRANGE, KEEP, RSNCODE, and RETCODE are optional parameters.

,STOKEN=stoken-addr

Specifies the address of the 8-character variable that contains the STOKEN for the ESO hiperspace from which the data is to be read or into which the data is to be written. Restrictions on the hiperspace 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.

Use of the HSPALET parameter requires that the caller provide a 144-byte save area in the caller's primary address space or in the common area. If the caller is disabled, the save area must be in nonpageable storage. AR/GPR 13 must provide addressability to this area regardless of the caller's ASC mode. GPR 13 must contain the address of the area and AR 13 must contain 0.

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

If you code HSPALET and you have an FRR recovery routine that gains control while HSPSERV is executing, your recovery routine cannot attempt retry at the time of error.

,NUMRANGE=n

,NUMRANGE=num-addr

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, or specifies the number of entries, from 1 to 50. The default is NUMRANGE=1.

If you omit NUMRANGE, then HSPSERV reads or writes one virtual range.

,RANGLIST=list-addr

Specifies a fullword that contains the address of a parameter area in nonpageable storage that contains a list of up to 50 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 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.

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

The one or more address space ranges on RANGLIST must be consistent with the ADDRSP parameter. When you specify ADDRSP=COMMON, each address space range described in the range list must reside entirely within CSA and have no intersections with other common area subpools or the private area. When you specify ADDRSP=HOME or ADDRSP=PRIMARY, each address space range described in the range list must reside entirely within the private area.

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

The range list must be in the common area or in the private area of the caller's primary address space.

,ADDRSP=HOME

,ADDRSP=PRIMARY

,ADDRSP=COMMON

Specifies the location of the virtual storage range from which the system is to read or into which the system is to write. The location can be the caller's home address space (ADDRSP=HOME), the caller's primary address space (ADDRSP=PRIMARY), or the CSA (ADDRSP=COMMON). The default is ADDRSP=HOME.

,KEEP=YES

,KEEP=NO

Specifies whether or not the system preserves the source data in the virtual storage of the address space after it completes the CWRITE request. KEEP is valid only on the CWRITE request.

If you specify KEEP=YES, the data in the specified address space is unchanged and available for reference. The default is KEEP=YES.

If you specify KEEP=NO, the system might not preserve the data in the address space. If your program will reuse the same virtual storage area after the CWRITE request completes, use KEEP=NO.

,RETCODE=ret-addr

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

,RSNCODE=rsn-addr

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

,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 macro 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 CREAD or HSPSERV CWRITE, 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.