Easy access to fantastically important service level Information


Now that we've turned the corner on using z/OSMF for the z/OS platform installation method, we're revving up with exploiting z/OSMF for additional capabilities.  I'd like to discuss the latest delivery which I think will be very helpful to use, especially if you are keen on automating common tasks.  

Let's look at an extremely ubiquitous use case - well, really, three - for retrieving service information about your z/OSMF software instances*.    With the new z/OSMF REST APIs that were delivered in APAR PH47050 on z/OS V2.5, it is now incredibly simple to write a program to answer these questions:

  1. What are the missing critical fixes I need on a specific software instance?  [Remember, critical fixes are any unresolved PE PTFs, HIPERs, or other exception SYSMODs which you can identify with ERROR HOLDDATA. ]
  2. What PTFs am I missing for FIXCAT s on a specific software instance?  [Remember, FIXCATs are essential to knowing if you have all the PTFs necessary for many reasons, such as position for the new IBM z16.]
  3. Do I have these PTFs installed on a specific software instance?  This is just a simple query, however, this is a basic service that we need for many reasons.
Now would be a fairly good time to note, that all these queries are also available from within the z/OSMF user interface itself (Actions --> Maintenance Reports --> Missing Critical Service, Missing FIXCAT Service, and SYSMOD Search). 

z/OSMF Software Management user interface

Because programming in modern languages is easy and common in the marketplace, allowing these programs to make use of the z/OSMF Software Management REST APIs gives us a way to open up an entire enterprise to fast automation capabilities with lower skill requirements.  In fact, because these three REST APIs have been added to Ansible as roles (in Galaxy v1.3.0  and the Automation Platform) and with sample playbooks, getting them into productive use can be very fast.  

Let's imagine a task that would be rather cumbersome today...your manager comes to you and says, "We are going to buy that lovely IBM z16 soon, and I want to know across our 30 LPARs if every system has the proper required PTFs installed or if we need to schedule a maintenance window next weekend to roll them into test."  

Today, I reckon the steps would be:

  1. Gather up the list of all the SMP/E CSIs that represent the software on the 30 LPARs you have.  I really hope that that is something that everyone even has!  Let's say that was, at most, 30 SMP/E CSIs.  It could be many more than that, if you also include middleware on those LPARs.  
  2. Now, for each of those 30 CSIs, you'd need to run a REPORT MISSINGFIX command for the the z16 Required FIXCAT.  You might even need to look it up the FIXCAT name as you probably haven't used it before, to get it correctly specified on the command.  
  3. Across those 30 reports you received back, you'd need to consolidate them manually to understand which systems are and are not at the right service level.  
  4. Each time you wanted to verify this, for instance right before you IPLed the IBM z16, you'd need to repeat each of these manual steps.  

With the new z/OSMF REST APIs, you could  write a simple program (or model after a playbook) once, and reuse it for any FIXCAT ever.  The steps in the program or playbook might be:

  1. Ask z/OSMF to give you back all the software instances in the enterprise.  
  2. For each of those software instances, query for missing FIXCATs.  All applicable PTFs with their associated FIXCATs will be returned. 
  3. Scan through the results for "z16" (or another term you input for other purposes), and determine programmatically by software instance, which system needs updating when PTFs are returned as missing for that term.  
  • By the way, the above z/OSMF steps can be done interactively with z/OSMF Software Management interface too.  Even the the first step, where you can select in a single click all your z/OSMF software instances!  My point is that z/OSMF will do a lot of heavy lifting, across your entire enterprise from a single dashboard or program.  z/OSMF can do this as it has a repository of all your software instances and can communicate with all your systems through your network from a central point.   
Do you want to see these new REST APIs in action, without even writing a program?  Try them out interactively in a couple of clicks now.  If you've got the Swagger service set up for z/OSMF, and the APAR above installed, just drive them through your web browser.   Note, these services are asynchronous, because as you can expect, they might be long running.  With that mind you receive a status monitor id on your query, and then you retrieve the results of your query with that same status monitor id.  

Look under the Software Management APIs section for these services:

POST /zosmf/swmgmt/swi/{system-nickname}/{swi-name}/missingcriticalupdates

...and then review the status using the status-monitor-id in the response message:

GET /zosmf/swmgmt/statusmonitor/missingcriticalupdates/{status-monitor-id}

GET /zosmf/swmgmt/statusmonitor/missingfixcatupdates/{status-monitor-id}

One other handy trivia item:  if you use either the z/OSMF Software Management REST APIs or the user interface, you can also see the date that the Enhanced HOLDDATA was received which you are using for the queries.  This information isn't available with the traditional SMP/E interface  - you've got to be using z/OSMF to see this.

"lastholdrecvdate": "2023-02-16T17:26:54Z",

Oh yeah, maybe another handy trivia item:  All the above is vendor-agnostic.  These new services do not care which vendor products you might be using, since it is all "standard" SMP/E.  

I hope that those interested in these new services find value in writing programs and driving automation to make their jobs easier.  I know I have.  


*What is a z/OSMF software instance?  This is a deployable software unit within z/OSMF Software Management.  A software instance is composed of the SMP/E environment (CSIs and the data sets they refer to, if it happens to be SMP/E installed), and possibly other data sets.  If the software isn't SMP/E installable, then it's just a collection of data sets that you identify.  A software instance has a name, and is kept track of in the z/OSMF repository.  You can create a software instance from any installed software (SMP/E packaged or not) that you've already got on your system.  The hardest part is just knowing what you'd like to call it!