Skip to main content

How to Effectively Document Mainframe Architecture

Mainframe architecture needs to be drafted and kept up to date. What can you do today to make sure you have solid mainframe architecture topology and are ready for an outage?

Pile of documents on a desk.

A while back I was asked to determine why a customer had been unable to use one of their IBM Mainframe Virtual Tape System (VTS) devices for close to two years. When it was installed they had it powered up on the data center floor, had a customer engineer perform the required installation testing, connected it to the network, verified they could ping the IP but could never read or write to it even though they had confirmed it was properly, logically connected to their existing VTS system. The device checked out correctly in every way. All the tests netted correct results, yet this device would not process anything. No reads. No writes. My first question was. “Can you show me the architectural diagrams for this device and its connections?” The answer was:
“There is no documentation. No one ever asks us for that. We never create those. We have everything we need via the screens and panels we use when we remote into the device. Documentation is something we don’t have time to do. No one uses documentation like that anyway.”
Really? Documentation wasn’t necessary but this problem was waiting to be solved for two years! It was fortunate that this problem was isolated to a specific device, but infrastructure, systems and applications are increasingly complex, utilize multiple platforms, have many layers, encompass dozens of disciplines and are often spread across different geographies. When trouble strikes, the first question that should be asked is “What does the architecture look like?”

Documenting Architecture Is Crucial 

Without the proper view of the architecture you are lost and the longer you will search for a solution. This may seem obvious but often, some organizations do not have this understanding at the proper level nor with the correct individuals. There may be extremely detailed network diagrams for certain pieces of infrastructure or detailed application topology for systems and programs but what is needed are architectural views from large scale infrastructure components down to those very detailed independent parts and pieces.
That documentation must also be kept up to date. Organizations with small mainframe footprints to very large footprints typically have the mainframe and mid-range documentation separated entirely. You might have some level of mainframe topology and some level of mid-range topology but documentation of the connections between the two are often hard to find if they exist at all. Today’s applications have many diverse layers so having this big picture view is critical. This is especially true when you consider that a smart phone application could easily cross multiple platforms, have many layers and encompass dozens of disciplines.
Complex systems can have an internet layer, load balancers, security, web servers, internal firewalls, app servers, web services, back-end systems comprised of multiple sysplex connected mainframes and perhaps dozens of individual mainframe address spaces. Parts of mobile phone applications could even be writing data to a VTS at some point. Architecture documentation must be the place where we see alignment of mainframe and midrange.

Documentation Helps Prepare for Challenges

Solving an outage is a great reason to have up to date architecture documentation but solid architecture documentation or topology is also needed so that CIOs and mainframe leadership are prepared for other challenges, including:
  • Developing short- and long-term strategy
  • Moving data centers
  • Upgrading disaster recovery (DR) methodology
  • Designing hybrid cloud strategy
  • Making costly hardware and software decisions
  • Identifying resiliency and availability gaps
  • Determining if new business objectives can be met
  • Identifying opportunities to improve license agreements
  • Application improvements
  • Responding to complex application changes
  • Shifting workloads to IBM Z
  • Increasing capacity
  • Getting new employees up to speed quickly
IT support staff must have up-to-date information at the ready so that they can support their decision makers appropriately and so their organization can react quickly to new business requirements, be able to support new initiatives, and solve problems. Mainframe staff must have views that show the big pieces in their purview down to the detail. Enterprise architecture has become so vast and complex that it is an unacceptable risk and a large cost driver to keep critical information in the heads of your subject matter experts.
Architecture needs to be drafted and kept up to date. The question that needs to be asked is, what can you do today, right now, to make sure you have solid mainframe architecture topology and are ready for an outage, new business development, hardware purchases or a new DR strategy? What is the minimum you need to begin having solid architecture topology and be ready for anything?

Where to Start? 

Begin with the data centers then drill into the various components, working your way toward critical applications. If you have none of this, keep thinking big picture and do not get mired in detail yet. That will come as you develop your architecture topology collection.
Remember, the greater the detail the smaller the audience. So, detail is generally for specific teams not the wider audience. Get something put to paper that is useable quickly. That will not be the detail. You also must remember that good architecture drawings must be consumable by a variety of users and not require a college level course to understand. A good application component model should be easily understood by a Java developer, a mainframe configuration expert or a CEO.
For example, let’s say you have an outage and you are at the point where executives are called, non-technical people are notified, people are upset and money and business reputation are at stake. Leadership will want to know and understand the issue rapidly. Do you want to be able to explain it with one consumable drawing you already have and a short discussion, or do you want to stand at a white board and then be asked “Why you don’t have this information already?”

