The IEAMRMF3 macro provides information about the dispatchability of address spaces. Use IEAMRMF3 to determine which address spaces are currently running on a processor and which address spaces are waiting for a processor. To get information about the dispatchability of enclaves, use the IWMRQRY macro. IMWRQRY is described in z/OS MVS Programming: Workload Management Services.
The number of elements you receive is the maximum number of address spaces in the system.
Use the IEAMRMF3 macro for monitoring your system. Typically, a monitoring program issues the macro repeatedly to obtain samples over a period of time. For some invocations of the macro, the system might be unable to retrieve the data, and the caller receives a return code of 4. However, this is generally a temporary condition; if the caller was issuing the macro repeatedly, the caller should continue to do so and should receive data on subsequent invocations. If the caller receives return code 4 several times in succession, the caller should stop issuing the macro. How many times the caller issues the macro after a return code of 4 is up to the installation.
Under certain conditions, the system abnormally ends the caller of IEAMRMF3 with an X'0C4' abend code. The caller must supply its own recovery routine to capture this abend code and retry.
Requirements for the caller are:
Environmental factor | Requirement |
---|---|
Minimum authorization: | Supervisor state and PSW key 0 |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN=HASN=SASN or PASN¬=HASN¬=SASN |
AMODE: | 31-bit |
ASC mode: | Primary |
Interrupt status: | Enabled or disabled for I/O and external interrupts |
Locks: | No locks held, except the CPU lock if the caller is disabled for I/O and external interrupts. |
Control parameters: | Must be in the primary address space |
The caller must obtain storage for the output returned by this macro. See the OUTAREA parameter for further information.
If a separate module examines the data returned by IEAMRMF3, that module must also include the IHADSD mapping macro.
For the mappings provided by the IHAASVT, CVT, IHADSD, and IHAPSA mapping macros, see the information in z/OS MVS Data Areas in the z/OS Internet library.
None.
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 caller issued the macro. 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.
On entry to IEAMRMF3, general purpose register (GPR) 13 must contain the address of a 72-byte standard save area. If the caller is disabled, the save area must be pagefixed.
None.
The standard form of the IEAMRMF3 macro is written as follows:
Syntax | Description |
---|---|
name | name: Symbol. Begin name in column 1. |
␢ | One or more blanks must precede IEAMRMF3. |
IEAMRMF3 | |
␢ | One or more blanks must follow IEAMRMF3. |
OUTAREA=area name | area name: Symbol. |
The parameter is explained as follows:
The caller must obtain storage for area name on a fullword boundary, in the caller's primary address space. The caller is not required to initialize area name. If the caller is disabled, area name must be pagefixed.
(DSDRSVD - DSDELEM) + (length of DSDRSVD)
(ASVTMAXU * length of an element) + (length of DSDFIXED)
ASVTMAXU is a field in the ASVT data area. DSDFIXED, DSDRSVD, and DSDELEM are fields in the DSD data area.
When control returns from IEAMRMF3, GPR 15 contains one of the following return codes:
Hexadecimal Return Code | Meaning and Action |
---|---|
00 | Meaning: Data successfully collected. Action: None. |
04 | Meaning: The system was not able to gather
the data on this invocation of the macro. Action: Reissue the macro. If you receive return code 4 several times in succession, you need to stop issuing the macro and inform your technical support personnel. |
Issue the IEAMRMF3 macro to obtain address space dispatchability data. The caller in this example is enabled for I/O and external interrupts, and is APF-authorized.
MONITOR CSECT
MONITOR AMODE 31
MONITOR RMODE ANY
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R5 EQU 5
R6 EQU 6
R7 EQU 7
R8 EQU 8
R9 EQU 9
R10 EQU 10
R11 EQU 11
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
*
USING *,R15 Establish addressability
*
STM R14,R12,12(R13) Save registers in caller's save
* area
DROP R15
LR R12,R15 Copy base register R12 because R15
* is volatile across interfaces used
* in this module
@PSTART EQU MONITOR
USING @PSTART,R12 Reestablish addressability using
* R12 as base register
****************************************************************
*
* Invoke the IEAMRMF3 service to obtain address space
* dispatchability data.
*
****************************************************************
*
* Change to key 0, supervisor state
*
MODESET KEY=ZERO,MODE=SUP
*
* Obtain storage for a register save area to pass to IEAMRMF3
*
LA R0,72
GETMAIN RU,LV=(R0)
LR R4,R13 Save the caller's save area
* address
LR R13,R1 Get address of save area to
* pass to IEAMRMF3
*
* Calculate the size of the storage to obtain for the output from
* IEAMRMF3:
* (ASVTMAXU * length of an element) + (length of DSDFIXED)
*
USING PSA,0
L R2,FLCCVT Get pointer to the CVT from the
* PSA
L R9,CVTASVT-CVTMAP(,R2) Get pointer to the ASVT from
* the CVT
L R9,ASVTMAXU-ASVT(,R9) Get ASVTMAXU
LA R11,ELEMSIZE Get the length of an element
MR R8,R11 Multiply
LA R6,L'DSDFIXED Get the length of DSDFIXED
AR R9,R6 Add to get total
*
* Obtain storage for the DSD data area
*
GETMAIN RU,LV=(R9)
*
* Issue the IEAMRMF3 macro to return address space dispatchability data
* Note: Register 13 contains the address of the 72-byte save area to
* pass to IEAMRMF3.
*
LR R6,R1 Move address of storage that
* was just obtained into R6.
*
USING DSD,R6 Map the DSD on the storage area
* that was just obtained.
*
IEAMRMF3 OUTAREA=DSD Issue the IEAMRMF3 macro passing
* the DSD data area to be used for
* the output.
*
LTR R15,R15 Check return code from IEAMRMF3.
BNZ NODATA For a nonzero return code,
* do not attempt to look at data.
*
* Look at the elements that are filled in by using the DSDINDXF field
* to find the first element, and the DSDINDXN field to chain to
* the next element.
*
LH R11,DSDINDXF Get the index of the first entry
* that is filled in. If the value
* is x'FFFF' then no entries are
* filled in.
L R7,DSDAPTR Get the address of the array
NEXTELEM DS 0H
CH R11,=X'FFFF' If the index is x'FFFF' then
* this is the last element that is
* filled in.
BE ALLDONE There are no more elements to
* process.
BCTR R11,0 Decrement the index by 1. The
* entry for ASID 1 is the first
* entry.
LA R2,ELEMSIZE Get the element size
MR R10,R2 Multiply the index by the
* element size.
AR R11,R7 Add the array pointer and the
* result to obtain the address of
* the entry that we want to look at
USING DSDELEM,R11
* . This area contains whatever code
* . the routine uses to look at the
* . required fields.
*
LH R11,DSDINDXN Obtain the index of the next
* entry to look at.
DROP R11
B NEXTELEM Go process the next element
*
NODATA DS 0H
LR R2,R15 Save the nonzero return code
* from IEAMRMF3 in R2. R15 is
* volatile across the interfaces.
B FREESTOR
ALLDONE DS 0H
*
* Set a return code of zero.
*
LA R2,0 Save the zero return code that
* this module sets in R2. R15 is
* volatile across the interfaces.
*
FREESTOR DS 0H
*
* Free the storage for the register save area passed to IEAMRMF3.
*
LA R0,72
FREEMAIN RU,LV=(R0),A=(13)
*
* Restore the caller's save area address
*
LR R13,R4
*
* Free the storage for the DSD data area
*
FREEMAIN RU,LV=(R9),A=(6)
DROP R6 Drop addressability to the
* DSD data area.
*
* Change to problem state, not key 0
*
MODESET KEY=NZERO,MODE=PROB
*
LR R15,R2 Copy the return code to
* R15.
L R14,12(R13)
LM R0,R12,20(R13)
BR R14 Return to the caller
DROP R12
*
* Equate for length of an element:
*
ELEMSIZE EQU DSDRSVD-DSDELEM+L'DSDRSVD
EJECT
IHAASVT LIST=NO Mapping macro for the ASVT
EJECT
CVT DSECT=YES,LIST=NO Mapping macro for the CVT
EJECT
IHADSD LIST=YES Mapping macro for the DSD
EJECT
IHAPSA LIST=NO Mapping macro for the PSA
END MONITOR