message. IBM MVS Programming: Authorized Assembler Services

PDF

Документ

Chapter 46. DOM — Delete operator message

Description

The DOM macro deletes an operator message or group of messages from the display screen of the operator's console and from the list of messages retained by

MVS. When a program no longer requires that a message be displayed or retained, it issues the DOM macro to delete the message.

When a program issues a WTO or WTOR macro, the system assigns an identification number to the message and returns this number in register 1 to the issuing program. When the display of this message is no longer needed, the issuing program can issue the DOM macro using the identification number that was returned in register 1.

MVS automatically invokes DOM for a WTOR when it receives the WTOR reply.

You need only invoke DOM for a WTOR if the WTOR becomes obsolete before the system receives the reply. When the system receives the reply, the message is no longer highlighted on the MCS console screen. The message is eventually removed from the screen of an MCS console.

Environment

The requirements for the caller are different for LINKAGE=SVC and

LINKAGE=BRANCH.

If you specify LINKAGE=SVC, the requirements for the caller are:

Environmental factor

Minimum authorization:

Dispatchable unit mode:

Cross memory mode:

AMODE:

ASC mode:

Interrupt Status:

Locks:

Control parameters:

Requirement

Supervisor state or problem state and any PSW key

Task

PASN=HASN=SASN

24- or 31- or 64-bit

Primary

Enabled for I/O and external interrupts

No locks held

Must be in the primary address space

If you specify LINKAGE=BRANCH, the requirements for the caller are:

Environmental factor

Minimum authorization:

Dispatchable unit mode:

Cross memory mode:

AMODE:

ASC mode:

Interrupt Status:

Locks:

Control parameters:

Requirement

Supervisor state with PSW key 0-7

Task or SRB

Any PASN, any HASN, any SASN

24- or 31-bit

Primary

Enabled or disabled for I/O and external interrupts

The caller may hold locks, but is not required to hold any

Must be in the primary address space.

Programming requirements

None.

577

DOM macro

Syntax

Restrictions

The following restrictions and limitations apply: v If the caller is executing in a sysplex, do not use SCOPE=SYSTEM, but rather

SCOPE=SYSTEMS. DOM ignores SCOPE=SYSTEM if the caller is executing in a sysplex.

v For any DOM parameters that allow a register specification, the value must be right-justified in the register, and the remaining bytes within the register must be zero.

v Any authorized DOM parameters that are specified by an unauthorized program will cause a 157 abend. The only authorized parameter is SCOPE.

Register information

After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

When control returns to the caller, the general purpose registers (GPRs) contain:

Register

Contents

0-1

Used as work registers by the system

2-13

Unchanged

Used as a work register by the system

Return code if you specified LINKAGE=BRANCH; otherwise, used as a work register by the system.

Performance implications

None.

Syntax

The DOM macro is written as follows:

Description

⌂

name

name: Symbol. Begin name in column 1.

One or more blanks must precede DOM.

DOM

⌂ One or more blanks must follow DOM.

MSG=field

MSGLIST=list addr

field: Four-byte value

list addr: Symbol, RX-type address, or register (1) - (12).

578

z/OS MVS Authorized Assembler Services Reference ALE-DYN

DOM macro

Syntax

TOKEN=addr

,COUNT=count addr

,SCOPE=SYSTEM

,SCOPE=SYSTEMS

,LINKAGE=SVC

,LINKAGE=BRANCH

Description

addr: Register (1) - (12), or an RX-type address.

count addr: Register (2) - (12), or an RX-type address.

Default:

SCOPE=SYSTEMS

Default:

LINKAGE=SVC

Parameters

The parameters are explained as follows:

MSG=field

MSGLIST=list addr

TOKEN=addr

MSG=field specifies in register 1 the ID of a single message to be deleted.

Register 1 contains the 32-bit identification number (the DOM id) of a WTO message to be deleted. Use this as input on the MSG parameter.

MSGLIST=list addr specifies the address of a list of one or more fullwords, each word containing the 32-bit identification number of a message to be deleted.

You can end the list in one of two ways: v Use the COUNT parameter to specify how many entries are in the list.

v Turn on the high-order bit in the last entry of the list.

