|
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. Unlike an address space, a data space can
hold only data or programs stored as data. For more information on
data spaces and how to use them, see z/OS MVS Programming: Extended Addressability 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 central storage an area of a data
space (OUT parameter)
- Back data space virtual pages with 1 MB page frames, if possible
(PAGEFRAMESIZE=1M).
DSPSERV is also described in z/OS MVS Programming: Assembler Services Reference ABE-HSP,
with the exception of the DREF, SCOPE, KEY, CALLERKEY, FPROT, and
DISABLED parameters. These parameters are restricted to supervisor
state or PSW key 0-7 programs.
Environment
The requirements for the caller are:
Environmental factor |
Requirement |
---|
Minimum authorization: |
To request the following DSPSERV services, a program must be
supervisor state or PSW key 0-7: - Create a data space with disabled referenced (DREF) storage or
fetch protected (FPROT) storage
- Create and delete a SCOPE=ALL and SCOPE=COMMON data space
- Assign a storage key to a data space
- Load an area of a SCOPE=ALL or SCOPE=COMMON data space into central
storage
- Page out of central storage an area of a SCOPE=ALL or SCOPE=COMMON
data space
- Extend the current size of a data space it does not own
|
|
|
|
Problem state programs with PSW key 8-F can request
all other DSPSERV services for data spaces. |
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, with
the following exception: can be disabled for I/O and external interrupts
if the caller specifies DSPSERV RELEASE with DISABLED=YES to release
data space pages that reside in DREF storage |
Locks: |
No locks held, except the CPU lock if the caller
specifies DSPSERV RELEASE with DISABLED=YES to release data space
pages that reside in DREF storage |
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 the caller is disabled and specifies DISABLED=YES, the parameter
list must be in fixed or DREF storage.
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/.
For information about programs in 64-bit addressing mode (AMODE
64), see z/OS MVS Programming: Extended Addressability Guide.
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 if the return code in GPR 15 is not 0; otherwise,
used as a work register by the system
- 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, DREF, SCOPE, CALLERKEY, KEY, FPROT, TTOKEN, ORIGIN, NUMBLKS,BACK, PAGEFRAMESIZE |
RELEASE |
STOKEN, START, BLOCKS, INLIST,
RANGLIST, NUMRANGE, DISABLED |
DELETE |
STOKEN, TTOKEN |
EXTEND |
STOKEN, BLOCKS, VAR, NUMBLKS |
LOAD |
STOKEN, START, BLOCKS |
OUT |
STOKEN, START, BLOCKS |
|
|
PAGEFRAMESIZE=4K |
Default: PAGEFRAMESIZE=4K |
PAGEFRAMESIZE=1M |
|
|
|
,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). |
|
|
,BACK=31 |
Default: BACK=31 (for PAGEFRAMESIZE=4K) |
,BACK=64 |
Default: BACK=64 (for PAGEFRAMESIZE=1M) |
|
|
,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. |
|
|
,DREF=NO |
Default: DREF=NO |
,DREF=YES |
|
|
|
,SCOPE=SINGLE |
Default: SCOPE=SINGLE |
,SCOPE=ALL |
|
,SCOPE=COMMON |
|
|
|
,CALLERKEY |
Default: CALLERKEY |
,KEY=key-addr |
key-addr: RX-type address or
register (2) - (12). |
|
|
,FPROT=YES |
Default: FPROT=YES |
,FPROT=NO |
|
|
|
,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). Default: NUMRANGE=1 |
|
|
,VAR=NO |
Default: VAR=NO |
,VAR=YES |
|
|
|
,DISABLED=NO |
Default: DISABLED=NO |
,DISABLED=YES |
|
|
|
,PLISTVER=IMPLIED_VERSION |
Default: IMPLIED_VERSION |
,PLISTVER=MAX |
|
,PLISTVER=plistver |
plistver: 0 |
|
|
,HIDEZERO=NO |
Default: HIDEZERO=NO |
,HIDEZERO=YES |
|
|
|
,MF=S |
|
|
|
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.
Parameters
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, OUTNAME, GENNAME, BLOCKS, DREF,
SCOPE, CALLERKEY, KEY, FPROT, TTOKEN, ORIGIN, NUMBLKS, BACK and
PAGEFRAMESIZE.
- 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 supervisor state or key 0-7
program can release any data space it owns or created, if its home
or primary address space is the same as the owner's. A problem state
program can release any data space it owns or created.
The
caller must own the data space, 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. 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.
If your program
is disabled for I/O and external interrupts, use DISABLED=YES; otherwise,
use DISABLED=NO (the default). DSPSERV RELEASE with DISABLED=YES is
valid only to release data space pages that reside in DREF storage.
Use
DSPSERV RELEASE instead of using the MVCL instruction for these reasons: - DSPSERV RELEASE is faster than MVCL for very large areas.
- Pages that are released through DSPSERV RELEASE do not occupy
space in real or auxiliary storage.
- DELETE
- Requests that the system delete a data space. STOKEN is the only
required parameter on the DELETE request. TTOKEN is optional.
A
problem state or key 8-F program can delete any data space it owns,
providing its PSW key matches the storage key of the data space.
A
supervisor state or key 0-7 program can delete any data space it owns
or created, if its home or primary address space is the same as the
owner's.
- 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 data space 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.
If
the caller is problem state with PSW key 8 through F, any TCB can
extend a data space that was created by any other TCB within the same
address space.
If the caller is in supervisor state with PSW
key 0 through 7, the TCB that represents the caller can be in any
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 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.
- OUT
- Tells the system that it can page some areas of a data space out
of central storage. When you specify OUT, you must also specify the
STOKEN, START, and BLOCKS parameters.
- PAGEFRAMESIZE=4K
- Backs data space virtual pages with 4 KB page frames at first
reference.
- PAGEFRAMESIZE=1M
- Backs data space virtual pages with pageable 1 MB page frames
at first reference. If pageable 1 MB page frames are not available
at first reference, 4K page frames are used. If DEFINE IOON is later
performed against pages backed with pageable 1 MB page frames, the
pages are always backed above 2 GB. PAGEFRAMESIZE=1M is only valid
for TYPE=BASIC data spaces. Refer to the BACK=64 and TYPE parameters
for additional information.
- ,BACK=31
- ,BACK=64
- Specifies the backing attributes of data space pages when defined
as IOON (fixed). Specifying ,BACK=31 backs the data space pages with
frames that reside below 2 gigabytes when defined IOON. Specifying
,BACK=64 backs the data space pages by frames that reside either above
or below 2 gigabytes when defined as IOON. Data spaces that are created
by specifying PAGEFRAMESIZE=1M can only be backed by frames that reside
above 2 gigabytes when defined as IOON. If ,BACK=31 is specified with
PAGEFRAMESIZE=1M, the ,BACK=31 specification is ignored and the MNOTE
ASMA254I message is generated, with the text PAGEFRAMESIZE=1M CANNOT
BE SPECIFIED WITH BACK=31.
- ,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 services.
- ,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
space can 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. IBM uses
the following names for data spaces and hiperspaces: - Names that begin with A through I.
- Names that begin with SYSAxxxx through SYSIxxxx.
- Names that begin with numbers or the characters SYSDS.
Use the following names for your data spaces:
To ensure that the names for your data spaces 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 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 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 data space name it generated 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 data space. The address must be
on a four-kilobyte boundary. START is required on RELEASE, LOAD, and
OUT 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 or the size of an area within
the data space.
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 then recompile the program to run on later releases of MVS™,
you must change the specification to BLOCKS=((register)) before
you recompile.
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 default is BLOCKS=0, setting the initial size and the
maximum size equal to the installation (or IBM) default.
For
a RELEASE request, BLOCKS is a required parameter that defines contiguous
storage (in blocks of 4K bytes) that the system is to release (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 of central storage.
For CREATE and EXPAND
requests, for data spaces created with PAGEFRAMESIZE=1M where the
BLOCKS specification does not result in the current size of the data
space being a multiple of 256 blocks, the current partial last segment
of the data space is backed by 4K pages at first reference. This ensures
that the user cannot access 4K pages beyond the current end of the
data space.
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 then recompile the program to run on later releases of MVS,
you must change the specification to BLOCKS=((register)) before
you recompile.
- ,DREF=NO
- ,DREF=YES
- Specifies whether (YES) or not (NO) disabled programs can reference
the data space. If you specify NO, only enabled programs can reference
the data space. If a disabled program references the data space,
the system might abend the program. If you specify YES, both an enabled
and a disabled program can reference the data space.
DREF is an
optional parameter when you create a data space. The default, DREF=NO,
specifies that only enabled programs can reference the data space.
- ,SCOPE=SINGLE
- ,SCOPE=ALL
- ,SCOPE=COMMON
- Specifies whether the data space is a SCOPE=SINGLE, SCOPE=ALL,
or a SCOPE=COMMON data space. A SCOPE=SINGLE data space may be referenced
only by the owning address space. SCOPE=ALL and SCOPE=COMMON data
spaces can be referenced by programs in many address spaces.
Any
program can create and delete SCOPE=SINGLE data spaces. Only supervisor
state or PSW key 0-7 programs can create and delete SCOPE=ALL and
SCOPE=COMMON data spaces.
The address space that contains an
owner of a SCOPE=ALL or SCOPE=COMMON data space must be nonswappable.
SCOPE
is an optional parameter for DSPSERV CREATE; the default is SCOPE=SINGLE.
- ,CALLERKEY
- ,KEY=key-addr
- Specifies the address of the eight-bit variable or constant that
contains the storage key of the data space to be created. The key
must be in bits 0-3 of the field. The system ignores bits 4-7. CALLERKEY
specifies that the data space have the storage key that matches the
PSW key of the caller.
The KEY parameter is optional on DSPSERV
CREATE. CALLERKEY is the default.
- ,FPROT=YES
- ,FPROT=NO
- Specifies whether the data space should (YES) or should not (NO)
be fetch-protected. If you specify YES, the entire data space is
fetch-protected. Fetch protection means a program must be in the
key of the data space storage (or key 0) to reference data in the
data space.
FPROT is an optional parameter for DSPSERV CREATE.
The default, FPROT=YES, specifies that the data space is fetch-protected.
- ,TTOKEN=ttoken-addr
- Specifies the address of the TTOKEN, the 16-byte variable or constant
that identifies the TCB that is (for the CREATE request) to become
the owner of the data space or is (for the DELETE request) the owner
of the data space. Use this parameter when you assign ownership of
a data space or when you delete a data space that belongs to another
task. A program can assign ownership of a data space only when it
creates it.
Before a program creates a data space and assigns ownership,
it must know the TTOKEN of the TCB that is to be the new owner. The
new owner must reside in the caller's home or primary address space.
If
you do not specify TTOKEN, the system assumes the caller is to be
the owner of the data space.
A problem state program with PSW
key 8 - F can use the TTOKEN parameter only on the CREATE request
and only to assign ownership to its own task or its job step task.
An
SRB cannot own a data space. It can create one, but it must assign
the data space to a TCB. The system abends SRB mode callers if they
do not include the TTOKEN parameter on create requests.
- ,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.
- ,VAR=YES
- ,VAR=NO
- 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 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 data space was created
- Rejects the request if the data space 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 data space.
- ,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
an input fullword that contains the address of the range list. The
range list consists of a number of entries (as specified by NUMRANGE)
where each entry is 8 bytes long. A mapping of each entry is provided
through the mapping macro IARDRL. If you specify DISABLED=YES or a
NUMRANGE value greater that 16, the range list must be in fixed storage.
- ,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, supplied through the RANGLIST parameter. For unauthorized
callers, the maximum value is 16. The default is 1. If you specify
INLIST=YES, you must specify RANGLIST.
- ,DISABLED=NO
- ,DISABLED=YES
- Specifies that the caller is enabled for I/O and external interrupts
(DISABLED=NO) or disabled for these interrupts (DISABLED=YES). DISABLED=NO
is the default.
DISABLED=YES is valid only with DSPSERV RELEASE
to release data space pages that reside in DREF storage. If you issue
RELEASE and DISABLED=YES for a non-DREF data space, you receive an
abend X'01D' with reason code X'020B'.
- ,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, supports all parameters except those specifically referenced
in higher versions.
- 1, supports all parameters from version 0 and the BLOCKS(Positional_2)
parameter.
To code, specify in this input parameter one of the
following: - IMPLIED_VERSION
- MAX
- A decimal value of 0-1.
- ,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 are shown
in the following table.
Table 1. Return and Reason
Codes for the DSPSERV CREATE MacroHexadecimal Return Code |
Hexadecimal Reason Code |
Meaning and Action |
---|
00 |
None |
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
exhausted. 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 are no longer exhausted.
See also the description
of the MAXCAD parameter in the IEASYSxx parmlib member in z/OS MVS Initialization and Tuning Reference.
|
0C |
xx0007xx |
Meaning: System error. The system cannot
obtain addressability to its data structures. Action: Record
the return and reason codes and supply them to the appropriate IBM support
personnel.
|
Hexadecimal return and reason codes from DSPSERV EXTEND are shown
in the following table.
Table 2. Return and Reason
Codes for the DSPSERV EXTEND MacroHexadecimal Return Code |
Hexadecimal Reason Code |
Meaning and Action |
---|
00 |
None |
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 10 MILLION BYTES OF STORAGE
DSPBLCKS DC A((DSPCSIZE+4095)/4096) NUMBER OF BLOCKS NEEDED FOR
* A 10 MILLION BYTE DATA SPACE
Example 2
Release 9 ranges of storage in a data space with a previously built
range list. 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
|