 |
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/.
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.
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
|
z/OS MVS Programming: Assembler Services Reference ABE-HSP
Copyright IBM Corporation 1990, 2014