Attention:

Do not alter a DOM id from the 32-bit value returned in register 1 by the WTO or WTOR macro, except to turn on the high-order bit (x'80000000') in the last entry in a list.

Note:

MSGLIST identification numbers of zero (0), while counted against the maximum allowed of sixty (60), are ignored and not processed in any way (i.e.

not presented to any exits or the SSI and not sent to other systems).

TOKEN=addr specifies a field or register containing a 4-byte token that is associated with messages to be deleted. When you issue WTO or WTOR to write a message, you can choose a token value, and specify it as an input parameter to WTO or WTOR through the TOKEN parameter. To issue a DOM using a TOKEN, ignore the message ID returned by WTO or WTOR in register

1, and specify the token value instead, using the TOKEN parameter when you issue DOM. TOKEN is an alternate method for identifying messages, which is independent of the register 1 message ID. Specifying TOKEN with DOM will delete all messages specified with WTO and that particular TOKEN.

With TOKEN, authorized users may delete any messages originally issued under the same ASID and system ID. Unauthorized users may delete only those messages that were originally issued under the same jobstep TCB, ASID, and system ID. The value of the token may not be the same as the ID that was returned in register 1 after a WTO or WTOR. TOKEN is mutually exclusive with MSG, MSGLIST, and COUNT.

Chapter 46. DOM — Delete operator message

579

DOM macro

,COUNT=count addr

Specifies a field or register containing the 1-byte count of 4-byte message IDs associated with this request. The count must be from 1 to 60. If you specify

COUNT, do not set the high-order bit on in the last entry of the DOM parameter list. If you specify COUNT in a register, ensure that it is right-justified and padded with zeros. If you do not specify COUNT, the message IDs are treated as 32-bit IDs. If an address is used, the address points to a 1-byte field that contains the count. COUNT is not valid with TOKEN.

,SCOPE=SYSTEM

,SCOPE=SYSTEMS

Specifies how to process the DOM request. If you specify SCOPE=SYSTEMS, the DOM request is to be communicated to other processors. If you specify

SCOPE=SYSTEM, the DOM request is not to be communicated to other processors. If you do not specify SCOPE, the DOM request defaults to

SCOPE=SYSTEMS.

You must specify SCOPE=SYSTEMS if you are running in a sysplex.

,LINKAGE=SVC

,LINKAGE=BRANCH

Specifies how DOM will receive control. LINKAGE=SVC specifies that linkage is by supervisor call, and LINKAGE=BRANCH specifies that linkage is by branch and link. LINKAGE=SVC is the default.

Use LINKAGE=BRANCH when you cannot issue an SVC.

Return and reason codes

LINKAGE=BRANCH:

Table 56. Return Codes for the DOM LINKAGE=BRANCH Macro

Hexadecimal Return

Code

Meaning

Meaning:

For LINKAGE=BRANCH, processing completed successfully. The system has accepted the request and will perform the deletion later.

Meaning:

You issued DOM with LINKAGE=BRANCH, but the system could not obtain necessary storage. No processing was done.

Meaning:

You issued DOM with LINKAGE=BRANCH, but the system was unable to obtain storage for processing. No processing was done. This return code can occur as a result of unexpected error conditions in system storage.

There are no return codes from DOM LINKAGE=SVC.

Example 1

Issue a DOM by ID. The ID is in register 2.

R2 EQU 2

DOM MSG=(R2)

Example 2

Issue a DOM by token.

DOM TOKEN=READER

READER DC F’00000320’

580

z/OS MVS Authorized Assembler Services Reference ALE-DYN

DOM macro

Example 3

Issue a DOM by a list of IDs. The count is specified in a register. Use the branch-entry form of the macro.

R7 EQU 7

L R7,CURCOUNT NUMBER OF ENTRIES IN LIST

DOM MSGLIST=MYLIST,COUNT=(R7),SCOPE=SYSTEMS,LINKAGE=BRANCH

CURCOUNT DS

MYLIST DS

60F

Chapter 46. DOM — Delete operator message

581

DOM macro

582

z/OS MVS Authorized Assembler Services Reference ALE-DYN

Chapter 47. DSPSERV — Create, delete, and control data spaces

