z/OS MVS Programming: Assembler Services Reference ABE-HSP
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF


Description

z/OS MVS Programming: Assembler Services Reference ABE-HSP
SA23-1369-00

DSPSERV for data spaces

To control the use of data spaces, use the variation of the DSPSERV macro described under DSPSERV — Create, delete, and control data spaces.

The DSPSERV macro creates, deletes, and controls hiperspaces. A hiperspace is a range of up to two gigabytes of contiguous virtual storage addresses that a program can use as a buffer. Like a data space, a hiperspace can hold user data and programs stored as data; it does not contain common areas or system data. Instructions do not execute in a hiperspace. Unlike a data space, data is not directly addressable. To manipulate data in a hiperspace, you bring the data into the address space in 4K-byte blocks.

A nonshared standard hiperspace, available to all programs, is backed with real storage and if necessary, with auxiliary storage. Through the buffer area in the address space, your program can view or “scroll” through the standard hiperspace. A shared standard hiperspace is available to problem state programs with PSW keys of 8 through F, but only under the control of programs in supervisor state or with PSW keys of 0 through 7. An ESO (expanded storage only) hiperspace is available only for supervisor state or PSW key 0 through 7 programs. For more information on hiperspaces and how to use them, see z/OS MVS Programming: Assembler Services Guide.

Use the DSPSERV macro to:
  • Create a standard hiperspace (CREATE parameter and TYPE=HIPERSPACE parameter)
  • Delete a hiperspace (DELETE parameter)
  • Release an area of a hiperspace (RELEASE parameter)
  • Increase the current size of a hiperspace (EXTEND parameter)

On the DSPSERV macro, hiperspaces are identified through STOKENs. The STOKEN is a unique identifier of address spaces, data spaces, and hiperspaces.

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Problem state programs with PSW key 8-F can request these DSPSERV services:
  • Create a nonshared standard hiperspace
  • Delete any hiperspace they own
  • Release an area of a hiperspace
  • Increase the current size of a hiperspace
Dispatchable unit mode: Task or SRB
Cross memory mode: Any PASN, any HASN, any SASN
AMODE: 31-bit
ASC mode: Primary or access register (AR)
Interrupt status: Enabled for I/O and external interrupts
Locks: No locks held
Control parameters: Must be in the primary address space.

Programming requirements

If your program is in AR mode, issue the SYSSTATE ASCENV=AR macro before you issue DSPSERV. SYSSTATE ASCENV=AR tells the system to generate code appropriate for AR mode.

If you use the RELEASE parameter to specify a range of storage using INLIST=YES, you must use RANGLIST to specify a range list that is mapped by the IARDRL macro. For information on the IARDRL macro, see z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/.

Restrictions

None.

Input register information

Before issuing the DSPSERV 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.

Output register information

When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0
Reason code
1
Used as a work register by the system
2-13
Unchanged
14
Used as a work register by the system
15
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as work registers by the system

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.

Performance implications

None.

Syntax

The standard form of the DSPSERV macro is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
One or more blanks must precede DSPSERV.
   
DSPSERV  
   
One or more blanks must follow DSPSERV.
   
  Valid parameters (Required parameters are underlined.)
CREATE STOKEN, NAME, TYPE, GENNAME, OUTNAME,
  BLOCKS, ORIGIN, and NUMBLKS
RELEASE STOKEN, START, BLOCKS, INLIST, RANGLIST, NUMRANGE
DELETE STOKEN
EXTEND STOKEN, BLOCKS, VAR, NUMBLKS
   
,STOKEN=stoken-addr stoken-addr: RX-type address or register (2) - (12).
   
