Description

Description

z/OS MVS Programming: Assembler Services Reference ABE-HSP
SA23-1369-00

Use the CSRSI service to retrieve system information. You can request information about the machine itself, the logical partition (LPAR) in which the machine is running, or the virtual machine hypervisor (VM) under which the system is running. The returned information is mapped by DSECTs in macro CSRSIIDF (for assembler language callers) or structures in header file CSRSIC (for C language callers).

The information available depends upon the availability of the Store System Information (STSI) instruction. When the STSI instruction is not available (which would be indicated by receiving the return code 4 (equate symbol CSRSI_STSINOTAVAILABLE), only the SI00PCCACPID, SI00PCCACPUA, and SI00PCCACAFM fields within the returned infoarea are valid. When the STSI instruction is available, the validity of the returned infoarea depends upon the system:

If the system is running neither under LPAR nor VM, then only the CSRSI_Request_V1CPC_Machine data are valid.
If the system is running under a logical partition (LPAR), then both the CSRSI_Request_V1CPC_Machine data and CSRSI_Request_V2CPC_LPAR data are valid.
If the system is running under a virtual machine hypervisor (VM), then all of the data (CSRSI_Request_V1CPC_Machine, CSRSI_Request_V2CPC_LPAR, and CSRSI_Request_V3CPC_VM) are valid.

You can request any or all of the information regardless of your system, and validity bits will indicate which returned areas are valid.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state, key 8-15
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	24- or 31-bit when using the CALL CSRSI form (or csrsi in C), 31-bit when using an alternate form
ASC mode:	Primary
Interrupt status:	Enabled or disabled for I/O and external interrupts.
Locks:	The caller may hold a LOCAL lock, the CMS lock, or the CPU lock, but is not required to hold any locks.

Programming requirements

The caller should include the CSRSIIDF macro to map the returned information and to provide equates for the service.

Restrictions

None.

Input register information

The caller is not required to set up any registers.

Output register information

When control returns to the caller, the 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

Performance implications

None.

Syntax

Syntax	Description
CALL CSRSI	(Request ,Infoarealen ,Infoarea ,Returncode)

In C: the syntax is similar. You can use either of the following techniques to invoke the service:

1.  CSRSI (Request,...Returncode);

When you use this technique, you must link edit your program with a linkage-assist routine (also called a stub) in SYS1.CSSLIB.

2.  CSRSI_byaddr (Request,...Returncode);

Both of these techniques require AMODE=31. If you use the second technique, before you issue the CALL, you must verify that the CSRSI service is available (in the CVT, both CVTOSEXT and CVTCSRSI bits are set on).

In Assembler: Link edit your program with a linkage-assist routine (also called a stub) in SYS1.CSSLIB unless you use either of the following techniques as an alternative to CALL CSRSI:

1.  LOAD EP=CSRSI
    Save the entry point address
    ...
    Put the saved entry point address into R15
    Issue CALL (15),...

2.  L   15,X'10'                  Get CVT
    L   15,X'220'(,15)
    L   15,X'30'(,15)             Get address of CSRSI
    CALL (15),(...)

Both of these techniques require AMODE=31. If you use the second technique, before you issue the CALL, you must verify that the CSRSI service is available (in the CVT, both CVTOSEXT and CVTCSRSI bits are set on).

Parameters

The parameters are explained as follows:

(Request

Supplied parameter:

Type: Integer
Length: Full word

Request identifies the type of system information to be returned. The field must contain a value that represents one or more of the possible request types. You add the values to create the full word. Do not specify a request type more than once. The possible request types, and their meanings, are:

CSRSI_Request_V1CPC_Machine: The system is to return information about the machine.
CSRSI_Request_V2CPC_LPAR: The system is to return information about the logical partition (LPAR).
CSRSI_Request_V3CPC_VM: The system is to return information about the virtual machine (VM).

,Infoarealen

Supplied parameter:

Type: Integer
Range: X'1040', X'2040', X'3040', X'4040'
Length: Full word

Infoarealen specifies the length of the infoarea parameter.

,Infoarea

Returned parameter:

Type: Character
Length: X'1040', X'2040', X'3040', X'4040' bytes

Infoarea is to contain the retrieved system information. (Infoarealen specifies the length of the provided area.) The infoarea must be of the proper length to hold the requested information. This length depends on the value of the Request parameter.

When the Request parameter is CSRSI_Request_V1CPC_Machine, the returned infoarea is mapped by SIV1 and the infoarealen parameter must be X'2040'.
When the Request parameter is CSRSI_Request_V1CPC_Machine plus CSRSI_Request_V2CPC_LPAR, the returned infoarea is mapped by SIV1V2 and the infoarealen parameter must be X'3040'.
When the Request parameter is CSRSI_Request_V1CPC_Machine plus CSRSI_Request_V2CPC_LPAR plus CSRSI_Request_V3CPC_VM, the returned infoarea is mapped by SIV1V2V3 and the infoarealen parameter must be X'4040'.
When the Request parameter is CSRSI_Request_V1CPC_Machine plus CSRSI_Request_V3CPC_VM, the returned infoarea is mapped by SIV1V3 and the infoarealen parameter must be X'3040'.
When the Request parameter is CSRSI_Request_V2CPC_LPAR, the returned infoarea is mapped by SIV2 and the infoarealen parameter must be X'1040'.
When the Request parameter is CSRSI_Request_V2CPC_LPAR plus CSRSI_Request_V3CPC_VM, the returned infoarea is mapped by SIV2V3 and the infoarealen parameter must be X'2040'.
When the Request parameter is CSRSI_Request_V3CPC_VM, the returned infoarea is mapped by SIV3 and the infoarealen parameter must be X'1040'.

,Returncode)

Returned parameter:

Type: Integer
Length: Full word

Returncode contains the return code from the CSRSI service.

Return codes

When the CSRSI service returns control to the caller, Returncode contains the return code. To obtain the equates for the return codes:

If you are coding in assembler, include mapping macro CSRSIIDF, described in z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/.
If you are coding in C, use include file CSRSIC.

The following table describes the return codes, shown in decimal.

Return Code (decimal)	Equate Symbol Meaning and Action
00	Equate Symbol: CSRSI_SUCCESS Meaning: The CSRSI service completed successfully. All information requested was returned. Action: Check the si00validityflags field to determine the validity of each returned area.
04	Equate Symbol: CSRSI_STSINOTAVAILABLE Meaning: The CSRSI service completed successfully, but since the Store System Information (STSI) instruction was not available, only the SI00PCCACPID, SI00PCCACPUA, and SI00PCCACAFM fields are valid. Action: None required.
08	Equate Symbol: CSRSI_SERVICENOTAVAILABLE Meaning: Environmental error: The CSRSI service is not available on this system. Action: Avoid calling the CSRSI service unless running on a system on which it is available.
12	Equate Symbol: CSRSI_BADREQUEST Meaning: User error: The request parameter did not specify a word formed from any combination of CSRSI_Request_V1CPC_Machine, CSRSI_Request_V2CPC_LPAR, and CSRSI_Request_V3CPC_VM. Action: Correct the parameter.
16	Equate Symbol: CSRSI_BADINFOAREALEN Meaning: User error: The Infoarealen parameter did not match the length of the area required to return the requested information. Action: Correct the parameter.
20	Equate Symbol: CSRSI_BADLOCK Meaning: User error: The service was called while holding a system lock other than CPU. LOCAL/CML, or CMS. Action: Avoid calling in this environment.