PGSER — Page services

The requirements for the caller invoking PGSER with BRANCH=N are:

The requirements for the caller invoking PGSER with BRANCH=Y are:

• The caller must include the IHAPVT mapping macro.
• Except for the TCB, all input parameters to this macro can reside in storage above 16 megabytes if the caller is executing in 31-bit addressing mode.
• 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.

IBM recommends that page fixes of more than 100 pages be divided into several smaller fix requests. Large page fix requests can cause an excessive spin loop to occur.

Before issuing PGSER with BRANCH=Y, the caller must ensure that GPR 13 points to a standard 18-word save area. Before issuing PGSER with BRANCH=N, 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.

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.

None.

The standard form of the PGSER macro is written as follows:

The parameters are explained as follows:

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, which specifies the virtual area for which the service is to be performed. See “Input to Page Services” in z/OS MVS Programming: Authorized Assembler Services Guide for a description of the PSL.

,FIX

,FREE

,LOAD

,OUT

,PROTECT

,UNPROTECT

,RELEASE

,ANYWHER

Indicates the function to be performed.

FIX specifies that the virtual storage areas are to reside in central (also called real) storage and are ineligible for page-out while the address space is swapped in. This parameter does not prevent pages from being paged out when the entire address space is swapped out of central storage. FIX will ignore a request to fix storage in a system area that has the fixed attribute (for example, the LSQA and SQA). A FIX request for a page in the LSQA or SQA will not cause the page to be backed by central storage below 16 megabytes. Requests for disabled reference (DREF) storage are not valid for the FIX parameter.

FREE specifies that the virtual storage areas that were previously fixed via the FIX option are eligible for page-out. A fixed page is not considered pageable until the number of FREE and FIX requests for the page are equal. Requests for disabled reference (DREF) storage are not valid for the FREE parameter.

LOAD specifies that a page-in operation is to be initiated for the virtual storage area specified, in anticipation of future needs. Requests for disabled reference (DREF) storage are not valid for the LOAD parameter.

OUT specifies that a page-out operation is to be initiated for the virtual storage area specified. Requests for disabled reference (DREF) storage are not valid for the OUT parameter.

PROTECT specifies that a range of virtual storage be made read-only. R, L, LA, A, BRANCH, 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, BRANCH, EA, and RELATED are valid keywords with the UNPROTECT option. The caller must have either key 0 or a PSW key that matches the key of the storage.

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. RELEASE is the only PGSER function that is valid for disabled reference (DREF) storage.

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.

Use PGSER RELEASE instead of the MVCL instruction for these reasons:

• PGSER RELEASE is faster than MVCL for very large areas.
• Pages that are released through PGSER RELEASE do not occupy space in central, expanded, or auxiliary storage.

ANYWHER applies to virtual storage areas that did not specify LOC=(BELOW,ANY) or LOC=(ANY,ANY) or LOC=ANY on a GETMAIN request, that have been previously fixed, and probably will not need to be fixed again. ANYWHER specifies that the virtual storage area specified can be placed either above or below 16 megabytes central on future page-ins.

,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 last byte of the virtual area to be fixed for R requests.

,TCB=tcb addr

Specifies either zero or the address of the TCB to be assigned ownership of fixes for a FIX request or fixes for a FREE request. If zero is specified, no TCB is assigned ownership of the request. Cross memory callers must specify zero.

For OUT and LOAD requests, the PGSER routine associates the request with a particular TCB so that the request can be purged if the task terminates before the request is complete. For SVC entry (BRANCH=N), the PGSER routine uses the current TCB.

Note: The TCB resides in storage below 16 megabytes.

,ECB=ecb addr

Specifies the address of the ECB that is used to signal event completion for an asynchronous FIX or LOAD request. If the caller is in cross memory mode or if the caller requests a synchronous page fix (a FIX for which the caller is suspended until the entire FIX request is complete), the ECB must be zero (ECB=0 or ECB=(r), where (r) represents a register that contains zero).

For a FREE request, ECB specifies the address of the ECB that was used in a previous FIX request. If this parameter is specified, any pages in the previous FIX request that are not yet fixed, will not be fixed. If L is specified, the PSL chain must contain the addresses of the virtual pages in the same order in both the FREE and the previous FIX request. Also, the ECB for the FIX request will not be posted if it was not yet posted at the time of the FREE request.

If the ECB parameter is not specified on a FREE request, only the fix counts for the valid pages in storage at the time of the FREE request are decreased. This will not affect the paging activity and the posting of the ECB associated with the original FIX request.

If an ECB is supplied on a FIX or LOAD request, 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.

For all callers that supply an ECB, page services verifies that the ECB address is in an area allocated through the GETMAIN macro and if the caller is not in key 0, page services also verifies that the ECB is in the caller's protect key. You must ensure that the page containing the ECB is not freed and that the key is not altered; otherwise, page services does not post the ECB.

,RELEASE=Y

,RELEASE=N

Specifies that all the central 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 not valid and the real frames freed for reuse (N).

,LONG=Y

,LONG=N

Specifies that the relative real time anticipated for the FIX is long (Y); or that the relative real time anticipated for the FIX is short (N). (In general, the duration of a fix is long if it can be measured in seconds.)

,BACKOUT=Y

,BACKOUT=N

Specifies the procedure to follow when a nonallocated page is encountered during the processing of a FIX request. If BACKOUT=Y, all pages fixed as part of the request are freed before returning to the caller. If BACKOUT=N, the pages previously fixed as part of the request are not freed and no further processing is done before returning to the caller.

,ANYWHER=N

,ANYWHER=Y

Specifies that on subsequent page-ins, page services is to assign real frames below 16 megabytes in anticipation of a page-fix (N); or on subsequent page-ins, page services is to assign real frames anywhere (Y). The ANYWHER option takes effect only when the page-fix count goes to zero.

,BRANCH=Y

,BRANCH=N

Specifies whether this is a branch entry.

If BRANCH=Y is specified, it is a branch entry and users of this option must provide the address of an 18-word save area in GPR 13. Cross memory callers and callers in AR mode must use BRANCH=Y.

If BRANCH=N is specified, it is an SVC entry.

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

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.

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