Skip to main contentIBM Z Hot Topics

BCPii - A RESTed development

A new z/OS BCPii API, HWIREST, is introduced for the IBM z15. This API provides a simpler and more intuitive REST programming model for applications to use to access many previously unavailable attributes and instantly access future attributes that may become available.

BCPii - A RESTed development
Figure 0

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

Let’s meet the new API

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:

  • List CPC Objects - GET /api/cpcs
  • List Logical Partitions of CPC - GET /api/cpcs/{cpc-id}/logical-partitions
  • List Group Profiles - GET /api/cpcs/{cpc-id}/group-profiles
  • List Image Activation Profiles - GET /api/cpcs/{cpc-id}/image-activation-profiles
  • List Capacity Records - GET /api/cpcs/{cpc-id}/capacity-records …and many more

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.

{
"name": "T115",
"se-version": "2.15.0",
"location": "local",
"object-uri": "/api/cpcs/6666666-2222-bbbb-aaaa-aaaaaa",
"target-name": "IBM390PS.T115”
}

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:

Figure 1

Figure 1: CPC Data Model

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.

Figure 2

Figure 2: Get CPC Properties operation

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

  • GET is the required HTTP method, you’ll use HWIREST’s equivalent HWI_REST_GET constant.
  • /api/cpcs/{cpc-id} is the URI for your CPC which you obtained by issuing the initial LIST CPCs request -> "object-uri" = URI of CPC-> "/api/cpcs/6666666-2222-bbbb-aaaa-aaaaaa"
  • properties and cached-acceptable are optional query parameters that you can append to the CPC URI to filter what CPC properties are returned and the source of those values. If the properties filter is omitted, all the properties that are defined in the CPC Data Model are returned in the response for this request. In this case, let’s take advantage of the properties filter to explicitly state we want only the values for storage-total-installed, storage-customer, and storage-vfm-total returned to us in the response body.
  • In addition, you also need the targeting information for the CPC you are interacting with; this is the other piece of information you obtained by issuing the initial LIST CPCs request -> "target-name": "IBM390PS.T115”

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

requestParm.httpMethod = HWI_REST_GET
requestParm.uri = ‘/api/cpcs/6666666-2222-bbbb-aaaa-aaaaaa?properties=
storage-total-installed,storage-customer,storage-vfm-
total&cached-acceptable=true’
requestParm.targetName = ‘IBM390PS.T115’
requestParm.requestBody = <leave blank since this REST API doesn’t require a
request body>

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

responseParm.responseDate = Wed, 06 May 2021 18:05:36 GMT
responseParm.requestId = Sxbbbbbb-5555-1111-00000.1f3 Rxc
responseParm.httpStatus = 200 (OK)
responseParm.responseBody =
{
"storage-vfm-total":0,
"storage-customer":2883584,
"storage-total-installed":3145728
}

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

Figure 3

Figure 3: HWIREST 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).

Figure 4

Figure 4: 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.

Request parameter fieldsEquivalent content in the HMC Web Services API
httpMethodHTTP method for the REST API operation
uriURI for the REST API operation
targetNameX-API-Target-Name request header
requestBodyRequest body contents for the REST API operation
clientCorrelatorX-Client-Correlator request header
encodingValue of the charset used to encode all the input and output
requestTimeoutAmount of time the SE is given to carry out the request before giving up

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

Request parameter fieldsEquivalent content in the HMC Web Services API
responseDateDate response header
requestIdX-Request-Id response header
locationLocation response header
responseBodyResponse body contents for the REST API operation
httpStatusHTTP Status Code
reasonCodeReason

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.

How do you know which API is applicable to HWIREST in the Hardware Management Console Web Services API section?

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

Figure 5

Figure 5: How to tell if an 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.”

Figure 6

Figure 6: How to tell if a property is not supported in BCPii

Staying in sync with async

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):

Figure 7

Figure 7: Asynchronous results

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):

Figure 8

Figure 8: Query Job Status operation

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

Figure 9

Figure 9: Issuing an asynchronous request

Samples!

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.

Figure 10

Figure 10: Data obtained using the RXAUDIT1 sample

In Summary

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!

About the authors

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.


  1. HWIREST is available for BCPii on z/OS 2.4 with APAR OA60351 and is included in the base of later z/OS releases. An enhancement to HWIREST that allows access in TSO/E and ISV REXX environments to previously restricted REST API operations was made available in z/OS 2.4 and z/OS 2.5 with APAR OA61976. It is also included in the base of later releases. HWIREST requires a z15, SE 2.15.0 with MCL P46598.370, Bundle S38 or higher, and HMC 2.15.0 with MCL P46686.001, Bundle H25 or higher.