Fixing/freeing virtual storage contents

Fixing virtual storage and freeing central storage are complementary functions. The PGFIX and PGFIXA macros and the FIX option of PGSER make specified storage areas resident in central storage and ineligible for page-out as long as the requesting address space remains in central storage. Note that page fixing ties up valuable central storage and is usually detrimental to system performance unless the use of the fixed pages is extremely high.

The PGFREE and PGFREEA macros and the FREE option of PGSER make specified storage areas, which were previously fixed via the PGFIX macro or the FIX option of PGSER, eligible for page-out. Pages fixed by PGFIX, PGFIXA, or the FIX option of PGSER are not considered pageable until the same number of page free and page-fix requests have been issued for any virtual area. The fix and free requests for a page must be issued by the same task (unless TCB=0 is specified), otherwise the page will not be freed.

When using the fix function, you have the option of specifying the relative real time duration anticipated for the fix. Specify LONG=Y, if you expect that the duration of the fix will be relatively long. (As a rule of thumb, the duration of a fix is considered long if the interval can be measured on an ordinary timepiece-that is, in seconds.) Additional processing might be required to avoid an assignment of a frame to the V=R area or an area that might be varied offline. Specify LONG=N, if you expect the time duration of the fix to be relatively short. A long-term fix is assumed if you do not specify this option.

In both the fix and free functions, you have the option of specifying that the contents of the virtual area are to remain intact or be released. If the contents are to be released, specify RELEASE=Y; otherwise, specify RELEASE=N. If you specify PGFIX or the FIX option of PGSER with RELEASE=Y, the release function is performed before the fix function. If you specify PGFREE or the FREE option of PGSER with RELEASE=Y, the free function is performed and those pages of the virtual subarea with zero fix counts are released; that is, the contents of virtual areas spanning entire virtual pages that were fixed are expendable and no page-outs for these pages are necessary.

RELEASE may also be specified as a separate parameter of the PGSER macro. When you specify RELEASE as a separate parameter, the released page can be in disabled reference 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.

The BRANCH=SPECIAL and the FIX or FREE options of PGSER provide the fast path version of PGSER. The fast path version of PGSER with the FIX option ensure that specific storage areas are resident in central storage and ineligible for page-out. These functions execute only short-term, synchronous page fixes.

Note:

PGFIX and the FIX option of PGSER do not prevent pages from being paged out when an entire virtual address space is swapped out of central storage. Consequently, the user of PGFIX and the FIX option of PGSER cannot assume a constant real address mapping for fixed virtual areas in most cases.
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.
When using the PGFIXA macro or the fast path version of PGSER with the FIX option, or a branch entry to PGSER with the options FIX and TCB=0, fixed areas will not automatically be freed at the end of a job; to free them, issue a PGFREEA macro or the PGSER macro with the FREE and BRANCH=SPECIAL options.