PGFREE — Free virtual storage contents

Description

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

The PGFREE macro makes virtual storage pages, below 16 megabytes, that were fixed via the PGFIX macro eligible for page-out. The PGFREE function is available only to authorized users. PGFREE must be issued by the same task that issued the PGFIX, otherwise PGFREE has no effect.

Note: A fixed page is not considered pageable until the number of PGFREEs issued for the page is equal to the number of PGFIXes previously issued for that page. That is, a page is not automatically made pageable as the result of issuing a PGFREE macro.

Syntax

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

Syntax	Description

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

␢	One or more blanks must precede PGFREE.

PGFREE

␢	One or more blanks must follow PGFREE.

L

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

R

,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

,ANYWHER=N	Default: ANYWHER=N
,ANYWHER=Y

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

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.
R: Specifies that no parameter list is being supplied with this request.
,A=start addr: Specifies the start address of the virtual area to be freed.
Note: start addr must be located in 24-bit addressable storage.
,ECB=ecb addr: Specifies the address of the ECB that was used in a prior PGFIX request. This parameter is used if there is any possibility that the ECB for the previously issued PGFIX was not posted complete.
,EA=end addr: Specifies the end address + 1 of the virtual area to be freed.
Note: end addr must be located in 24-bit addressable storage.
,ANYWHER=N
,ANYWHER=Y: On subsequent page-ins, assign real frames below 16 megabytes in anticipation of a page fix (N) or on subsequent page-ins, assign real frames anywhere (Y). The ANYWHER option takes effect only when the page fix count goes to zero. The default is ANYWHER=N.
,RELEASE=N
,RELEASE=Y: Specifies that the contents of the virtual area is to remain intact (N) or be released (Y).
,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 PGFREE macro returns control to your program, GPR 15 contains one of the following hexadecimal return codes.

Table 1. Return Codes for the PGFREE Macro
Return Code	Meaning
00	Meaning: Operation completed normally.
04	Meaning: Operation abnormally terminated. Operation incomplete because of invalid address in virtual subarea list entry.
10	Meaning: Operation abnormally terminated. Virtual subarea list entry or ECB address invalid.

Example 1

Free the storage in Example 1 of standard-form PGFIX.

PGFREE R,A=(R3)

Example 2

Free the storage in Example 2 of standard-form PGFIX.

PGFREE R,A=(R3),EA=(R4)

Example 3

Free the storage in Example 3 of standard-form PGFIX, and forfeit the pages fully included in the address range.

PGFREE R,A=(R3),EA=(R4),ECB=(R5),RELEASE=Y