PGSER — Page services

Description

Note: IBM® recommends that you use the PGSER macro for paging services.

The PGSER macro performs the same paging services as the PGLOAD, PGOUT, and PGRLSE macros. PGSER performs these services for addresses either above or below 16 megabytes.

The services are:

Page load equivalent to the PGLOAD macro.
Page out equivalent to the PGOUT macro.
Page release equivalent to the PGRLSE macro.
The PGSER macro with the PROTECT parameter makes a range of virtual storage pages read-only.
The PGSER macro with the UNPROTECT parameter makes a range of virtual storage pages modifiable.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state, and any PSW key. To use the PROTECT and UNPROTECT options, the caller must have a PSW key that matches the key of the storage.
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	24- or 31-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Must be in the primary address space

Programming requirements

The caller must include the IHAPVT mapping macro.
Regardless of the addressing mode, all addresses passed in registers are used as 31-bit addresses.
All RX-type addresses are assumed to be in the addressing mode of the caller.

Restrictions

None.

Input register information

Before issuing the PGSER 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 GPRs contain:

Register: Contents
0-4: Used as work registers by the system
5-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the access registers (ARs) are unchanged.

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 PGSER macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede PGSER.

PGSER

␢	One or more blanks must follow PGSER.

R L

,LOAD ,OUT ,PROTECT ,UNPROTECT ,RELEASE

,LA=`list addr`	`list addr`: RX-type address or register (1), (2) - (12).
	Note: This parameter is valid only with L.

,A=`start addr`	`start addr`: RX-type address or register (1), (2) - (12).
	Note: This parameter is valid only with R.

,EA=`end addr`	Default: EA=`start addr`
	`end addr`: RX-type address or register (15), (2) - (12).
	Note: This parameter is valid only with R.

,ECB=`ecb addr`	Default: If LOAD is specified, ECB=0.
	`ecb addr`: RX-type address or register (0) or (2) - (12).
	Note: This parameter is optional if LOAD is specified and is not valid for OUT and RELEASE.

,RELEASE=Y	Default: RELEASE=N
,RELEASE=N	Note: This parameter may be specified only if LOAD is specified.

,KEEPREL=Y	Default: KEEPREL=N
,KEEPREL=N	Note: This parameter may be specified only if OUT is specified.

,RELATED=`value`	`value`: Any valid macro keyword specification.

Parameters

R

L

Specifies the manner in which the input is supplied. If R is specified, the user supplies the starting and ending addresses of the virtual area for which the service needs to be performed. If L is specified, the user supplies the address of the page services list (PSL), which specifies the virtual area for which the service is to be performed. See the topic “Page Service List (PSL)” in z/OS MVS Programming: Assembler Services Guide for a description of the PSL.

,LOAD

,OUT

,PROTECT

,UNPROTECT

,RELEASE

Indicates the function to be performed.

LOAD specifies that a page-in operation is to be initiated for the virtual storage area specified, in anticipation of future needs.

OUT specifies that a page-out operation is to be initiated for the virtual storage area specified.

PROTECT specifies that a range of virtual storage be made read-only. R, L, LA, A, EA, and RELATED are valid keywords with the PROTECT option.

UNPROTECT specifies that a range of virtual storage be made modifiable. R, L, LA, A, EA, and RELATED are valid keywords with the UNPROTECT option.

RELEASE specifies the release of all physical paging resources, including both processor storage and auxiliary storage. Functionally, RELEASE is equivalent to a FREEMAIN macro followed by a GETMAIN macro. That is, the virtual space is maintained, but the data is discarded. When a released page is next referred to, its contents are binary zeros.

Note: You must unprotect protected storage before releasing it.

,LA=list addr

Specifies the address of the page services list (PSL) for L requests.

,A=start addr

Specifies the address of the start of the virtual area for R requests.

,EA=end addr

Specifies the address of the last byte on the last page of the virtual area for R requests.

,ECB=ecb addr

Specifies the address of the ECB that is used to signal event completion for a LOAD request.