,TYPE=HIPERSPACE  
   
   ,NAME=name-addr name-addr: RX-type address or register (2) - (12).
   
   ,GENNAME=NO Default: GENNAME=NO
   ,GENNAME=COND  
   ,GENNAME=YES  
   
   ,OUTNAME=outname-addr outname-addr: RX-type address or register (2) - (12).
   
   ,START=start-addr start-addr: RX-type address or register (2) - (12).
   
   ,BLOCKS=(max-addr,init-addr) max-addr: RX-type address or register (2) - (12).
   ,BLOCKS=(max,init) init-addr: RX-type address or register (2) - (12).
   ,BLOCKS=max max: Number up to 524288.
   ,BLOCKS=(0,init) init: Number up to 524288.
   ,BLOCKS=0 0 specifies the installation default size.
   ,BLOCKS=(0,init-addr) Default for CREATE: BLOCKS=0
   ,BLOCKS=(size-addr) size-addr: RX-type address or register (2) - (12).
   ,BLOCKS=(size) size: Number up to 524288.
   
   ,ORIGIN=origin-addr origin-addr: RX-type address or register (2) - (12).
   
   ,NUMBLKS=numblks-addr numblks-addr: RX-type address or register (2) - (12).
   ,INLIST=NO Default: INLIST=NO
   ,INLIST=YES  
   ,RANGLIST=rangelist_addr rangelist_addr: RS-type address or register (2) - (12). Required with INLIST=YES.
   ,NUMRANGE=numrange_addr numrange_addr: RS-type address or register (2) - (12).
   ,NUMRANGE=1 Default: NUMRANGE=1
   
   ,VAR=NO Default: VAR=NO
   ,VAR=YES  
   
   ,PLISTVER=IMPLIED_VERSION  
   ,PLISTVER=MAX Default: IMPLIED_VERSION
   ,PLISTVER=plistver plistver: 0
   
   ,MF=S  
   

Parameters

The CREATE, RELEASE, DELETE, and EXTEND parameters, which designate the services of the DSPSERV macro, are mutually exclusive. You can select only one.

The parameters are explained as follows:

CREATE
Requests that the system create a nonshared standard hiperspace. Creating a hiperspace is somewhat like issuing a GETMAIN for storage. The entire hiperspace is in the same storage key. When you specify CREATE, you must also specify NAME, STOKEN, and TYPE=HIPERSPACE.

Optional parameters when you create a hiperspace are: OUTNAME, GENNAME, BLOCKS, ORIGIN, and NUMBLKS.

RELEASE
Requests that the system resources used to contain the user's data be returned to the system. Although the data contained in the virtual storage is discarded, the user's virtual storage itself remains and is available for further use. When you specify RELEASE, you must also specify STOKEN to identify the hiperspace, and the START and BLOCKS parameters to identify the beginning and the length of the area to be returned to the system.

The caller must own the hiperspace, and the caller's PSW key must be zero or equal to the key of the storage the system is to release. Otherwise, the system abends the caller.

Pages that are released through DSPSERV RELEASE do not occupy space in central, expanded, or auxiliary storage. These pages are available for further use and contain hexadecimal zeros.

DELETE
Requests that the system delete a hiperspace. STOKEN is the only required parameter on the DELETE request.

A problem state or PSW key 8 - F caller must own the hiperspace, and its PSW key must be zero or equal to the storage key of the hiperspace the system is to release.

EXTEND
Requests that the system increase the current size of a hiperspace. Use EXTEND only for a hiperspace that was created with an initial size smaller than a maximum size. Before a caller can reference storage beyond the current size, the caller must use EXTEND to increase the storage that is available. If a caller references hiperspace storage beyond the current size, the system rejects the request; it terminates the caller with an 0C4 abend code.

STOKEN (identifying the hiperspace) and BLOCKS (specifying the size of the increase) are required on the EXTEND request. VAR (requesting a variable extension) and NUMBLKS (requesting the size of the extension) are optional parameters.

For the problem state and PSW key 8 through F caller, the TCB that represents it must own the hiperspace.

