IEAMRMF3 — Obtain address space dispatchability data

Description

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 output you receive from this macro contains an array of elements, with each element representing an address space. For each address space, the system indicates that the address space is one of the following:

Dispatchable and running on a processor
Dispatchable and waiting to run on a processor
Not dispatchable.

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.

Environment

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

Programming requirements

The caller must obtain storage for the output returned by this macro. See the OUTAREA parameter for further information.

Include the following mapping macros in the module that calculates the size of the storage area for the output:

IHADSD, which maps the DSD data area
IHAASVT, which maps the ASVT data area
CVT, which maps the CVT data area
IHAPSA, which maps the PSA data area

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.

Restrictions

None.

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 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.

When control is returned to the calling program, the GPRs contain:

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

When control is returned to the calling program, the 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 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.

Parameters

The parameter is explained as follows:

OUTAREA=area name

The required parameter that specifies the name of the area of storage to contain the output from the macro. The output contains an array of elements; each element represents an address space. The output is mapped by the IHADSD mapping macro.

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.

Before issuing IEAMRMF3, you need to determine the size of the output area and obtain storage for it. To do so, use the following formula to determine the length of an element:

(DSDRSVD - DSDELEM) + (length of DSDRSVD)

Then, use that value in the following formula to determine the total size of area name:

(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.

For each element representing an address space, the following are true:

If the DSDUSING bit in the DSD is on, the address space is dispatchable and running on a processor.
If the DSDWAIT bit in the DSD is on, the address space is dispatchable and is waiting to run on a processor.
If neither the DSDUSING bit nor the DSDWAIT bit in the DSD is on, then either the address space is not dispatchable or the element does not represent a valid address space.

Return codes

When control returns from IEAMRMF3, GPR 15 contains one of the following return codes:

Table 1. Return Codes for the IEAMRMF3 Macro
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.

Example

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.

In this example, the caller issues IEAMRMF3 only once. If the return code from IEAMRMF3 is zero, the caller loops through the elements to look at the data, and does not issue the macro again. If the return code is not zero, the caller does not make another attempt to obtain data. A more typical scenario would be to issue the macro repeatedly if the return code is zero to obtain data over a period of time, and to issue the macro again even if the return code is 4, hoping to obtain data on a subsequent invocation. This example is intended only as an illustration of how to issue the macro, and an illustration of one way you might look at the data returned by the macro.

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