ibm / zos-bcpii

zOS Base Control Program internal interface

zOS-BCPii

zOS Base Control Program internal interface

Base Control Program internal interface (z/OS BCPii)

• Allows authorized z/OS applications to have HMC-like control over systems in the process control (HMC) network.
• Does not use any external network; Communicates directly with the SE rather than going over an IP network.
• A z/OS address space that manages authorized interaction with the interconnected hardware.
  
  

This repository contains samples that take advantage of new z/OS BCPii HWIREST interface to issue various requests against the CPC and more.

System Requirements for HWIREST invocation

• minimum IBM Z15 hardware level for:
  • SE and HMC associated with the local and target CPC
• mimimum BCPii microcode level applied to the corresponding SE and HMC:
  • SE 2.15.0 with MCL P46598.370, Bundle S38
  • HMC 2.15.0 with MCL P46686.001, Bundle H25
• minimum BCPii level
  • z/OS 2.4 with APAR
    • OA60351
    • OA61976 - TSO/E and ISV REXX env

HWIREST Interface Considerations

• C, Assembler

  • Request Body maximum 64KB
  • Response Body maximum 15MB

• System/ISV REXX

  • Request Body maximum 64KB
  • Response Body maximum 2.5MB

• TSO/E REXX

  • Request Body maximum 32767 bytes
  • Response Body maximum 2.5MB

Usage Notes

• In the event the SE System BCPii Permissions on the Security panel are NOT granted in order to restrict access to LPARs only (disallow CPC access), the application should use the following List Permitted Logical Partitions REST API to obtain the URI and Target Name information for the target LPAR
  • GET /api/console/operations/list-permitted-logical-partitions

Example-QueryInfo-REXX

This sample demonstrates how to use the BCPii HWIREST REXX interface to query CPC and LPAR information.

Example-LPARActivate-C

This sample demonstrates how to use the BCPii HWIREST C interface to activate an LPAR and POLL to determine if the operation was successful.

Example-LPARLoad-SystemRexx

This sample demonstrates how to use BCPii HWIREST SYSTEM REXX interface to load an LPAR, including a possible activation of the LPAR before hand.

Example-LPARLoad-Rexx

This sample demonstrates how to use BCPii HWIREST in a TSO/E REXX or ISV REXX interface to load an LPAR, including a possible activation of the LPAR before hand.

Example-Energy-REXX

This sample uses BCPii HWIREST REXX interface to retrieve energy management information for a target CPC. The results are stored in .csv format, in a member in a z/OS data set.

Example-Audit-REXX

This sample uses BCPii HWIREST REXX interface to audit LPARs on a target CPC. The results are stored in .csv format, in a member in a z/OS data set.

Example-Crypto-REXX

This sample uses BCPii HWIREST REXX interface to retrieve crypto information from image activation profiles associated with LPARs located on a specific CPC. The results are stored in .csv format, in a member in a z/OS data set. Note the crypto properties are valid on z16 processors or higher.

Example-CustomUsrGrp-REXX

This sample uses BCPii HWIREST REXX interface to list custom user groups and group members located on a specific CPC (SE). It can also be used to add an LPAR to a custom user group or remove an LPAR from a customer user group.

Publication References:

• Syntax of HWIREST and other useful BCPii information: IBM z/OS MVS Programming: Callable Services for High-Level Languages

• REST API operations documentation, including HTTP Status, error reason codes, etc.

  • Hardware Management Console Web Services API

• MVS System Management Facilities (SMF): BCPii SMF 106

• MVS System Codes: BCPii System Code '042'X

• MVS System Messages, Vol 6 (GOS-IEA) HWI mesages

• z/OS MVS Diagnosis: Tools and Service Aids - SYSBCPII component trace

• zOS Hot Topics: BCPii - A RESTed development

  • 2022 Hot Topics -> BCPii - A RESTed development

Other useful references:

• z/OS client web enablement toolkit: JSON Parser
• z/OS client web enablement toolkit github

zos-bcpii's Issues

Sample for updating the defined capacity of an LPAR

Thanks for those samples who helped me a lot to retrieve LPAR/Images/CPC/etc... parameters.

I now want to update the Defined capacity of an LPAR through BCPII. I know how to do it with the previous BCPII method but do not find how to do it with this new way of working ?

Can you provide a sample for it ?

Thanks,
François

LPARs which can send BCPII commands

Hi,

Through the HMC console, in the security tab that can be found in the image profiles, we can specify if an LPAR can send BCPII command and/or can receive BCPII commands from other LPARs. If an LPAR can receive command, we have the choice to speficy that all LPARs can send commands to the LPAR associated to the profile or we can specify an explicit list of LPARs that can send BCPII commands to.

I do not find how to retrieve those informations through a BCPII program. At our site, because we are service provider with multiple customers, we have to specify explicit list of LPARs that can send commands. It would be usefull for us to be able to retrieve this information via a BCPII program.

Other question : is it possible to perform those definitions via BCPII or do we have to do it exclusively via the HMC console. It is a fastidious job (because we have lot of partitions and lot of customers....); would be interresting for us to do it via BCPII (Of course, the first LPAR has to be defined manually in the HMC console; but then, from this LPAR, we should be able to do the other definitions).

Thanks in advance,
François

Error executing

Hi, seems to me an environmental error but I could not find any information or where to look. I have GDPS in place so BCPii configuration is not a problem here but using this rexx it gives me following error:

Rexx RC: (0)
HTTP Status: (500)
Reason Code: (4212)

I really understand that this Rexx is provided "AS IS" but if you have any tip on how to check the errors, I would appreccicate.

Thanks!