BCPii - A RESTed development

This article was updated on August 11, 2022.

Hopefully you got the play on words… (from the sitcom “Arrested Development”). For those programmers not familiar with BCPii, it provides a way for authorized applications running on z/OS to programmatically interact with IBM Z hardware. The application can query, change, and perform operational procedures, e.g., activating an LPAR, by using the set of provided BCPii APIs. These APIs use internal communication paths between the z/OS operating system and the hosting hardware, thus avoiding the IP network (intranet).

So, if you’re a z/OS systems programmer, what can you do with BCPii? Well, you can do some neat things. How many times have you needed to get the attributes of an LPAR (i.e., number of CPs or amount of memory)? Prior to BCPii, this required logging on to the HMC, going through the appropriate panels and updating an offline spreadsheet or document. But, as most of us found out, sometimes a systems programmer updates the LPAR configuration on the HMC and forgets to notify the document owner, leading to confusion and possible problems! So, what is a z/OS systems programmer to do? BCPii to the rescue!

However, as years and multiple new hardware releases have gone by, if you’re an existing BCPii user, you may have noticed BCPii started lagging a bit (or a lot) behind the attributes available on the SE/HMC GUI. Introducing HWIREST, the latest addition to the set of BCPii APIs, which made its official debut in 2Q2021¹ on z15. If you fall into the existing group of users, this new addition gives you the ability to access and update many new attributes, including storage-class memory! It also gives TSO/E REXX and ISV REXX applications the ability to issue commands previously not permitted for those environments, for example, activate and load LPARs, and issue requests to the console.

HWIREST is a conduit that gives a z/OS application the ability to issue a core set of REST APIs as defined in “Chapter 11: Core IBM Z resources”, of the IBM Z Hardware Management Console Web Services API publication.

This single API is used to perform all forms of requests, from query through LPAR activation, all the while using the internal communication path to the hardware.

HWIREST adheres to the same set of BCPii authorization requirements that are in place for the existing APIs. So, if you already have a set of HWI.* FACILITY class profiles defined, you can reuse them for your interaction with HWIREST. The main difference is the identification that is associated with each resource, CPC, LPAR, CapRec, and others. The existing APIs use the concept of a connection token to uniquely identify the resource after a connection to that resource is established. The token contains the netid.nau and possibly an additional name value that is associated with the specific resource. That information is then used to build the SAF profile to use for authorization of the request. Unlike its siblings, HWIREST does not have a connection token. Instead, each resource’s identity is formed by a combination of the URI and target name that is passed as input on the request. That identity is then used to build the corresponding SAF profile.

You are probably thinking, “how do I obtain the URI and target name?” Numerous LIST operations are available for each supported resource:

Each LIST operation request returns various pieces of information for each entity, including the object-uri (CPCs, LPARs, Profiles) or element-uri (Capacity Record) and target-name.

For example, to obtain a list of CPCs you issue the List CPC Objects operation. That operation returns an array of CPC entities, each of which includes the unique URI for that CPC (value of the object-uri property), and the targeting information for that CPC (value of the target-name property). Those two pieces of information form the CPC identity.

Your application builds on this data and/or reuses it for all subsequent requests that are associated with that CPC.

One example of a subsequent request is to query storage-related properties on that CPC. Specifically, you can query the total storage that is installed, the storage available for a customer, and the total VFM storage. The first step is to find the corresponding CPC properties names. The CPC Data Model section in chapter 11 of the Hardware Management Console Web Services API publication (Chapter 11 -> CPC object -> Data Model) contains all the various properties available for a CPC. In the Data Model section, scroll a bit to find the properties you are seeking, storage-total-installed, storage-customer, and storage-vfm-total:

The next step is to figure out the syntax of the GET CPC Properties operation (Chapter 11 -> CPC object -> Get CPC Properties) that will be used to query those properties.

The operation syntax (Figure 2) is broken down as follows:

When all the various pieces of information are combined, you can form the following HWIREST request:

If the request is successful, your response parm contains the following output:

Putting it all together into a picture, here is the request and response:

One of the things you might have noticed in the previous example is that the response content is always in JSON format. HWIREST uses JSON as the format for the request and response data content. It supports both UTF-8 and IBM-1047-character encoding. In case you are worried you must code up a JSON parser yourself, I would like to shamelessly pitch and highly recommend the z/OS client web enablement toolkit JSON Parser, which is built into the z/OS base, for all your JSON parsing needs.

The other thing that you might have noticed is that there is nothing that resembles a return code parameter that is typically found in a z/OS API. Don’t fret! HWIREST is staying true to its RESTful nature; on success it returns an HTTP status value in the 200-299 range (Chapter 3. Invoking API operations -> HTTP status codes).

A value outside of that range indicates an error and additional information that will help explain the error will be provided in the accompanying reason code and response body. In addition to documenting HTTP status codes, Chapter 3 in Hardware Management Console Web Services API publication is also where you’ll find the error response bodies section that defines the various fields included in the response body on error and descriptions of the various reason codes you could encounter.

Now for a few words about the HWIREST parameters, two to be exact, one for the content of request (input) and one that contains the result of the request (output).

The request parameter is broken down into various fields that correspond to content in the Hardware Management Console Web Services API, though the names might vary slightly.

The response parameter is broken down in a similar fashion; its various fields correspond to content in the Hardware Management Console Web Services API.

You might have noticed a bit of a trend by now. The MVS Programming: Callable Services for High-Level Languages publication helps you understand the syntax of HWIREST, but after you learn how to interact with this API, you might never need to return to it again because all the content is in the Hardware Management Console Web Services API.

The full list of supported REST API operations through HWIREST can be found in “Appendix A: Base Control Program internal interface (BCPii)” in Hardware Management Console Web Services API. In addition to the information in Appendix A, each supported operation includes the verbiage: “This operation is supported using the BCPii interface.”

Now you’re thinking, okay but what about the various attributes, in the Data Model and in the operation descriptions. The attribute is supported unless there is an explicit note in the description that states: “This property is only returned when the web services interface was used for the request.”

Before you try out the new API, let’s talk about asynchronous requests (have I mentioned you can issue these out of TSO/E REXX and ISV REXX environments?). Some REST API operations, such as Activate Logical Partition, are asynchronous (Chapter 11 -> Logical Partition -> Activate Logical Partition):

The response body that is returned contains a job URI. That job URI is associated with the asynchronous job processing operation (Chapter 7 -> Asynchronous job processing):

Your application uses HWIREST to poll that JOB URI to determine the result of the asynchronous request.

Have we got some samples for you! You can find them at: https://github.com/IBM/zOS-BCPii. One of the samples, RXAUDIT1, goes to the CPC and lists attributes, number of general-purpose CPs, zIIPs, storage, etc., for all LPARs. It then stores the results, which are in .csv format, in a z/OS data set member. You can then import the content into Microsoft™ Excel or another application of your choice.

z/OS BCPii is excited to introduce you to its newest member, HWIREST API. This API provides a new REST-like interface for applications to use to access many previously unavailable attributes and allows TSO/E REXX and ISV REXX applications the ability to issue commands previously not permitted for those environments. In addition, as firmware updates are applied that introduce new attributes to currently supported resources, you no longer have to wait for z/OS to make its corresponding APAR available. In most cases, you can access the new attributes instantaneously!

Galina Gorelik is the product owner of z/OS BCPii and z/OS client web enablement toolkit.

Neil Shah is an IBM z/OS Systems Programmer.

Anne Romanowski contributed to the editorial review of this article.

Image created by Izzi Cain.