The system rejects the EXTEND request if you specified VAR=NO (or took the default) and the extended size would:
  • Exceed the maximum size specified when the hiperspace was created.
  • For a hiperspace with a storage key greater than 7, extend the cumulative data space and hiperspace totals beyond the installation limits for the owning address space.
,STOKEN=stoken-addr
Specifies the address of the eight-byte STOKEN for the hiperspace being created, deleted, or released.

DSPSERV CREATE returns the STOKEN; STOKEN is required input for all other requests.

,TYPE=HIPERSPACE
Specifies that the system is to create a standard hiperspace rather than a data space.
,NAME=name-addr
Specifies the address of the eight-byte variable or constant that contains the name of the hiperspace. NAME is required for DSPSERV CREATE.

Hiperspace™ names are from one to eight bytes long. They can contain letters, numbers, and @, #, and $, but they cannot contain embedded blanks. Names that contain fewer than eight bytes must be left-justified and padded on the right with blanks.

Hiperspace and data space names must be unique within the home address space of the owner. No other hiperspace or data space in the home address space can have the same name. Therefore, in choosing names for your hiperspaces, you must avoid using the same names that IBM® might use for hiperspaces. Do not use the following names:
  • Names that begin with A through I.
  • Names that begin with a numeral or with SYS.

How to choose names for your hiperspaces: Use hiperspace names that begin with @, #, $, or the letters J through Z, with the exception of SYS. The system abends problem state programs that begin names with SYS.

To ensure that the names for your hiperspaces are unique, ask the system to generate a unique name. See the GENNAME parameter.

,GENNAME=NO
,GENNAME=COND
,GENNAME=YES
Specifies whether or not you want the system to generate a name for the hiperspace to ensure that all names are unique within the address space. The system generates a name by adding a 5-character prefix (consisting of a numeral followed by four characters) to the first three characters of the name you supply on the NAME parameter. For example, if you supply ‘XYZDATA’ on the NAME parameter, the name becomes ‘nCCCCXYZ’ where ‘n’ is the numeral, ‘CCCC’ is the 4-character string generated by the system, and XYZ comes from the name you supplied on NAME. See NAME for more information about naming conventions.
GENNAME=NO
The system does not generate a name. You must supply a name unique within the address space. GENNAME=NO is the default.
GENNAME=COND
The system generates a unique name only if you supply a name that is already being used. Otherwise, the system uses the name you supply.
GENNAME=YES
The system takes the name you supply on the NAME parameter and makes it unique.

If you want the system to return the unique name it generates, use the OUTNAME parameter.

,OUTNAME=outname-addr
Specifies the address of the eight-byte variable where the system returns the name it generated for the hiperspace. the generated name of the hiperspace if you specify GENNAME=YES or GENNAME=COND. The OUTNAME parameter is optional on DSPSERV CREATE.
,START=start-addr
Specifies the address of a four-byte variable containing the beginning address of a block of storage in a hiperspace. The address must be on a four-kilobyte boundary. A block is a unit of 4K bytes. START is required on a RELEASE request.
,BLOCKS=(max-addr,init-addr)
,BLOCKS=(max,init)
,BLOCKS=max
,BLOCKS=(0,init)
,BLOCKS=0
,BLOCKS=(0,init-addr)
,BLOCKS=size-addr
,BLOCKS=size
Specifies the size of a hiperspace or the size of an area within a hiperspace. BLOCKS is required for all requests except for DSPSERV DELETE.

For a CREATE request, specifies the maximum size (in blocks) to which the hiperspace can expand (max-addr or max) and the initial size of the hiperspace (init-addr or init.). A block is a unit of 4K bytes. You cannot extend the hiperspace beyond its maximum size.

max-addr specifies the address of a field that contains the maximum size of the hiperspace to be created. max is the number of blocks (up to 524,288) to be used for the hiperspace.

init-addr specifies the address of the initial size of the hiperspace. init is the number of blocks to be used as the initial size. If the initial size you specify exceeds or equals the maximum size, then the initial size becomes the maximum size.

