Description

Description

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

The BPXEKDA macro provides an interface for an authorized report application to retrieve kernel data, such as:

A list of current processes (for the entire system or for a specific userid)
A list of threads within a specific process
A list of current BPXPRMxx option settings
All system-wide file system information

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state
Dispatchable unit mode:	Task
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	31-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Programming requirements

If the supplied buffer is in the primary address space (ALET=0), BPXEKDA will protect the last page of the buffer to guard against overlays of storage following the buffer. If the buffer is not in the primary address space, the caller is responsible for protecting the last page of the buffer to prevent potential overlays.

Restrictions

None.

Input register information

Before issuing the BPXEKDA macro, the caller must ensure that the following general-purpose registers (GPRs) contain the specified information:

Register: Contents
0-12: Undefined
13: Address of a 72-byte register save area
14-15: Undefined

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0-1: Unpredictable
2-13: Unchanged
14: Next instruction address
15: Return code

Performance implications

None.

Syntax

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

Syntax	Description

`name`	`name`: symbol. The name is optional.

␢	One or more blanks must precede BPXEKDA.

BPXEKDA

␢	One or more blanks must follow BPXEKDA.

,KBUFLEN=`xkbuflen`	`xkbuflen`: RS-type address or register (2) - (12).

,KBUFALET=`xkbufalet`	`xkbufalet`: RS-type address or register (2) - (12).

KBUFPTR=`xkbufptr`	`xkbufptr`: RS-type address or register (2) - (12).

,RETCODE=`xretcode`	`xretcode`: RS-type address or register (2) - (12).

,MF=S	Default: MF=S

Parameters

The parameters are explained as follows:

name: An optional symbol, starting in column 1, that is the name on the BPXEKDA macro invocation. The name must conform to the rules for an ordinary assembler language symbol. Default: No name.
,KBUFLEN=xkbuflen: The name (RS-type) or address in register (2) - (12) of a required fullword field that contains the length of the supplied buffer. It is recommended that this buffer be at least 1 megabyte in length to contain all of the data that could be returned for the input request data. Upon successful completion, this area is defined by the mapping macro BPXZODMV. If BPXEKDA is unsuccessful, this area contains incorrect data.
,KBUFALET=xkbufalet: The name (RS-type) or address in register (2) - (12) of a required fullword field that contains the ALET of the supplied buffer.
KBUFPTR=xkbufptr: The name (RS-type) or address in register (2) - (12) of a required 4–byte area that contains the address of a required input/output area that is to contain the input request data and the output data to be returned by BPXEKDA. The mapping macro BPXZODMV maps all of this input and output data. The input request data is mapped by the OdmvInputParms field. The remainder of the BPXZODMV mapping macro describes data that is returned by BPXEKDA when it completes successfully.
,RETCODE=xretcode: The name (RS-type) of an optional fullword output variable, or register (2) - (12), into which the return code is to be copied from GPR 15.
,MF=S: An optional parameter that requests the standard form, which places parameters into an inline parameter list and invokes the BPXEKDA macro service. MF=S is the default.

Return codes

The following are the return codes from BPXEKDA and their explanations:

Table 1. Return Codes for the BPXEKDA Macro
Hexadecimal Return Code	Meaning and Action
00	Meaning: BPXEKDA completed successfully. Action: None required.
04	Meaning: The macro was unsuccessful. The supplied user name or ASID was not found. Action: None required.
08	Meaning: The macro was unsuccessful. An internal error occurred attempting to obtain file system mount data. Action: None required.
12	Meaning: The macro was unsuccessful. The supplied buffer was not large enough to hold all of the data that the macro attempted to return. Action: None required.
16	Meaning: The macro was unsuccessful. The input flags specified mutually exclusive values. Action: None required.
20	Meaning: The macro was unsuccessful. The caller does not have the correct authorization to use this service. Action: None required.
24	Meaning: The macro was unsuccessful. The caller did not specify the address of an output area in OdmvOutPtr. Action: None required.
28	Meaning: OMVS inactive Action: None required.