Mainframe: the Big Picture 

The following components should be properly documented for mainframes:
  1. Data centers. This one is simple but important since it lays the groundwork for understanding the infrastructure. Think of the 100 employees who just came on board and have no clue where the cafeteria is, let alone the data centers. This is one page. It shows locations, names, addresses, contacts, and connections to and from. Simple but valuable.
  2. Hardware. Divide this into mainframes, storage devices, routers and switches. Nothing elaborate here: make, model, serial, type of replication in use and connection lines. Important mainframe information to catalog is the vital product data (VPD). This can be retrieved via the hardware management console (HMC). 
  3. Network. Start at your mainframes and map out what they connect to and stop. You will have connections such as corporate network, storage, routers, support elements (SEs), HMCs and inter-mainframe connections. In addition to mainframe connections, locate all of you virtual IP addresses or VIPAs, DNS names, and VTAM nodes. You want to end up with a list of every IP that is associated with your mainframe, LPARs and started tasks. 
  4. Data. Remember you already have make, model, and number of devices and connections. The information you need for mainframe data is the big picture view of what is inside those devices. Those devices are the direct access storage devices (DASDs) and VTS devices. DASD needs to be shown by logical control unit (LCU) and the LPARs that those LCUs connect to. Additionally, the storage pools associated with the LCUs that access them are also very helpful. VTS data should be documented by the defined drives and the LPARs that access those drives. 
  5. LPARs. Map all LPARs by the mainframe where they reside along with the associated sysplex if applicable. Make sure you have LPAR weights and memory allocation, too. Simply adding an excel printout of each LPAR Definition File (LPDEF) is the easiest way to do this. Add a list of all coupling facility (CF) structures and file system information for zOS and Unix System Services (USS). 
  6. Software. You must know what products you have running on your mainframes, the value they provide, what they are costing you and the impact to them when your environment changes. Build a spreadsheet organized by mainframe, LPAR, vendor and product. If you have Tivoli Asset Discovery for z/OS (TADz) this will be easy. TADz has a plethora of reports you can create and data you can download in several formats to organize this information. At this point you have the basic mainframe information necessary to be useful. You have clarity on all the mainframe hardware in your data center(s) and solid information on how that hardware is used. You will have improved your mainframe tactical and strategic planning position greatly at this point. However, the last entry level diagrams are not specifically mainframe.
  7. Applications. The most useful diagrams to get your organization on the path to solid architecture topology are component models of your critical applications. Component models are exactly what the name implies. They show clearly all the major parts and pieces of an application; the components. Start with Tier 1 or critical applications. You can get into every detail at some point but for now you want something usable quickly. Collecting the information for the model will be the most difficult part. You may learn no single person on the application team has the entire view that you need for a component model. Each team member will know his or her portion very well but perhaps not a lot beyond. Similarly, infrastructure teams may not have much insight into what interfaces with the many started tasks they keep running. It is up to an architect to bring these pieces together and construct the component models. The easiest way to do this is to gather everyone who you think has a part of an application, put them in a room (physical or virtual) and get to that white board and start mapping out the connections, data, and endpoints.
    A web application could be interfacing with many platforms only one of which is mainframe. That mainframe portion could be using sysplex-enabled middleware with data sharing databases across multiple machines or a single database on one LPAR, VSAM files and triggering batch jobs.
    The point is, you need to know. You want to document components, not detail. Knowing CICS is used in LPAR “X” is enough. At this level you don’t need the detailed CICSplex information. That can come later. I would restrict this to components that help you identify the support teams that you will need in a crisis and that show you where processes are running. The component model should be consumable by your technical teams and as well as executives.

Now you have the table stakes for useful, easy-to-maintain mainframe architecture diagrams. There are many tools and methods that can be used to create good architecture documentation, but to get this started in your organization, use what you have available today. The selection of a tool or method or even the creation of standards to impose to utilize them can sometimes take longer than the project they are being slotted for.

The VTS problem I mentioned at the beginning of this article was due to a duplicate IP address being assigned to one of the VTS ports. Solving it was done by simply tracing the physical paths, confirming IPs, documenting those paths and then cross-checking that information against other IPs on the same switch. Perhaps if someone had produced architecture diagrams for this hardware, the problem would have been resolved sooner or even completely avoided.

IBM Systems Webinar Icon

View upcoming and on-demand (IBM Z, IBM i, AIX, Power Systems) webinars.
Register now →