DSPSERV for hiperspaces

To control the use of hiperspaces, use the variation of the DSPSERV macro described

under Chapter 48, “DSPSERV — Create, delete, and control hiperspaces,” on page 603.

Description

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: v

Create a data space (CREATE parameter and TYPE=BASIC parameter) v Delete a data space (DELETE parameter) v Release an area of a data space (RELEASE parameter) v Increase the current size of a data space (EXTEND parameter) v Load an area of a data space into central storage (LOAD parameter) v Take (that is, page out) from central storage an area of a data space (OUT parameter) v 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.

583

DSPSERV macro for data spaces

Environment

The 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 a data space with disabled referenced (DREF) storage or fetch protected (FPROT) storage v Create and delete a SCOPE=ALL and SCOPE=COMMON data space v Assign a storage key to a data space v Load an area of a SCOPE=ALL or SCOPE=COMMON data space into central storage v Page out of central storage an area of a SCOPE=ALL or

SCOPE=COMMON data space v Extend the current size of a data space it does not own

Dispatchable unit mode:

Cross memory mode:

AMODE:

ASC mode:

Interrupt status:

Locks:

Control parameters:

Problem state programs with PSW key 8-F can request all other DSPSERV services for data spaces.

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 data space pages that reside in

DREF storage

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

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 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.

584

z/OS MVS Authorized Assembler Services Reference ALE-DYN

⌂

Syntax

name

DSPSERV macro for data spaces

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

Reason code if the return code in GPR 15 is not 0; otherwise, used as a work register by the system

Used as a work register by the system

2-13

Unchanged

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.

DSPSERV

One or more blanks must follow DSPSERV.

Valid parameters (Required parameters are underlined.)

Chapter 47. DSPSERV — Create, delete, and control data spaces

585

DSPSERV macro for data spaces

Syntax

CREATE

RELEASE

DELETE

EXTEND

LOAD

OUT

PAGEFRAMESIZE=4K

PAGEFRAMESIZE=1M

,STOKEN=stoken-addr

,TYPE=BASIC

,NAME=name-addr

,GENNAME=NO

,GENNAME=COND

,GENNAME=YES

,OUTNAME=outname-addr

,START=start-addr

,BACK=31

,BACK=64

,BLOCKS=(max-addr,init-addr)

,BLOCKS=(max,init)

,BLOCKS=max

,BLOCKS=(0,init)

,BLOCKS=0

,BLOCKS=(0,init-addr)

,BLOCKS=(size-addr)

,BLOCKS=(size)

,DREF=NO

,DREF=YES

Description

STOKEN, NAME, TYPE, GENNAME, OUTNAME, BLOCKS, DREF, SCOPE,

CALLERKEY, KEY, FPROT, TTOKEN, ORIGIN, NUMBLKS,BACK,

PAGEFRAMESIZE

STOKEN, START, BLOCKS, INLIST, RANGLIST, NUMRANGE, DISABLED

STOKEN, TTOKEN

STOKEN, BLOCKS, VAR, NUMBLKS

STOKEN, START, BLOCKS

Default:

PAGEFRAMESIZE=4K

stoken-addr: RX-type address or register (2) - (12).

Default:

TYPE=BASIC

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).

Default:

BACK=31 (for PAGEFRAMESIZE=4K)

Default:

BACK=64 (for PAGEFRAMESIZE=1M)

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:

DREF=NO

586

z/OS MVS Authorized Assembler Services Reference ALE-DYN

DSPSERV macro for data spaces

Syntax

,SCOPE=SINGLE

,SCOPE=ALL

,SCOPE=COMMON

,CALLERKEY

,KEY=key-addr

,FPROT=YES

,FPROT=NO

,TTOKEN=ttoken-addr

,ORIGIN=origin-addr

,NUMBLKS=numblks-addr

Description

Default:

Default

Default:

SCOPE=SINGLE

: CALLERKEY

key-addr: RX-type address or register (2) - (12).

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

Default:

VAR=NO ,VAR=NO

,VAR=YES

,DISABLED=NO

,DISABLED=YES

Default:

DISABLED=NO

,PLISTVER=IMPLIED_VERSION

Default:

IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=plistver plistver: 0

Default:

HIDEZERO=NO ,HIDEZERO=NO

,HIDEZERO=YES

,MF=S

Chapter 47. DSPSERV — Create, delete, and control data spaces

587

DSPSERV macro for data spaces

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: v 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

588

z/OS MVS Authorized Assembler Services Reference ALE-DYN

DSPSERV macro for data spaces

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: v Exceed the maximum size specified when the data space was created.

v 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.

Chapter 47. DSPSERV — Create, delete, and control data spaces

589

DSPSERV macro for data spaces

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: 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 data spaces: v Problem state programs can 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.

Supervisor state programs and programs with PSW key 0 - 7 can use data space names that begin with @, #, $, or the letters J 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 data spaces that belong to supervisor state programs and programs with

PSW key 0 - 7 do not conflict with the names of data spaces that belong to problem state programs.

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.

590

z/OS MVS Authorized Assembler Services Reference ALE-DYN

DSPSERV macro for data spaces

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.

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 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.

Chapter 47. DSPSERV — Create, delete, and control data spaces

591

DSPSERV macro for data spaces

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

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.

592

z/OS MVS Authorized Assembler Services Reference ALE-DYN

DSPSERV macro for data 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.

Chapter 47. DSPSERV — Create, delete, and control data spaces

593

DSPSERV macro for data spaces

,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 data space v 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: v The maximum size of the data space, as specified on the BLOCKS parameter when the data space was created.

v 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: v The maximum size specified on the BLOCKS parameter when the data space 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 data space was created v 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

594

z/OS MVS Authorized Assembler Services Reference ALE-DYN

DSPSERV macro for data spaces

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: 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

, supports all parameters except those specifically referenced in higher versions.

v 1 , supports all parameters from version 0 and the BLOCKS(Positional_2) parameter.

To code

, specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v 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.

Chapter 47. DSPSERV — Create, delete, and control data spaces

595

DSPSERV macro for data spaces

v 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 57. Return and Reason Codes for the DSPSERV CREATE Macro

Hexadecimal

Return Code

Hexadecimal

Reason Code

None

Meaning and Action

Meaning

: DSPSERV CREATE completed successfully.

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 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.

Meaning

: Program error. Creation of the data space would violate installation criteria. See the IEFUSI installation exit in z/OS MVS Installation Exits.

08 xx0009xx xx0012xx

Action

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

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.

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.

596

z/OS MVS Authorized Assembler Services Reference ALE-DYN

DSPSERV macro for data spaces

Table 57. Return and Reason Codes for the DSPSERV CREATE Macro (continued)

Hexadecimal

Return Code

Hexadecimal

Reason Code

xx0006xx

Meaning and Action

Meaning

: Environmental error. The system cannot create any additional data spaces at this time because of a shortage of resources.

0C xx0007xx

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.

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 58. Return and Reason Codes for the DSPSERV EXTEND Macro

Hexadecimal

Return Code

Hexadecimal

Reason Code

None

Meaning and Action

Meaning

: DSPSERV EXTEND completed successfully.

08 xx0502xx xx0503xx

Action

: None.

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.

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

DSPCSTKN DS CL8

DSPCORG DS F

DSPCSIZE EQU 10000000

’ DATA SPACE NAME

DATA SPACE STOKEN

DATA SPACE ORIGIN RETURNED

10 MILLION BYTES OF STORAGE

DSPBLCKS DC A((DSPCSIZE+4095)/4096) NUMBER OF BLOCKS NEEDED FOR

* A 10 MILLION BYTE DATA SPACE

Chapter 47. DSPSERV — Create, delete, and control data spaces

597

DSPSERV macro for data spaces

Example 2

Release 9 ranges of storage in a data space with a previously built range list.

DSP2

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’

RANGE LIST ADDRESS

DATA SPACE STOKEN

NUMBER OF RANGES TO PROCESS

RANGELST DS CL256

DRLMAP DS 0F

IARDRL

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.

Syntax

The list 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.

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

598

z/OS MVS Authorized Assembler Services Reference ALE-DYN

DSPSERV macro for data spaces

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

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

Description

name

�

DSPSERV

�

