Description

Attention: Use the PGSER macro rather than PGRLSE.

The PGRLSE macro is used to release to the system all central (also called real) storage and auxiliary storage associated with specified pageable virtual storage areas. The PGRLSE macro performs this function for virtual addresses below 16 megabytes; the RELEASE option of the PGSER macro performs the same function for virtual addresses either above or below 16 megabytes. Use PGRLSE when a large area (one or more complete pages) of virtual storage within your program no longer has significant contents.

Functionally, PGRLSE 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. Thus, you can help reduce system overhead by releasing virtual storage when you no longer need it.

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.

Proper use of this function can increase the amount of storage available to the system and prevent needless paging I/O activity. Usage of PGRLSE may improve operating efficiency when the using program can discard the contents of a large virtual storage area and reuse the virtual storage pages; paging operations may be eliminated for those virtual storage pages when they are reused.

Syntax

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

Syntax	Description

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

␢	One or more blanks must precede PGRLSE.

PGRLSE

␢	One or more blanks must follow PGRLSE.

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

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

Parameters

The parameters are explained as follows:

LA=low addr: Specifies the address of the lower boundary of the area to be released.
,HA=high addr: Specifies the address of the upper boundary + 1 of the area to be released.

When control is returned, register 15 contains one of the following return codes:

Hexadecimal Code: Meaning
00: Successful completion.
04: Execution failed. The area specified, or a portion of the area, is protected from the requesting program. Any valid portion of the area preceding the protected area is released.

Example 1

Release the contents of the pages included within the specified areas. Only those pages fully encompassed will be nullified.

PGRLSE   LA=(R4),HA=(R5)

Example 2

Perform the operation in Example 1, but use A-type addresses.

PGRLSE   LA=LOWADDR,HA=HIGHADDR