delete, and control hiperspaces. IBM MVS Programming: Authorized Assembler Services
โฆษณา
โฆษณา
Chapter 48. DSPSERV — Create, delete, and control hiperspaces
DSPSERV for data spaces
To control the use of data spaces, use the variation of the DSPSERV macro described
under Chapter 47, “DSPSERV — Create, delete, and control data spaces,” on page 583.
Description
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. A hiperspace can hold user data and programs stored as data. Data is not directly addressable; to manipulate data in a hiperspace, you use the HSPSERV macro to bring the data into the address space in blocks of 4K bytes.
Supervisor state or PSW key 0 through 7 programs have a choice of creating a standard hiperspace or an ESO hiperspace. The standard hiperspace is backed with real storage and auxiliary storage, if necessary. The HSTYPE=SCROLL parameter creates a standard hiperspace. The ESO hiperspace is backed only with real storage. HSTYPE=CACHE creates an ESO hiperspace. For more information on hiperspaces and how to use them, see z/OS MVS Programming: Extended
Addressability Guide. To learn the restrictions for the use of hiperspaces, see the description of the HSPSERV macro.
Use the DSPSERV macro to: v Create a hiperspace (CREATE parameter and TYPE=HIPERSPACE parameter) v Delete a hiperspace (DELETE parameter) v Release an area of a hiperspace (RELEASE parameter) v
Increase the current size of a hiperspace (EXTEND parameter)
DSPSERV is also described in z/OS MVS Programming: Assembler Services Reference
ABE-HSP, with the exception of the KEY, CALLERKEY, TTOKEN, HSTYPE,
SHARE, DISABLED, and CASTOUT parameters. These parameters are restricted to supervisor state or PSW key 0-7 programs.
Environment
Requirements for the caller are:
Environmental factor
Minimum authorization:
Requirement
To request the following DSPSERV services, a program must be supervisor state or PSW key 0-7: v Create and delete an ESO or a shared standard hiperspace v Release storage in a shared or ESO hiperspace v Extend the current size of a shared or ESO hiperspace v Assign a storage key to a hiperspace v Assign hiperspace ownership to a TCB
© Copyright IBM Corp. 1988, 2017
603
DSPSERV macro for hiperspaces
Environmental factor
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state programs with PSW key 8-F can request all other DSPSERV services.
Task or SRB
Any PASN, any HASN, any SASN
31-or 64-bit
Primary or access register (AR)
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 an ESO (HSTYPE=CACHE) hiperspace
No locks held, except the CPU lock if the caller specifies
DSPSERV RELEASE with DISABLED=YES to release an ESO
(HSTYPE=CACHE) hiperspace
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 disabled reference (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 the z/OS Internet library (www.ibm.com/systems/z/os/zos/library/ bkserv).
For information about programs in 64-bit addressing mode (AMODE 64), see z/OS
MVS Programming: Extended Addressability Guide.
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 if the return code in GPR 15 is not 0; otherwise, used as a work register by the system
1
2-13
Used as a work register by the system
Unchanged
604
z/OS MVS Authorized Assembler Services Reference ALE-DYN
Syntax
name
�
DSPSERV
�
DSPSERV macro for hiperspaces
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
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:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede DSPSERV.
CREATE
RELEASE
DELETE
EXTEND
,STOKEN=stoken-addr
,TYPE=HIPERSPACE
,HSTYPE=SCROLL
,HSTYPE=CACHE
One or more blanks must follow DSPSERV.
Valid parameters (Required parameters are underlined.)
STOKEN, NAME, TYPE, HSTYPE, CASTOUT, SHARE GENNAME,
OUTNAME, BLOCKS, CALLERKEY, KEY, FPROT, TTOKEN, ORIGIN, and
NUMBLKS
STOKEN, START, BLOCKS, INLIST, RANGLIST, NUMRANGE, DISABLED
STOKEN, TTOKEN
STOKEN, BLOCKS, VAR, NUMBLKS
stoken-addr: RX-type address or register (2) - (12).
Default:
HSTYPE=SCROLL
Chapter 48. DSPSERV — Create, delete, and control hiperspaces
605
DSPSERV macro for hiperspaces
Syntax
,SHARE=NO
,SHARE=YES
,CASTOUT=YES
,CASTOUT=NO
,NAME=name-addr
,GENNAME=NO
,GENNAME=COND
,GENNAME=YES
,OUTNAME=outname-addr
,START=start-addr
,BLOCKS=(max-addr,init-addr)
,BLOCKS=(max,init)
,BLOCKS=max
,BLOCKS=(0,init)
,BLOCKS=0
,BLOCKS=(0,init-addr)
,BLOCKS=(size-addr)
,BLOCKS=(size)
,CALLERKEY
,KEY=key-addr
,FPROT=YES
,FPROT=NO
,TTOKEN=ttoken-addr
,ORIGIN=origin-addr
,NUMBLKS=numblks-addr
,INLIST=NO
,INLIST=YES
Description
Default:
SHARE=NO
Note:
SHARE is valid only if you specify HSTYPE=SCROLL.
Default:
CASTOUT=YES
Note:
CASTOUT is valid only if you specify HSTYPE=CACHE.
name-addr: RX-type address or register (2) - (12).
Default:
GENNAME=NO
outname-addr: RX-type address or register (2) - (12).
start-addr: RX-type address or register (2) - (12).
max-addr: RX-type address or register (2) - (12).
init-addr: RX-type address or register (2) - (12).
max: Number up to 524288.
init: Number up to 524288.
0 specifies the installation default size.
Default for CREATE:
BLOCKS=0
size-addr: RX-type address or register (2) - (12).
size: Number up to 524288.
Default
: CALLERKEY
key-addr: RX-type address or register (2) - (12).
Default:
FPROT=YES
ttoken-addr: RX-type address or register (2) - (12).
origin-addr: RX-type address or register (2) - (12).
numblks-addr: RX-type address or register (2) - (12).
Default:
INLIST=NO
606
z/OS MVS Authorized Assembler Services Reference ALE-DYN
DSPSERV macro for hiperspaces
Syntax
,RANGLIST=rangelist_addr
,NUMRANGE=numrange_addr
Description
rangelist_addr: RS-type address or register (2) - (12). Required with
INLIST=YES
numrange_addr: RS-type address or register (2) - (12). Default:
NUMRANGE=1
,VAR=NO
,VAR=YES
,DISABLED=NO
,DISABLED=YES
Default:
VAR=NO
,PLISTVER=IMPLIED_VERSION
Default:
IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver plistver: 0
,MF=S
Default:
DISABLED=NO
Note:
DISABLED=YES is valid only if you specify DSPSERV RELEASE with
HSTYPE=CACHE.
The CREATE, RELEASE, DELETE, and EXTEND 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 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 the
NAME, TYPE=HIPERSPACE, and STOKEN parameters. To create an ESO or a shared standard hiperspace, your program must be supervisor state or have
PSW key 0 - 7.
Optional parameters when you create a hiperspace are: HSTYPE, CASTOUT,
GENNAME, OUTNAME, BLOCKS, KEY, CALLERKEY, FPROT, TTOKEN,
ORIGIN, SHARE, 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.
A problem state or PSW key 8 - F caller must own the hiperspace, and its PSW key must be zero or equal to the key of the storage the system is to release. A supervisor state or PSW key 0 - 7 caller must have its home or primary
Chapter 48. DSPSERV — Create, delete, and control hiperspaces
607
DSPSERV macro for hiperspaces
address space the same as the owner's home address space, and its PSW key must be zero or equal to the key of the storage the system is to release.
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 an ESO
(HSTYPE=CACHE) hiperspace.
Pages that are released through DSPSERV RELEASE do not occupy space in real 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. TTOKEN is optional.
A problem state or key 8-F program can delete any hiperspace it owns and for which its PSW key matches the key of the hiperspace.
A supervisor state or key 0-7 program can delete any hiperspace it owns and other hiperspaces, 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 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.
If the caller is problem state and PSW key 8 through F, it must own the hiperspace. Otherwise, the TCB that represents the caller must be in the home or primary address of the owner of the hiperspace.
The system rejects the EXTEND request if you specified VAR=NO (or took the default) and the extended size would: v Exceed the maximum size specified when the hiperspace was created.
v
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. DSPSERV
CREATE returns the STOKEN as output. STOKEN is required input for all other DSPSERV requests.
,TYPE=HIPERSPACE
Specifies that the system is to create a hiperspace rather than a data space.
,HSTYPE=SCROLL
,HSTYPE=CACHE
Specifies the type of hiperspace the system is to create: HSTYPE=SCROLL creates a standard hiperspace, the type of storage area that your program can scroll through. HSTYPE=CACHE creates an ESO hiperspace, one that acts as a high-speed cache for storing data. HSTYPE=SCROLL is the default.
608
z/OS MVS Authorized Assembler Services Reference ALE-DYN
DSPSERV macro for hiperspaces
,SHARE=NO
,SHARE=YES
Specifies whether the system is to create a nonshared standard hiperspace
(SHARE=NO) or a shared standard hiperspace (SHARE=YES). This parameter is valid only if you specify HSTYPE=SCROLL. When you specify
HSTYPE=SCROLL, SHARE=NO is the default.
Generally, a program can share a nonshared standard hiperspace only with programs that are dispatched in the owner's home address space. However, a program not dispatched in the owner's home address space and using an
ALET, can access this nonshared standard hiperspace through the owner's home PASN-AL. A program can share a shared standard hiperspace with programs that are dispatched in any address space.
,CASTOUT=YES
,CASTOUT=NO
Specifies that the system is to persist (CASTOUT=NO) or not persist
(CASTOUT=YES) in retaining a copy of the data in the hiperspace. The
CASTOUT parameter is valid only if you specify HSTYPE=CACHE. When you specify HSTYPE=CACHE, CASTOUT=YES is the default.
When the system needs the real storage for its own needs, it is less likely to take the real storage from a hiperspace created with CASTOUT=NO than from one created with CASTOUT=YES.
CASTOUT=YES indicates that the system can discard the data when it needs the real storage for other purposes. CASTOUT=NO specifies that the system is to give the data in the ESO hiperspace more priority when searching for pages to remove from real storage when a shortage arises.
Note:
Specifying CASTOUT=NO places a heavy demand on real storage. The system might discard the pages regardless of CASTOUT=NO. For example, if the system swaps out the address space that owns the hiperspace, it discards pages without regard to CASTOUT. (To prevent the loss due to a swapped-out address space, make the address space that owns the hiperspace nonswappable.)
,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.
Names of hiperspaces and data spaces 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 uses for data spaces and hiperspaces. IBM uses the following names: v Names that begin with A through I.
v Names that begin with SYSAxxxx through SYSIxxxx.
v Names that begin with numbers or the characters SYSDS.
Use the following names for your hiperspaces: v Problem state programs can 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.
Chapter 48. DSPSERV — Create, delete, and control hiperspaces
609
DSPSERV macro for hiperspaces
|
|
|
|
|
|
|
|
| v Supervisor state programs and programs with PSW key 0 - 7 can use hiperspace names that begin with @, #, $, or the letters I through Z. In addition, they can use names that begin with SYSJ through SYSZ. The system abends programs that begin names with SYSDS.
Use names that begin with SYSJ through SYSZ to ensure that the names of the hiperspaces that belong to supervisor state programs and programs with
PSW key 0 - 7 do not conflict with the names of hiperspaces that belong to problem state programs.
To ensure that the names for your hiperspaces 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 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 (or the whole name if it has three or fewer characters). 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 keyword and makes it unique.
Note:
The maximum number of system generated names is 99,999. If all system-generated names are used, DSPSERV reuses generated names from previously deleted data spaces or hiperspaces. If all system-generated names are in use for active data spaces or hiperspaces, DSPSERV fails with return code 8 and reason code 0012.
Before we reach the maximum number of system-generated names, the counter will not be reset to zero until all data spaces and hiperspaces within the address space are deleted. The generated names counter are reset to zero when the job is recycled.
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 generates for 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
610
z/OS MVS Authorized Assembler Services Reference ALE-DYN
DSPSERV macro for hiperspaces
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 address of a four-byte variable that contains the size of the hiperspace or the size of an area within the hiperspace.
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 default is 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 to the current size of the hiperspace.
,CALLERKEY
,KEY=key-addr
Specifies the address of the eight-bit variable or constant that contains the storage key of the hiperspace to be created. The key must be in bits 0-3 of the field. The system ignores bits 4-7. CALLERKEY specifies that the hiperspace is to 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 hiperspace should (YES) or should not (NO) be fetch-protected. If you specify YES, the entire hiperspace is fetch-protected.
Chapter 48. DSPSERV — Create, delete, and control hiperspaces
611
DSPSERV macro for hiperspaces
Fetch protection means a program must be in the key of the hiperspace storage
(or key 0) to reference data in the hiperspace.
FPROT is an optional parameter for DSPSERV CREATE. The default,
FPROT=YES, specifies that the hiperspace 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 hiperspace or is (for the DELETE request) the owner of the hiperspace. Use this parameter when you assign ownership of a hiperspace or when you delete a hiperspace that belongs to another task. A program can assign ownership of a hiperspace only when it creates it.
Before a program creates a hiperspace 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 the owner.
An SRB cannot own a hiperspace. A program that the SRB represents can create one, but it must assign the hiperspace 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 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: v For DSPSERV CREATE, the maximum size (in blocks) of the newly-created hiperspace v 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.
,VAR=YES
,VAR=NO
Specifies whether or not 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 the amount you request because that amount might cause the system to exceed one of the following: v The maximum size of the hiperspace, as specified on the BLOCKS parameter when the hiperspace was created.
v 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.)
612
z/OS MVS Authorized Assembler Services Reference ALE-DYN
DSPSERV macro for hiperspaces
If you specify VAR=YES (the variable request) and the system is unable to satisfy the request, the system extends the hiperspace to one of the following sizes, depending on which is smaller: v The maximum size specified on the BLOCKS parameter when the hiperspace was created v 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: v Abends the caller if the extended size would exceed the maximum size specified when the hiperspace was created v 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.
,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 an ESO
(HSTYPE=CACHE) hiperspace. If you issue RELEASE and DISABLED=YES for a standard (HSTYPE=SCROLL) hiperspace, 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:
Chapter 48. DSPSERV — Create, delete, and control hiperspaces
613
DSPSERV macro for hiperspaces
v 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.
v 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.
v 0 , if you use the currently available parameters.
To code
, specify in this input parameter one of the following: v
IMPLIED_VERSION v MAX v 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 more information.
Return and reason codes
Hexadecimal return and reason codes from DSPSERV CREATE are shown in the following table.
Table 59. Return and Reason Codes for the DSPSERV CREATE Macro
Hexadecimal Return
Code
00
Hexadecimal Reason
Code
None
Meaning and Action
Meaning
: DSPSERV CREATE completed successfully.
04
08 xx000Cxx xx0005xx
Action
: None.
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.
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.
614
z/OS MVS Authorized Assembler Services Reference ALE-DYN
DSPSERV macro for hiperspaces
Table 59. Return and Reason Codes for the DSPSERV CREATE Macro (continued)
Hexadecimal Return
Code
08
Hexadecimal Reason
Code
xx0009xx
Meaning and Action
Meaning
: Program error. The specified hiperspace name is not unique within the address space.
08
08
0C
0C xx0010xx xx0012xx xx0006xx xx0007xx
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.
Meaning
: Environmental error. ESO hiperspace creation was rejected because there is no real storage on the system.
Action
: Determine if an ESO hiperspace is required. If not, modify the program to specify a standard rather than an ESO hiperspace. If an
ESO hiperspace is required, run the program on another system with real storage installed.
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 resources are no longer exhausted.
Meaning
: Environmental error. The system cannot create any additional hiperspaces 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.
Meaning
: System error. The system cannot obtain addressability to its own hiperspaces.
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 60. Return and Reason Codes for the DSPSERV EXTEND Macro
Hexadecimal Return
Code
00
Hexadecimal Reason
Code
None
Meaning and Action
Meaning
: DSPSERV EXTEND completed successfully.
Action
: None.
Chapter 48. DSPSERV — Create, delete, and control hiperspaces
615
DSPSERV macro for hiperspaces
Table 60. Return and Reason Codes for the DSPSERV EXTEND Macro (continued)
Hexadecimal Return
Code
08
Hexadecimal Reason
Code
xx0502xx
Meaning and Action
Meaning
: Environmental error. Extending the hiperspace size would cause the data space and hiperspace limits for the address space to be exceeded.
08 xx0503xx
Action
: Check with your system programmer, who might be able to tune the system so that the function is made available to your program.
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 1
Create a hiperspace named TEMP with a size of 10 million bytes.
DSP1 DSPSERV CREATE,NAME=HSPCNAME,STOKEN=HSPCSTKN,
TYPE=HIPERSPACE,BLOCKS=HSPBLCKS,ORIGIN=HSPCORG
* .
HSPCNAME DC CL8’TEMP
HSPCSTKN DS CL8
HSPCORG DS F
’ HIPERSPACE NAME
HIPERSPACE STOKEN
HIPERSPACE ORIGIN RETURNED
HSPCSIZE EQU 10000000
HSPBLCKS DC A((HSPCSIZE+4095)/4096) NUMBER OF BLOCKS NEEDED FOR
* A 10 MILLION BYTE HIPERSPACE
X
Example 2
Release 9 ranges of storage in a data space with a previously built range list.
DSP2
LA
ST
5,RANGELST
5,RNGLSTPT
LA, 5,RNGLSTPT
DSPSERV RELEASE,STOKEN=DSPCSTKN,DISABLED=NO,INLIST=YES,
NUMRANGE=NUMRANGS,RANGLIST=(5)
*
RNGLSTPT DS F
DSPCSTKN DS CL8
NUMRANGS DC F’9’
RANGELST DS CL256
DRLMAP DS 0F
IARDRL
RANGE LIST ADDRESS
DATA SPACE STOKEN
NUMBER OF RANGES TO PROCESS
STORAGE FOR MAX NUMBER OF RANGES
THIS CREATES A DSECT
MAPPING MACRO
DSPSERV - List form
Use the list form of the DSPSERV macro to construct a nonexecutable control program parameter list.
616
z/OS MVS Authorized Assembler Services Reference ALE-DYN
DSPSERV macro for hiperspaces
Syntax
The list form of the DSPSERV macro is written as follows:
Description Syntax
�
name
name: Symbol. Begin name in column 1.
One or more blanks must precede DSPSERV.
DSPSERV
� One or more blanks must follow DSPSERV.
,PLISTVER=IMPLIED_VERSION
Default:
IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver plistver: 0
,MF=(L,list addr)
,MF=(L,list addr,attr)
list addr: Symbol.
attr: 1- to 60-character input string. Default: 0D
Parameters
The parameters are explained as follows:
,MF=(L,list addr)
,MF=(L,list addr,attr)
Specifies the list form of the DSPSERV macro. list addr defines the area that the system is to use for the parameter list.
attr is an optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
DSPSERV - Execute form
The execute form of the DSPSERV macro can refer to and modify the parameter list constructed by the list form of the macro.
Syntax
Syntax
The execute form of the DSPSERV macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede DSPSERV.
Chapter 48. DSPSERV — Create, delete, and control hiperspaces
617
DSPSERV macro for hiperspaces
Description Syntax
DSPSERV
�
CREATE
One or more blanks must follow DSPSERV.
Valid parameters (Required parameters are underlined.)
STOKEN, NAME, TYPE, HSTYPE, SHARE, CASTOUT, GENNAME,
OUTNAME, BLOCKS, CALLERKEY, KEY, FPROT, TTOKEN, ORIGIN, and
NUMBLKS
STOKEN, START, BLOCKS, INLIST, RANGLIST, NUMRANGE, DISABLED
STOKEN, TTOKEN
STOKEN, BLOCKS, VAR, NUMBLKS
stoken-addr: RX-type address or register (2) - (12).
RELEASE
DELETE
EXTEND
,STOKEN=stoken-addr
,TYPE=HIPERSPACE
,HSTYPE=SCROLL
,HSTYPE=CACHE
,SHARE=NO
,SHARE=YES
,CASTOUT=YES
,CASTOUT=NO
,NAME=name-addr
,GENNAME=NO
,GENNAME=COND
,GENNAME=YES
,OUTNAME=outname-addr
,START=start-addr
,BLOCKS=(max-addr,init-addr)
,BLOCKS=(max,init)
,BLOCKS=max
,BLOCKS=(0,init)
,BLOCKS=0
Default:
HSTYPE=SCROLL
Default:
SHARE=NO
Note:
SHARE is valid only if you specify HSTYPE=SCROLL.
Default:
CASTOUT=YES
Note:
CASTOUT is valid only if you specify HSTYPE=CACHE.
name-addr: RX-type address or register (2) - (12).
Default:
GENNAME=NO
outname-addr: RX-type address or register (2) - (12).
start-addr: RX-type address or register (2) - (12).
max-addr: RX-type address or register (2) - (12).
init-addr: RX-type address or register (2) - (12).
max: Number up to 524288.
init: Number up to 524288.
0 specifies the installation default size.
618
z/OS MVS Authorized Assembler Services Reference ALE-DYN
DSPSERV macro for hiperspaces
Syntax
,BLOCKS=(0,init-addr)
,BLOCKS=(size-addr)
,BLOCKS=(size)
,KEY=key-addr
,CALLERKEY
,FPROT=YES
,FPROT=NO
,TTOKEN=ttoken-addr
,ORIGIN=origin-addr
,NUMBLKS=numblks-addr
Description
Default for CREATE:
BLOCKS=0
size-addr: RX-type address or register (2) - (12).
size: Number up to 524288.
key-addr: RX-type address or register (2) - (12).
Default
: CALLERKEY
Default:
FPROT=YES
ttoken-addr: RX-type address or register (2) - (12).
origin-addr: RX-type address or register (2) - (12).
numblks-addr: RX-type address or register (2) - (12).
Default:
INLIST=NO ,INLIST=NO
,INLIST=YES
,RANGLIST=rangelist-addr
,NUMRANGE=numrange-addr
rangelist-addr: RS-type address or register (2) - (12). Required with
INLIST=YES.
numrange-addr: RS-type address or register (2) - (12). Default:
NUMRANGE=1
,VAR=NO
,VAR=YES
,DISABLED=NO
,DISABLED=YES
Default:
VAR=NO
Default:
DISABLED=NO
Note:
DISABLED=YES is valid only if you specify DSPSERV RELEASE with
HSTYPE=CACHE.
,PLISTVER=IMPLIED_VERSION
Default:
IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver plistver: 0
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
list addr: RX-type address or register (2) - (12).
Chapter 48. DSPSERV — Create, delete, and control hiperspaces
619
DSPSERV macro for hiperspaces
Parameters
The parameters are explained under the standard form of the DSPSERV macro with the following exception:
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Specifies the execute form of the DSPSERV macro. list addr defines the area that the system uses for the parameter list.
COMPLETE specifies that the system is to check for required parameters and supply optional parameters that are not specified.
620
z/OS MVS Authorized Assembler Services Reference ALE-DYN
ดาวน์โหลด
ลิงก์สาธารณะได้รับการอัปเดตแล้ว
ลิงก์สาธารณะไปยังแชทของคุณได้รับการอัปเดตแล้ว You may view and manage your chat links after registration here.
ลิงก์สาธารณะของเอกสาร
โฆษณา
