Description

z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN

Description

z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN
SA23-1372-00

The COFPURGE macro requests that VLF purge (delete) a class of VLF objects. Before issuing COFPURGE, or any VLF macro, you need to understand the information on using the virtual lookaside facility (VLF) that appears in z/OS MVS Programming: Authorized Assembler Services Guide.

When you issue COFPURGE, VLF deletes the class immediately. Any transaction in process for the purged class fails; VLF issues a failure return code that is appropriate for the transaction. To reinstate the class, you must issue another COFDEFIN for the class, which you can do at any time. Once you have reinstated the class, you must identify the users of the class again.

Note that the system can also delete a class for control purposes even if no user requests it. Your application learns that the system has purged a class when it issues a COFIDENT, COFREMOV, COFCREAT, or COFRETRI macro specifying that class. There are specific return and reason code combinations to distinguish a class that is not defined from other error indicators.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state, with PSW key 0-7
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	24- or 31-bit
ASC mode:	Primary or access register (AR)
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Must be in the primary address space

Programming requirements

None.

Restrictions

None.

Input register information

Before issuing the COFPURGE macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0: Reason code
1: Used as a work register by the system
2-14: Unchanged
15: Return code

When control returns to the caller, the access registers (ARs) contain:

Register: Contents
0-1: Used as work registers by the system
2-14: Unchanged
15: Used as a work register by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

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

Syntax	Description

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

␢	One or more blanks must precede COFPURGE

COFPURGE

␢	One or more blanks must follow COFPURGE

CLASS=`class`	`class`: RX-type address or register (2) - (12).

,RETCODE=`retcod`	`retcod`: RX-type address or register (2) - (12).

,RSNCODE=`rsncod`	`retcod`: RX-type address or register (2) - (12).

Parameters

The parameters of the standard form are as follows:

CLASS=class: Specifies the required name of the class of VLF objects to be deleted.
,RETCODE=retcod: Specifies the location where the system is to store the return code. The return code is also in general purpose register (GPR) 15. If you specify a storage location, it must be on a fullword boundary.
,RSNCODE=rsncod: Specifies the location where the system is to store the reason code. The reason code is also in GPR 0. If you specify a storage location, it must be on a fullword boundary.

ABEND codes

None.

Return and reason codes

When the COFPURGE macro returns control to your program, GPR 15 (and retcod, if you coded RETCODE) contains one of the following hexadecimal return codes. GPR 0 (and rsncod, if you coded RSNCODE) contains one of the following hexadecimal reason codes.

Table 1. Return and Reason Codes for the COFPURGE Macro
Hexadecimal Return Code	Hexadecimal Reason Code	Meaning and Action
00	00	Meaning: The purge was successful. The class is no longer described to VLF. Action: None.
02	04	Meaning: Program error. The specified class was not described in the active COFVLFxx parmlib member. Action: Check that the class specified in the macro invocation matches a class specified in the SYS1.PARMLIB member COFVLFxx.
28	00	Meaning: Environmental error. VLF is not active. Action: Issue the START VLF command and rerun the program.