Description

The PURGEDQ macro allows a task to purge particular SRB activity. The system dispatches an SRB routine asynchronously from when the SCHEDULE macro was issued. For this reason, the conditions that existed in the system at the time the SCHEDULE was issued might have changed by the time the routine is dispatched. If the environment that the asynchronous routine requires to run successfully has been changed, the results are unpredictable. For this reason, the PURGEDQ macro is available to:

The parameters on PURGEDQ determine the target address space and limit the scope of the purge. When purging SRBs scheduled in the primary address space, PURGEDQ waits for dispatched SRBs to finish. When purging SRBs scheduled in an address space other than the primary, PURGEDQ does not purge SRBs that have been dispatched, nor does PURGEDQ wait for dispatched SRBs to complete.

When the target address space is not the primary address space, PURGEDQ does not guarantee that all SRBs matching the purge parameters will be purged. The issuer of PURGEDQ is not informed of SRBs that are not purged. When purging SRBs scheduled in an address space other than primary, use a resource manager termination routine (RMTR) if you need to know whether a particular SRB has been purged.

Except for the TCB, all input parameters to this macro can reside in storage above 16 megabytes if the issuer is executing in 31-bit addressing mode.

See z/OS MVS Programming: Authorized Assembler Services Guide for more information on using the PURGEDQ macro, especially the resource manager termination routine (RMTR).

Parent topic: PURGEDQ — Purge SRB activity

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Supervisor state or PSW key 0 - 7 or APF-authorized
Dispatchable unit mode: Task
Cross memory mode: PASN=HASN=SASN
AMODE: 24- or 31-bit
ASC mode: Primary
Interrupt status: Enabled for I/O and external interrupts
Locks: No locks held
Control parameters: Must be in the caller's primary address space

Programming requirements

None.

Restrictions

None.

Input register information

Before issuing the PURGEDQ 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

After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as work registers by the system
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as work registers by the system

Performance implications

None.

Syntax

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

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede PURGEDQ.
   
PURGEDQ  
   
␢ One or more blanks must follow PURGEDQ.
   
RMTR=RMTR addr RMTR addr: RX-type address, or register (2) - (12).
   
   ,ASID=ASID addr ASID addr: RX-type address, or register (2) - (12).
   
   ,ASIDTCB=addr addr: RX-type address of an 8-byte field, or register (2) - (12) that contains an address of an 8-byte field.
   

Parameters

The parameters are explained as follows:

RMTR=RMTR addr
Specifies the address of the RMTR. If the program scheduled the SRB using SCHEDULE, this is the address that was placed in the SRBRMTR field (mapped by IHASRB). If the program scheduled the SRB using IEAMSCHD, this is the address specified on the RMTRADDR parameter. It limits the purge to SRBs that are protected by the same RMTR; that is, where the SRBs have the same address.
,ASID=ASID addr
Specifies the address of a halfword that contains the ASID of the target address space into which the SRB was scheduled. If you omit ASID, the system assumes that the primary address space is the target address space. Note that when you use the ASID parameter to purge SRBs scheduled to an address space other than primary, PURGEDQ does not guarantee that all SRBs will be purged.
,ASIDTCB=addr
Specifies the address of a doubleword that describes the TCB for which SRBs are to be purged. Through this parameter, you can purge the SRBs associated with a specific task. If you omit the parameter, the system purges SRBs associated with the current task in the primary address space.

When you use the ASID parameter to purge SRBs scheduled to an address space other than primary, PURGEDQ does not guarantee that all SRBs will be purged.

Specify the ASIDTCB parameter in one of the following ways:
  1. To attempt to purge all SRBs scheduled to a specific address space as defined by ASID, set the ASIDTCB parameter as follows:
    Set These Bytes To This Value Meaning
    Bytes 0-7 Zero The system is to purge all SRBs defined by the ASID (SRBASCB) and RMTR parameters, regardless of their task (SRBPTCB) and address space (SRBPASID) association.
  2. To purge all SRBs scheduled by a specified address space, set the ASIDTCB parameter as described below:
    Set These Bytes To This Value Meaning
    Bytes 0-1 Reserved The system is to purge all SRBs defined by
    Bytes 2-3 ASID1 the ASID and RMTR parameters associated
    Bytes 4-7 Zero with the target address space (SRBPASID), regardless of their task (SRBPTCB).
  3. To purge all SRBs associated with a specified TCB in a specified address space, set the ASIDTCB parameter as described below:
    Set These Bytes To This Value Meaning
    Bytes 0-1 Zero The system is to purge all SRBs defined by
    Bytes 2-3 ASID2 the ASID and RMTR parameters associated
    Bytes 4-7 TCB address with the scheduling address space (SRBPASID) and task (SRBPTCB). (If you specify SRBPTCB, you must also specify SRBPASID.)
Note: The TCB resides in storage below 16 megabytes.

ABEND codes

17B
27B
47B

See z/OS MVS System Codes for an explanation and programmer responses for this code.

Return and reason codes

None.

Example 1

Purge all SRBs scheduled to ASID ‘20’X with:
  • SRBPTCB equal to the current TCB (that is, the TCB issuing the PURGEDQ)
  • SRBPASID equal to the primary ASID
  • SRBRMTR equal to the address of RMTR routine RMTRA 
          PURGEDQ ASID=AS1,RMTR=RMTRA

AS1       DC   XL2'0020'

Example 2

Purge all SRBs scheduled to ASID ‘21’X, regardless of what is specified in SRBPASID and SRBPTCB, and that have SRBRMTR equal to the address of RMTR routine RMTRB. 
          PURGEDQ ASID=AS2,ASIDTCB=PURGPRM1,RMTR=RMTRB

PURGPRM1  DC    XL8'00000000'
AS2       DC    XL2'0021'

Example 3

Purge all SRBs scheduled to the primary address space (that is, the address space from which this PURGEDQ was issued) that have:
  • SRBPASID of ‘12’X
  • SRBPTCB equal to the address of TCBX
  • SRBRMTR equal to the address of RMTR routine RMTRC
          PURGEDQ ASIDTCB=PURGPRM2,RMTR=RMTRC

PURGPRM2  DS    0CL8
          DC    XL2'0000'
PURGASID  DC    XL2'0012'
PURGTCB   DC    A(TCBX)

Example 4

Purge all SRBs scheduled into the primary address space, related to the current (terminating) task, and associated with the resource manager termination routine located at RESCLEAN. 
PURGEDQ RMTR=RESCLEAN