PGFIXA — Fix virtual storage contents

Description

Note: IBM® recommends that you use the PGSER macro rather than PGFIXA.

The PGFIXA macro makes virtual storage areas, below 16 megabytes, resident in central (also called real) storage and ineligible for page-out while the requesting task's address space is swapped into central storage. The PGFIXA function is available only to key zero and supervisor state users. The PGFIXA macro executes short-term, synchronous page fixes. The preferred area(s) of storage are intended for long term page fixes. A long term page fix in the V=R or nonpreferred areas may delay V=R functions or CONFIG STORAGE commands. All fix processing is assumed to be short-term and is complete when control is returned to the issuer of the macro.

PGFIXA does not prevent pages from being paged out when an entire address space is swapped out of central storage. Consequently, when using the PGFIXA macro, you cannot assume a constant real address mapping for fixed pages that are susceptible to swapping.

Output

If the PGFIXA is successful, control is returned enabled to the user, all pages are fixed, and register 15 contains a return code of zero.

If the PGFIXA is unsuccessful, the user will be abended with a system completion code of X‘171’ or a system complete code of X‘028’. For X‘171’ abends, all pages processed up to, but not including the page causing the error, will be fixed. Register 10 will contain the address of the pages in error when the abend is issued. No pages will be fixed in the event of a X‘028’ abend.

Restrictions

Use of the PGFIXA macro is subject to the following restrictions:
  • Can be used only for short term synchronous fixes.
  • The user must be in supervisor state with a protection key of zero.
  • The user must not hold any spin locks.
  • The program mask byte in the PSW is zero and interrupts are enabled upon return from the PGFIXA.
  • The user is responsible for freeing any pages fixed via the PGFIXA. A corresponding PGFREEA macro should be issued. In addition, an FRR should be established during the period where fixes are outstanding. The FRR should free the frames in case there is an unexpected error.
  • DSECTs for the IHAPSA, CVT, and IHAPVT must be provided.
  • The user must ensure that the end address is greater than or equal to the start address.
  • The SAVE keyword can only be used with TYPE=R.

Syntax

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

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede PGFIXA.
   
PGFIXA  
   
␢ One or more blanks must follow PGFIXA.
   
   ,TYPE=L  
   ,TYPE=R Default: TYPE=R
   
   ,SAVE=YES Default: SAVE=YES
   ,SAVE=NO  
   

Parameters

The parameters are explained as follows:

TYPE=L
TYPE=R
Specifies the type of input. When L is specified, register 1 is to contain the address of a virtual subarea list (VSL) fixed in storage. (See the topic “Input to Page Services” in z/OS MVS Programming: Authorized Assembler Services Guide for a description of the VSL.) By specifying TYPE=L, registers 1 through 13 are saved. If TYPE=R is specified, then register 1 contains the address of the first byte to be fixed in a contiguous range and register 2 contains the address of the last byte to be fixed (actual end address). When TYPE=R is specified, the registers saved depend upon what is specified on the SAVE parameter.
Note: All other users of the PGFIX, PGFIXA (TYPE=L), and PGFREEA macros must specify the actual end address plus one.
,SAVE=YES
,SAVE=NO
Specifies the registers to be saved for TYPE=R. Registers 1 through 13 are saved if SAVE=YES is specified or if the default is taken. Registers 2 through 10 are saved if SAVE=NO is specified.

Example 1

Use PGFIXA to fix virtual storage without using a virtual subarea list. Registers 2 through 10 will be saved. 
FIX1 PGFIXA TYPE=R,SAVE=NO

Example 2

Use PGFIXA to fix virtual storage using a virtual subarea list. Registers 1 through 13 will be saved. 
FIX2 PGFIXA TYPE=L