name: Symbol. Begin name in column 1.

One or more blanks must precede DSPSERV.

CREATE

RELEASE

DELETE

EXTEND

LOAD

OUT

,STOKEN=stoken-addr

,TYPE=BASIC

,NAME=name-addr

,GENNAME=NO

,GENNAME=COND

,GENNAME=YES

,OUTNAME=outname-addr

PAGEFRAMESIZE=4K

PAGEFRAMESIZE=1M

One or more blanks must follow DSPSERV.

Valid parameters (Required parameters are underlined.)

STOKEN, NAME, TYPE, GENNAME, OUTNAME, BLOCKS, DREF, SCOPE,

CALLERKEY, KEY, FPROT, TTOKEN, ORIGIN, NUMBLKS, BACK,

PAGEFRAMESIZE

STOKEN, START, BLOCKS, INLIST, RANGLIST, NUMRANGE, DISABLED

STOKEN, TTOKEN

STOKEN, BLOCKS, VAR, NUMBLKS

STOKEN, START, BLOCKS

stoken-addr: RX-type address or register (2) - (12).

Default:

TYPE=BASIC

name-addr: RX-type address or register (2) - (12).

Default:

GENNAME=NO

outname-addr: RX-type address or register (2) - (12).

Default

: PAGEFRAMESIZE=4K

Chapter 47. DSPSERV — Create, delete, and control data spaces

599

DSPSERV macro for data spaces

Syntax

,START=start-addr

,BACK=31

,BACK=64

,BLOCKS=(max-addr,init-addr)

,BLOCKS=(max,init)

,BLOCKS=max

,BLOCKS=(0,init)

,BLOCKS=0

,BLOCKS=(0,init-addr)

,BLOCKS=(size-addr)

,BLOCKS=(size)

,DREF=NO

,DREF=YES

,SCOPE=SINGLE

,SCOPE=ALL

,SCOPE=COMMON

,CALLERKEY

,KEY=key-addr

,FPROT=YES

,FPROT=NO

,TTOKEN=ttoken-addr

,ORIGIN=origin-addr

,NUMBLKS=numblks-addr

,INLIST=NO

,INLIST=YES

,RANGLIST=rangelist-addr

Description

start-addr: RX-type address or register (2) - (12).

Default

: BACK=31 (for PAGEFRAMESIZE=4K)

Default

: BACK=64 (for PAGEFRAMESIZE=1M)

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:

DREF=NO

Default:

SCOPE=SINGLE

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

rangelist-addr: RS-type address or register (2) - (12). Required with

INLIST=YES.

600

z/OS MVS Authorized Assembler Services Reference ALE-DYN

DSPSERV macro for data spaces

Syntax

,NUMRANGE=numrange-addr

Description

numrange-addr: RS-type address or register (2) - (12). Default:

NUMRANGE=1

Default:

VAR=NO ,VAR=NO

,VAR=YES

,DISABLED=NO

,DISABLED=YES

Default:

DISABLED=NO

,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).

The parameters are explained under the standard form of the DSPSERV macro with the following exception:

,MF=(E,list addr)

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.

Chapter 47. DSPSERV — Create, delete, and control data spaces

601

DSPSERV macro for data spaces

602

z/OS MVS Authorized Assembler Services Reference ALE-DYN

Привіт! Я чат-бот зі штучним інтелектом, спеціально навчений допомагати вам з message. IBM MVS Programming: Authorized Assembler Services. Я ретельно переглянув документ і можу допомогти вам знайти точну інформацію, яка вам потрібна, або пояснити вміст чіткими та простими словами. Незалежно від того, чи шукаєте ви вказівки щодо конкретних функцій, кроки з усунення несправностей або загальне використання, не соромтеся задавати свої запитання. Чим більше деталей ви надасте про свої проблеми чи потреби, тим точніше та ефективніше я зможу вам допомогти!

Асистент друкує

Асистент не в мережі. Будь ласка, спробуйте пізніше.

Зміст

Схоже, ви потрапили на документ, написаний кількома мовами, включаючи ту, яка не є вашою рідною. Ви можете скористатися наведеними нижче посиланнями, щоб тимчасово приховати сторінки без бажаної мови.