0 specifies the default size, either the installation default or the IBM-defined default. The IBM-defined default maximum is 239 blocks. Your installation can use the installation exit IEFUSI to change the IBM default. The system returns the maximum size at the location identified by NUMBLKS.

If you do not code the BLOCKS parameter on the CREATE request, the system uses BLOCKS=0, setting the initial size and the maximum size equal to the installation (or IBM) default.

For a RELEASE request, BLOCKS and START are required parameters that define contiguous storage (in 4K blocks) that the system is to release. BLOCKS specifies the size of an area to be released (size-addr or size). The minimum size is 1 block and the maximum is 524,288 blocks (2 gigabytes).

For an EXTEND request, BLOCKS is a required parameter that defines the amount of increase of the current size of the hiperspace.

,ORIGIN=origin-addr
Specifies the address of the four-byte variable that contains the lowest address (either zero or 4096) of the new hiperspace. The system returns the beginning address of the hiperspace at origin-addr. The system tries to start all hiperspaces at origin zero; on some processors, however, the origin is 4096. ORIGIN is an optional parameter for DSPSERV CREATE.
,NUMBLKS=numblks-addr
Specifies the address of the four-byte area where the system returns one of the following:
  • For DSPSERV CREATE, the maximum size (in blocks) of the newly created hiperspace.
  • For DSPSERV EXTEND, the size by which the system extended the hiperspace.

The NUMBLKS parameter is an optional parameter on DSPSERV CREATE and DSPSERV EXTEND.

If, when you create a hiperspace, you specify BLOCKS=0 or do not specify the BLOCKS parameter, the system uses the default that your installation established in the installation exit IEFUSI. The system returns this default value at numblks-addr.

,INLIST=NO
,INLIST=YES
Specifies whether a range is included (YES). The default is INLIST=NO. If you specify YES, you must also specify the RANGLIST parameter.
,RANGLIST=rangelist-addr
Specifies the name (RS-type) or address (in register 2-12) of a required input fullword that contains the address of the range list. The range list consists of a number of entries (specified by NUMRANGE); each entry is 8 bytes long. A mapping of each entry is provided through the mapping macro IARDRL.
,NUMRANGE=numrange_addr
Specifies the name (RS-type) or address (in register 2-12) of an optional parameter that provides the number of entries in the supplied RANGLIST. The maximum value may not exceed 16. The default is 1.
,VAR=NO
,VAR=YES
Specifies whether your request for the system to extend the amount of storage available in a hiperspace is a variable request. When you use DSPSERV EXTEND for a hiperspace, the system might not be able to extend the hiperspace by the amount you request, because that amount might cause the system to exceed one of the following:
  • The maximum size of the hiperspace, as specified on the BLOCKS parameter when the hiperspace was created.
  • For a hiperspace with storage key 8 - F, the limit of combined data space and hiperspace storage with storage key 8 - F for an address space. (The installation established this limit on the IEFUSI installation exit, or took the IBM default.)
If you specify VAR=YES (the variable request) and the system cannot satisfy your request, the system extends the hiperspace to one of the following sizes, depending on which is smaller:
  • The maximum size specified on the BLOCKS parameter when the hiperspace was created.
  • The largest size that would still keep the combined total of data space and hiperspace storage within the limits established by the installation for an address space.
If you specify VAR=NO (the default), the system:
  • Abends the caller if the extended size would exceed the maximum size specified when the hiperspace was created.
  • Rejects the request if the hiperspace has storage key 8 - F and the request would extend the cumulative data space and hiperspace totals beyond the installation limits for an address space.

If you use the NUMBLKS parameter, the system returns the size by which the system extends the hiperspace.

,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:
  • IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
  • MAX, if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.

    If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.

  • 0, if you use the currently available parameters.
To code, specify in this input parameter one of the following:
  • IMPLIED_VERSION
  • MAX
  • A decimal value of 0
