zinfo - ZOAU provides programmatic access to z/OS facts

With zinfo, you can use z/OS shell commands or Python to retrieve and display facts about a z/OS system, and then output the results to a JSON string. What’s more, with zinfo, you can gather and report z/OS system facts to products on other platforms, such as Ansible. zinfo is the newest addition to Z Open Automation Utilities (ZOAU), a runtime that supports automation tasks on z/OS in the UNIX System Services environment. Learn more about ZOAU.

Many facts about a z/OS system can be accessed by issuing the DISPLAY operator command. But the DISPLAY command output isn’t designed to be a programming interface, so obtaining programmatic access to any single fact requires string manipulation, such as with awk, sed, grep, or cut. Because such manipulation is prone to errors and corner cases, relying on DISPLAY can lead to parsing failures.

Using zinfo strictly as a command line utility inside z/OS UNIX System Services requires similar string manipulation. Though zinfo presents facts with more consistency than DISPLAY, using it just to display system facts in a text format doesn’t bring much improvement. The real value comes from its ability to output a JSON string.

The JSON format easily integrates into the existing Ansible fact-gathering infrastructure. Moreover, Python dictionaries and JSON objects play well together. So from a usability perspective, the JSON format is a clear winner. And though the zinfo command line utility does not currently offer variable access to individual components, ZOAU offers a Python library — and the Python interface does!

Because JSON enjoys wide support in APIs and automation platforms, it’s easy to use any zinfo fact in such environments. For environments that do not support JSON, a plain text output option is available, which opens the door to creating generalized scripts that run the same on any z/OS system.

The zinfo utility presents facts in a clear and consistent manner, which makes it easier to write and understand z/OS scripts and automation, hand off pieces of code to different developers, and bring new hires up to speed. For example, accessing the contents of the IEASYM card through the zinfo Python interface is as simple as accessing a variable. Compare that to the task of guiding a new developer through the steps: start at memory address 0 (also known as the PSA), jump to memory address 16 where the CVT lives, gain access to the offset where the IHAIPA control block can be found, then go to offset 48 to access IPALPDSN. Even with clearly documented common control blocks, it’s far simpler to let zinfo abstract away the details.

zinfo crawls z/OS control blocks to obtain information, which is done for both for reliability and performance reasons. Many control blocks are documented as programming interfaces, so their contents tend to be more stable and reliable than macros, DISPLAY commands, or other highly customized (and often inconsistent) sources of information. Plus, zinfo is designed for automation, so cross-system consistency is an important design principle; we know that today’s automation engineers want to write a single piece of code and apply it across many systems rather than tailor scripts to each system.

Facts come organized in subsets. Each subset is a sub-dict inside the overall JSON payload created by zinfo. The subsets categorize the facts in an easy-to-understand way and allow the collection of available facts to grow cleanly over time. Furthermore, you can use subsets to efficiently narrow down the types of facts queried by zinfo. In the first release there are about 20 facts available. As the collection grows, the ability to filter and dump only IPL facts will be beneficial. Compare this to a less-focused utility that dumps hundreds or thousands of facts straight to the console in an order determined by its own internal logic rather than by your use case.

Each subset name describes the set of facts contained within. For example, ipl refers to IPL info such as the load member and device number used for the IPL, the nucleus ID, the master catalog and volser at time of IPL, and so on. The cpu set of facts currently consists of only CPC (central processor complex) facts such as the model, type, serial, manufacturer, and sequence number. The sys subset contains system facts such as architecture level, system name, LPAR name, and sysplex name. Finally, the iodf subset contains facts related to the input/output definition file including the name, config ID, date, time, and the EDT (eligible devices table).

Because the collection of facts is meant to grow over time, the zinfo architecture is designed so that new subsets can be added with little to no effect on existing subsets.

The zinfo utility is available with ZOAU version 1.2.1. ZOAU is available as a stand-alone product or as part of the IBM Z and Cloud Modernization Stack Cloud Pak. If you have ZOAU installed, verify your existing version and refer to the Release Notes for your product to learn more.

The Red Hat Ansible ibm_zos_core zos_gather_facts module leverages zinfo to bring z/OS facts to Ansible. That module can be found on Ansible Galaxy or Ansible Automation Hub in any collection version higher than 1.5.

Ketan Kelkar is a Software Engineer on the Red Hat Ansible for IBM Z team. Ketan is the primary developer of the zinfo utility and the author of the Ansible zos_gather_facts module. Ketan holds a BS in Computer Science from the University of California, San Diego and joined IBM in 2019, right out of college.

Anthony Giorgio is a Senior Software Engineer with over 20 years of mainframe experience, and currently leads the Z Open Automation Utilities team. Anthony holds a BS and MS in Computer Science from the NYU Tandon School of Engineering.

Nate Myers contributed to the editorial review of this article.