 |
The DSPSERV macro creates, deletes, and controls data spaces.
A data space is a range of up to two gigabytes of contiguous
virtual storage addresses that a program can directly manipulate through
assembler instructions. A data space can hold only user data and
user programs stored as data; code does not execute in a data space.
There are three kinds of data spaces: SCOPE=SINGLE, SCOPE=ALL,
and SCOPE=COMMON. A SCOPE=SINGLE data space is used in ways similar
to the use of the private area of an address space. A SCOPE=ALL or
SCOPE=COMMON data space is used in ways similar to the use of the
common area of an address space. A problem state program with PSW
key 8 - F cannot create or delete a SCOPE=ALL or SCOPE=COMMON data
space. However, it can use these spaces, providing a supervisor state
program or a program with PSW key 0 - 7 created the space and established
addressability to the space on its behalf. For more information on
data spaces and how to use them, see z/OS MVS Programming: Assembler Services Guide.
Use the DSPSERV macro to: - Create a data space (CREATE parameter and TYPE=BASIC parameter)
- Delete a data space (DELETE parameter)
- Release an area of a data space (RELEASE parameter)
- Increase the current size of a data space (EXTEND parameter)
- Load an area of a data space into central storage (LOAD parameter)
- Take (that is, page out) from real storage an area of a data space
(OUT parameter)
On the DSPSERV macro, data spaces are identified through STOKENs.
A STOKEN is a unique identifier of address spaces, data spaces, and
hiperspaces.
Environment
The requirements for the caller are:
| Environmental factor |
Requirement |
|---|
| Minimum authorization: |
A problem state program with PSW key 8-F can use
DSPSERV to create a SCOPE=SINGLE data space. For all other DSPSERV
services, that program must own the data space. |
| Dispatchable unit mode: |
Task or SRB |
| Cross memory mode: |
Any PASN, any HASN, any SASN |
| AMODE: |
31- or 64-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 the RANGLIST parameter 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,
BACK, |
| |
BLOCKS, TTOKEN, ORIGIN, NUMBLKS |
| RELEASE |
STOKEN, START, BLOCKS, INLIST,
RANGLIST, NUMRANGE |
| DELETE |
STOKEN |
| EXTEND |
STOKEN, BLOCKS, VAR, NUMBLKS |
| LOAD |
STOKEN, BLOCKS, START |
| OUT |
STOKEN, BLOCKS, START |
| |
|
| ,STOKEN=stoken-addr |
stoken-addr: RX-type address
or register (2) - (12). |
| |
|
| ,TYPE=BASIC |
Default: TYPE=BASIC |
| |
|
| ,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. |
| |
|
| ,BACK=31 |
Default: BACK=31 |
| ,BACK=64 |
|
| |
|
| ,TTOKEN=ttoken-addr |
ttoken-addr: RX-type address
or register (2) - (12). |
| |
|
| ,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 |
| |
|
| ,HIDEZERO=NO |
Default: HIDEZERO=NO |
| ,HIDEZERO=YES |
|
| |
|
| ,MF=S |
|
| |
|
Parameters
The CREATE, RELEASE, DELETE, EXTEND, LOAD, and OUT 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 data space. Creating a data
space is somewhat like issuing a GETMAIN for storage. The entire data
space is in the same storage key. When you specify CREATE, you must
specify the NAME and STOKEN parameters.
Optional parameters when
you create a data space are: TYPE, GENNAME, OUTNAME, BLOCKS, BACK,
TTOKEN, 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 data space, and the START and
BLOCKS parameters to identify the beginning and the length of the
area to be returned to the system.
A problem state program with
PSW key 8 - F can release any data space it owns or created, providing
its PSW key matches the storage key of the data space. Note
that no exception to the caller's PSW key being zero or equal to the
key of the storage to be released is made for a storage-protection
override.However, if the program is using the
IARVSERV macro to share the data space, the program cannot release
the data space if it is a shared group and is fixed through another
view.
Use DSPSERV RELEASE instead of using the MVCL instruction
for these reasons: - The DSPSERV RELEASE is faster than MVCL for very large areas.
- Pages that are released through DSPSERV RELEASE do not occupy
space in real storage.
- DELETE
- Requests that the system delete a data space. STOKEN is the only
required parameter on the DELETE request.
A problem state program
with PSW key 8 - F can delete any data space it owns or created, providing
its PSW key matches the storage key of the data space.
- EXTEND
- Requests that the system increase the current size of a data space.
Use EXTEND only for a data space 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 data
space) 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
a problem state and PSW key 8 - F caller, any TCB can extend a data
space that was created by any other TCB in the address space.
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 data space was created.
- For a data space with a storage key greater than 7, extend the
cumulative data space and hiperspace space totals beyond the installation
limits for the owning address space.
- LOAD
- Requests that the system load some areas of a data space into
central storage. The system fills the request depending on how many
central storage frames are available. When you specify LOAD, you
must also specify the STOKEN, START, and BLOCKS parameters.
For
a problem state and PSW key 8 - F caller, the TCB that represents
it owns the data space.
- OUT
- Tells the system that it can take some areas of a data space from
central storage. When you specify OUT, you must also specify the
STOKEN, START, and BLOCKS parameters.
For a problem state and PSW
key 8 - F caller, the TCB that represents it owns the data space.
- ,STOKEN=stoken-addr
- Specifies the address of the eight-byte STOKEN for the data space.
DSPSERV CREATE returns the STOKEN as output; STOKEN is required input
for all other DSPSERV requests.
- ,TYPE=BASIC
- Specifies that the system should create a data space rather than
a hiperspace. TYPE=BASIC is the default.
- ,NAME=name-addr
- Specifies the address of the eight-byte variable or constant that
contains the name of the data space. NAME is required for DSPSERV
CREATE.
Data space 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.
Data space
and hiperspace names must be unique within the home address space
of the owner. No other data space or hiperspace in the home address
may have the same name. Therefore, in choosing names for your data
spaces, you must avoid using the same names that IBM® uses
for data spaces. Do not use the following names: - Names that begin with A through I.
- Names that begin with numerals or with SYS.
How to choose names for your data spaces: Use data space
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. Do not specify a data space name
beginning with a numeric if you are creating the data space name.
To
ensure that the names for your data spaces are unique, use the GENNAME
parameter to generate a unique name.
- ,GENNAME=NO
- ,GENNAME=COND
- ,GENNAME=YES
- Specifies whether or not you want the system to generate a name
for the data space 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 the NAME parameter for the data space and hiperspace
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 if you specify GENNAME=YES or GENNAME=COND
on DSPSERV CREATE. The OUTNAME parameter is optional.
- ,START=start-addr
- Specifies the address of a four-byte variable containing the beginning
address of a block of storage in a data space. The address must be
on a four-kilobyte boundary. START is required on RELEASE requests.
- ,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 the data space the system is to create,
or the size of an area within a data space. BLOCKS is required for
all DSPSERV requests except DSPSERV DELETE.
For a CREATE
request, specifies the maximum size (in blocks) to which the
data space can expand (max-addr or max)
and the initial size of the data space (init-addr or init.).
A block is a unit of 4K bytes. You cannot extend the data space beyond
its maximum size.
max-addr specifies the
address of a field that contains the maximum size of the data space
to be created. max is the number of blocks (up
to 524,288) to be used for the data space.
init-addr specifies
the address of the initial size of the data space. 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 data space.
For
LOAD and OUT requests, BLOCKS is a required parameter that
defines the amount of data space storage that the system is to load
into central storage or page out from central storage.
BLOCKS=size-addr in
MVS/SP3.1.0 is incompatible with BLOCKS=(size-addr) in
MVS/SP3.1.0e and later releases in the case where size-addr is
a register. If you coded BLOCKS=(register) in MVS/SP3.1.0,
and plan to recompile the program to run on later releases of MVS™,
you must change the specification to BLOCKS=((register)) before
you recompile.
- ,BACK=31
- ,BACK=64
- Specifies whether the data space pages can be backed by real storage
above 2 gigabytes when defined IOON (fixed).
BACK=31 specifies that
the data space pages will be backed by frames below 2 gigabytes when
defined IOON.
BACK=64 specifies that the data space pages will
be backed by frames above or below 2 gigabytes when defined IOON.
- ,TTOKEN=ttoken-addr
- Specifies the address of the TTOKEN, the 16-byte variable or constant
that identifies the task that is to become the owner of the data space.
The TTOKEN must represent either the caller's task or the caller's
job step task. TTOKEN is valid only on the CREATE request.
- ,ORIGIN=origin-addr
- Specifies the address of the four-byte variable that contains
the lowest address (either zero or 4096) of the new data space. The
system returns the beginning address of the data space at origin-addr.
The system tries to start all data spaces 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
data space.
- For DSPSERV EXTEND, the size by which the system extended the
data space.
The NUMBLKS parameter is an optional parameter on DSPSERV
CREATE and DSPSERV EXTEND.
If, when you create a data space,
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 or not your request for the system to extend
the amount of storage available in a data space is a variable request.
When you use DSPSERV EXTEND for a data space, the system might not
be able to extend the data space the amount you request because that
amount might cause the system to exceed one of the following:
- The maximum size of the data space, as specified on the BLOCKS
parameter when the data space was created.
- For a data space 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 data space to
one of the following sizes, depending on which is smaller: - The maximum size specified on the BLOCKS parameter when the data
space was created.
- The largest size that would still keep the combined 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 data space was created.
- Rejects the request if the data space has storage key 8 - F and
the request would extend the combined data space and hiperspace beyond
the installation limit for an address space.
If you use the NUMBLKS parameter, the system returns
the size by which the system extends the data space.
- ,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
- ,HIDEZERO=NO
- ,HIDEZERO=YES
- An optional keyword input that specifies whether the system hides
page 0 of the data space so that references to that page do not succeed.
Regardless, the data space starts at the returned origin, and the
number of blocks requested, if available, are allocated. HIDEZERO=NO
is the default.
- HIDEZERO=NO indicates not to hide page 0.
- HIDEZERO=YES indicates to hide page 0. The returned origin indicates
the lowest address that may be used which will be x'1000'. When PageFrameSize=1M
is in effect:
- The first segment is backed by 4K pages.
- If performance is critical, avoid using any address below X'100000'.
- ,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 data space
with zero origin, a data space 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 data space.
|
| 08 |
xx0005xx |
Meaning: Program error. Creation of the
data space 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 data spaces.
|
| 08 |
xx0009xx |
Meaning: Program error. The specified data
space name is not unique within the address space. Action:
Check that the data space name is not already in use by another active
data space. Change the data space 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. 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 data structures. 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 |
|---|
| 00 |
— |
Meaning: DSPSERV EXTEND completed successfully. Action:
None.
|
| 08 |
xx0502xx |
Meaning: Environmental error. Extending
the data space 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 data space; however, the data space
is already the maximum size. Action: None required. However,
if your program requires more storage, you should consider creating
an additional data space.
|
The caller of DSPSERV does not receive any return codes for the
RELEASE, DELETE, LOAD, and OUT services.
Example 1
Create a data space named TEMP with a size of 10 million bytes. DSP1 DSPSERV CREATE,NAME=DSPCNAME,STOKEN=DSPCSTKN,
BLOCKS=DSPBLCKS,ORIGIN=DSPCORG
* .
DSPCNAME DC CL8'TEMP ' DATA SPACE NAME
DSPCSTKN DS CL8 DATA SPACE STOKEN
DSPCORG DS F DATA SPACE ORIGIN RETURNED
DSPCSIZE EQU 10000000
DSPBLCKS DC A((DSPCSIZE+4095)/4096) NUMBER OF BLOCKS NEEDED FOR
* A 10 MILLION BYTE DATA SPACE
Example 2
Release a range of storage. LA 5,RANGELST
ST 5,RNGLSTPT
LA 5,RNGLSTPT
DSP2 DSPSERV RELEASE,STOKEN=DSPCSTKN,DISABLED=NO,INLIST=YES,
NUMRANGE=NUMRANGS,RANGLIST=(5)
*
RNGLSTPT DS F RANGE LIST ADDRESS
DSPCSTKN DS CL8 DATA SPACE STOKEN
NUMRANGS DC F'9' NUMBER OF RANGES TO PROCESS
RANGELST DS CL256 STORAGE FOR MAX NUMBER OF RANGES
DRLMAP DS 0F THIS CREATES A DSECT
IARDRL MAPPING MACRO
|
z/OS MVS Programming: Assembler Services Reference ABE-HSP
Copyright IBM Corporation 1990, 2014