Description

Description

z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO
SA23-1375-00

The SYSEVENT macro provides the interface to the system resource manager (SRM). Using SYSEVENT mnemonics, you can:

Notify SRM of an event
Ask SRM to perform a specific function

Environment

The requirements for the ENTRY=BRANCH caller are:

Environmental factor	Requirement
Authorization:	Supervisor state and PSW key 0 - 7
Dispatchable unit mode:	Task or SRB.
Cross memory mode:	PASN=HASN=SASN
AMODE:	24- or 31-bit
ASC mode:	Primary
Interrupt status:	Enabled or disabled for I/O and external interrupts
Locks:	Callers that specify ENTRY=BRANCH must hold the LOCAL lock for TRAXRPT, TRAXFRPT and TRAXERPT. There are no locking requirements for the other SYSEVENTs.

The requirements for the ENTRY=SVC caller are:

Environmental factor	Requirement
Authorization:	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 locking requirements

The requirements for the ENTRY=UNAUTHPC caller are:

Environmental factor	Requirement
Authorization:	Problem state and PSW key 8 - 15
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	31- or 64-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held

The following SYSEVENTs are unauthorized:

FREEAUX
QVS
REQFASD
REQLPDAT with ENTRY=UNAUTHPC
QRYCONT with ENTRY=UNAUTHPC

The requirements are:

Environmental factor	Requirement
Authorization:	Problem state or key 8-15
AMODE:	31- or 64-bit

All other requirements are as noted above for ENTRY=BRANCH, ENTRY=SVC.

Programming requirements

When you specify ENTRY=BRANCH, include the CVT mapping macro as a DSECT in the calling program. If a specific SYSEVENT requires a parameter list in addition to the information specified on the macro invocation, load register 1 with the address of that parameter list before issuing the macro.

Restrictions and limitations

For restrictions on the use of each SYSEVENT, including input and output requirements, refer to the descriptions of the parameters.

Input register information

When you specify ENTRY=BRANCH, register 13 must contain the address of a 72-byte save area on input. For specific input register requirements, see the description of the specific SYSEVENT.

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

Used as a work register by the system

1

One of the following:

Unchanged (for ENCASSOC, STGTEST, TRAXRPT, TRAXFRPT, TRAXERPT, REQASCL, REQASD, REQFASD, REQSRMST, ENQHOLD, ENQRLSE, QRYCONT, and QVS SYSEVENTs)
Status code (for DONTSWAP, OKSWAP, and TRANSWAP SYSEVENTs)

2-13

Unchanged

14

Used as a work register by the system

15

One of the following:

Return code (for ENCASSOC, TRAXRPT, TRAXFRPT, TRAXERPT, REQASCL, REQASD, REQFASD, REQSRMST, ENQHOLD, ENQRLSE, QRYCONT, and QVS SYSEVENTs)
Used as a work register by the system (for DONTSWAP, OKSWAP, STGTEST, and TRANSWAP SYSEVENTs)

Syntax

The SYSEVENT macro is written as follows:

Syntax	Description

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

␢	One or more blanks must precede SYSEVENT.

SYSEVENT

␢	One or more blanks must follow SYSEVENT.

`sysevent mnemonic`	`sysevent mnemonic`: symbol.
	Note: See the description of the parameters for the valid options.

,ENTRY=SVC ,ENTRY=BRANCH ,ENTRY=UNAU THPC	Defaults: DONTSWAP SVC (BRANCH possible) ENCASSOC BRANCH ENCSTATE BRANCH (SVC possible) ENQHOLD BRANCH (SVC possible) ENQRLSE BRANCH (SVC possible) FREEAUX BRANCH OKSWAP SVC (BRANCH possible) QVS BRANCH REQASCL BRANCH (SVC possible) REQASD SVC (BRANCH possible) REQFASD BRANCH REQLPDAT BRANCH (SVC and UNAUTHPC possible) REQSRMST SVC (BRANCH possible) STGTEST SVC (BRANCH possible) TRANSWAP SVC (BRANCH possible) TRAXERPT BRANCH TRAXFRPT BRANCH TRAXRPT BRANCH QRYCONT SVC (BRANCH and UNAUTHPC possible) Note: The FREEAUX, QVS, REQFASD, TRAXERPT, TRAXFRPT, and TRAXRPT SYSEVENTS use an unauthorized BRANCH.

,TYPE=`type value`	Note: The ENCASSOC, ENQHOLD, ENQRLSE, and REQFASD SYSEVENTs support the TYPE parameter. For valid `type values` refer to the descriptions of the specific SYSEVENT: For ENCASSOC, see Associate an enclave with an address space (ENCASSOC). For ENQHOLD, see Identify holder of a resource (ENQHOLD). For ENQRLSE, see Identify that a holder has released resource (ENQRLSE). For REQFASD, see Obtain address space related information (REQASD and REQFASD).

,ASID=`asid`	Address space ID
,ASIDL=`asidl`

Parameters

The parameters are explained as follows:

sysevent mnemonic

Identifies the SYSEVENT being requested. The valid options are:

DONTSWAP,
ENCASSOC
ENCSTATE
ENQHOLD
ENQRLSE
FREEAUX
OKSWAP
QRYCONT
QVS
REQASCL
REQASD
REQFASD
REQLPDAT
REQSRMST
STGTEST
TRAXERPT
TRAXFRPT
TRAXRPT
TRANSWAP

See SYSEVENT mnemonics for a description of these options.

,ENTRY=SVC

,ENTRY=BRANCH

,ENTRY=UNAUTHPC

Specifies the instruction used to pass control to SRM.

Only users who do not hold a lock can specify ENTRY=SVC.

Branch entry is required when the caller holds a lock. It is also the only supported entry for FREEAUX, REQFASD, QVS, TRAXERPT, TRAXFRPT, TRAXRPT, and ENCASSOC.

Use the UNAUTHPC entry to call SYSEVENTs from an unauthorized environment. If your application is performance critical or issues the SYSEVENT many times a second, use ENTRY=SVC or ENTRY=BRANCH.

,TYPE=type value

Note:

The ENCASSOC, ENQHOLD, ENQRLSE, and REQFASD SYSEVENTs support the TYPE parameter.
For valid type values refer to the descriptions of the specific SYSEVENT:
- For ENCASSOC, see Associate an enclave with an address space (ENCASSOC).
- For ENQHOLD, see Identify holder of a resource (ENQHOLD).
- For ENQRLSE, see Identify that a holder has released resource (ENQRLSE).
- For REQFASD, see Obtain address space related information (REQASD and REQFASD).

,ASID=register

,ASIDL=asid

Specifies the address space identifier in ASIDL=asid, or the register containing the address space identifier in ASID=register. Either ASIDL or ASID is required for REQASD and REQFASD.