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