,MF=S
Specifies the standard form of DSPSERV. The standard form places the parameters into an in-line parameter list.

ABEND codes

DSPSERV might abnormally terminate with abend code X'01D'. See z/OS MVS System Codes for an explanation and programmer response.

Return and reason codes

Hexadecimal return and reason codes from DSPSERV CREATE:

Return Code Reason Code Meaning and Action
00 Meaning: DSPSERV CREATE completed successfully.

Action: None.

04 xx000Cxx Meaning: Program error. DSPSERV CREATE completed successfully. You specified a size of 2 gigabytes (524,288 blocks). However, because the processor did not support a hiperspace with zero origin, a hiperspace of one less block (524,287 blocks) was created.

Action: None required. However, you should verify that your program correctly accounts for the nonzero origin of the hiperspace.

08 xx0005xx Meaning: Program error. Creation of the hiperspace would violate installation criteria. See the IEFUSI installation exit in z/OS MVS Installation Exits.

Action: Check with your system programmer for local restrictions on the creation and use of hiperspaces.

08 xx0009xx Meaning: Program error. The specified hiperspace name is not unique within the address space.

Action: Check that the hiperspace name is not already in use by another active hiperspace. Change the hiperspace name or specify the GENNAME parameter on the DSPSERV macro to get the system to generate a unique name.

08 xx0012xx Meaning: Environmental error. The system's set of generated names for data spaces and hiperspaces has been temporarily depleted.

Action: Retry the job one or more times during a period of lower system usage. If the problem persists, consult your system programmer, who might be able to tune the system so that more names are available for use.

0C xx0006xx Meaning: Environmental error. The system cannot create any additional data spaces at this time because of a shortage of resources.For reason code 6C000611, an ASTE could not be obtained for the requested data space. If the request is for a SCOPE=COMMON data space, this may mean there are already as many SCOPE=COMMON data spaces in the system as are allowed by the MAXCAD parameter.

Action: Retry the job one or more times during a period of lower system usage. If the problem persists, consult your system programmer, who might be able to tune the system so that resources will not become depleted.

0C xx0007xx Meaning: System error. The system cannot obtain addressability to its own hiperspaces.

Action: Record the return and reason code and supply it to the appropriate IBM support personnel.

Hexadecimal return and reason codes from DSPSERV EXTEND:

Return Code Reason Code Meaning and Action
00 Meaning: DSPSERV EXTEND completed successfully.

Action: None.

08 xx0502xx Meaning: Environmental error. Extending the hiperspace size would cause the data space and hiperspace limits for the address space to be exceeded.

Action: Check with your system programmer, who might be able to tune the system so that the function is made available to your program.

08 xx0503xx Meaning: Program error. You are using VAR=YES to extend the current size of the hiperspace; however, the hiperspace is already the maximum size.

Action: None required. However, if your program requires more storage, you should consider creating an additional hiperspace.

The caller of DSPSERV does not receive any return codes for the RELEASE and DELETE services.

Example

Create a hiperspace named TEMP with a size of 10 million bytes.
         DSPSERV CREATE,NAME=HSPCNAME,STOKEN=HSPCSTKN,             X
               TYPE=HIPERSPACE,BLOCKS=HSPBLCKS,ORIGIN=HSPCORG
*        .
HSPCNAME DC   CL8'TEMP    '            HIPERSPACE NAME
HSPCSTKN DS   CL8                      HIPERSPACE STOKEN
HSPCORG  DS   F                        HIPERSPACE ORIGIN RETURNED
HSPCSIZE EQU  10000000
HSPBLCKS DC   A((HSPCSIZE+4095)/4096)  NUMBER OF BLOCKS NEEDED FOR
*                                      A 10 MILLION BYTE HIPERSPACE

Go to the previous page Go to the next page




Copyright IBM Corporation 1990, 2014