If an ECB is supplied, the caller must check the return code because the ECB will not be posted if the return code is zero. If an ECB is not supplied, it is not necessary to check the return code because control returns to the caller only if the request was successfully completed; if unsuccessful, page services abnormally terminates the caller. You must ensure that the storage area containing the ECB is not freed and that the key is not altered. If either test fails, page services does not post the ECB.

,RELEASE=Y

,RELEASE=N

Specifies that all the central (also called real) and auxiliary storage associated with the virtual storage areas is to be released to the system (Y), or that all the central and auxiliary storage associated with the virtual storage areas is not to be released to the system (N).

Note: PGRLSE, PGSER RELEASE, PGSER FREE with RELEASE=Y, and PGFREE RELEASE=Y may ignore some or all of the pages in the input range and will not notify the caller if this was done.

Any pages in the input range that match any of the following conditions will be skipped, and processing continues with the next page in the range:

Storage is not allocated or all pages in a segment have not yet been referenced.
Page is in PSA, SQA or LSQA.
Page is V=R. Effectively, it's fixed.
Page is in BLDL, (E)PLPA, or (E)MLPA.
Page has a page fix in progress or a nonzero FIX count.
Pages with COMMIT in progress or with DISASSOCIATE in progress.

,KEEPREL=Y

,KEEPREL=N

Specifies that the virtual pages should be validated again after the page-out completes (Y), or that the virtual pages will be marked invalid and the real frames freed for reuse (N).

,RELATED=value

Provides information to document the macro by relating the service performed to some corresponding function or service. The format can be any valid coding value that the user chooses.

ABEND codes

PGSER might abnormally terminate with one of the following abend codes: X'18A', X'28A'. See z/OS MVS System Codes for explanations and programmer responses.

Return and reason codes

When the PGSER macro returns control to your program, GPR 15 contains one of the following hexadecimal return codes.

Option	Code	Meaning and Action
LOAD	0	Meaning: The operation completed normally and the ECB will not be posted. If no ECB is supplied, the operation is completed or proceeding. Action: None. If the ECB parameter was specified, do not issue a WAIT macro for the ECB after receiving this return code because it will not be posted.
LOAD	8	Meaning: The operation is proceeding. The ECB, if applicable and available, will be posted with X‘00’ when all page-ins are complete. Action: None. However, if the ECB parameter was specified, issuing a WAIT macro for this ECB will allow your program to synchronize with the completion of the page load operation.
OUT	0	Meaning: The operation completed normally. Action: None.
OUT	C	Meaning: At least one page specified to be paged out was not paged out. The page service is proceeding for the other pages. Action: None.
RELEASE	0	Meaning: The operation completed normally. Note: PGRLSE, PGSER RELEASE, PGSER FREE with RELEASE=Y, and PGFREE RELEASE=Y may ignore some or all of the pages in the input range and will not notify the caller if this was done. Any pages in the input range that match any of the following conditions will be skipped, and processing continues with the next page in the range: Storage is not allocated or all pages in a segment have not yet been referenced. Page is in PSA, SQA or LSQA. Page is V=R. Effectively, it's fixed. Page is in BLDL, (E)PLPA, or (E)MLPA. Page has a page fix in progress or a nonzero FIX count. Pages with COMMIT in progress or with DISASSOCIATE in progress. Action: None.

Examples

Example 1

Perform the page-load function for the 4096-byte virtual area starting at BUFFER, supplying no ECB. Include the IHAPVT mapping macro.

PGSER R,LOAD,A=BUFFER,EA=BUFFER+4095,ECB=0
IHAPVT

Example 2

Release the virtual area specified in the PSL located at LOADWORD. Include the IHAPVT mapping macro.

PGSER L,RELEASE,LA=LOADWORD
IHAPVT

Example 3

Protect the storage area that starts at the address in GPR 4 and ends at the address in the variable ENDIT. Include the IHAPVT mapping macro.

PGSER R,PROTECT,A=(4),EA=ENDIT
IHAPVT