PGFIX — Fix virtual storage contents

Description

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

The PGFIX 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. PGFIX ignores requests 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. A subsequent PGFREE is effective only if issued by the same task. The PGFIX function is available only to authorized users.

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

Syntax

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

Syntax	Description

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

␢	One or more blanks must precede PGFIX.

PGFIX

␢	One or more blanks must follow PGFIX.

R
L

,LA=`list addr`	`list addr`: A-type address, or register (1) or (2) - (12).

,A=`start addr`	`start addr`: A-type address, or register (1) or (2) - (12).

,ECB=`ecb addr`	`ecb addr`: A-type address, or register (0) or (2) - (12).

,EA=`end addr`	`end addr`: A-type address, or register (2) - (12) or (15).
	Default: `start addr` + 1

,LONG=Y	Default: LONG=Y
,LONG=N

,RELEASE=N	Default: RELEASE=N
,RELEASE=Y	Note: RELEASE=Y may only be specified with EA above.

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

Parameters

The parameters are explained as follows:

R: Specifies that no parameter list is being supplied with this request.
L: Specifies that a parameter list is being supplied with this request.
,LA=list addr: Specifies the address of the first entry of a virtual subarea list (VSL). See “Input to Page Services” in z/OS MVS Programming: Authorized Assembler Services Guide for a description of the VSL.
,A=start addr: Specifies the start address of the virtual area to be fixed.
Note: start addr must be located in 24-bit addressable storage.
,ECB=ecb addr: Specifies the address of the ECB that is used to signal event completion. If the ECB address specified is zero, (ECB=0 or ECB=(register) where the contents of the register specified is 0), the fix request is completely satisfied before control is returned.
Note: If the user intends to wait on the ECB as part of an ECB list, he must ensure that the list and associated ECBs are fixed in central storage before issuing the WAIT. The PGFIX service routine ensures that the specified ECB is fixed.
,EA=end addr: Specifies the end address + 1 of the virtual area to be fixed.
Note: end addr must be located in 24-bit addressable storage.
,LONG=Y
,LONG=N: Specifies that the relative real time duration anticipated for the fix is long (Y) or short (N).
,RELEASE=N
,RELEASE=Y: Specifies that the contents of the virtual area is to remain intact (N) or be released (Y) before the fix is done.
,RELATED=value: Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user, and may be any valid coding values.

Return and reason codes

When PGFIX macro returns control to your program, GPR 15 contains a hexadecimal return code.

Table 1. Return Codes for the PGFIX Macro
Return Code	Meaning
00	Meaning: Operation completed normally; ECB posted complete.
04	Meaning: Operation abnormally terminated with a X‘171’ abend. Operation incomplete because of invalid address virtual subarea list entry; ECB posted complete. See z/OS MVS System Codes for a complete description of the register contents after a X‘171’ abend.
08	Meaning: Operation proceeding; ECB will be posted when all requested pages are fixed in central storage.
10	Meaning: Operation abnormally terminated with a X‘171’ abend. Virtual subarea list entry or ECB address invalid; no ECB is posted. See z/OS MVS System Codes for a complete description of the register contents after a X‘171’ abend.

The ECB is unchanged if the request was initiated but not complete (return code 8), or if an ABEND was issued with return code 10. Otherwise, the ECB is posted complete with code:

0: - operation completed successfully.
4: - operation incomplete because of invalid address in VSL entry.

If the return code issued is 8, the ECB is posted asynchronously when paging I/O has completed, with code:

0: - operation completed successfully.
4: - operation incomplete because of paging error; requesting TCB will be abnormally terminated.

The ECB code is posted in the low-order 3 bytes of the ECB, and is right-justified.

Example 1

Fix a single byte of virtual storage addressed by register 3. Note that the full 4096-byte page containing the specified byte is actually fixed. The storage is long fixed.

PGFIX R,A=(R3),ECB=(R5)

Example 2

Fix virtual storage without using a virtual subarea list. Storage is long fixed.

PGFIX R,A=(R3),EA=(R4),ECB=ECB1

Example 3

Fix, but not long-fix, virtual storage, and ensure that the pages fully included in the address range are forfeited before fixing the area specified by registers 3 and 4.

PGFIX R,A=(R3),EA=(R4),ECB=(R5),LONG=N,RELEASE=Y