longpelaexpertise.com.au/ezine/UnderstandAPARs.php?ezinemode=printfriend

LongEx Mainframe Quarterly - November 2024

The IBM support pages provide, amongst a whole bunch of other things, APAR documentation. This is information from IBM support teams about errors, fixes and other issues relating to IBM products. There's a lot of information in this APAR documentation, but they can be a bit confusing. So, in this article we'll show how to read these APARs.

The Basics

Let's take an example: APAR OA61767:

If you're new to IBM support, an Authorized Program Analysis Report (APAR) is a report opened by IBM support. This may be because a client has opened a Problem Management Record (PMR), and IBM support suspects that there is an error with a product or wants to publish information on what to do with it. It may be a new feature added to existing software, or some information offered by IBM support.

Ever APAR has an ID: OA61767 in this case. Even this ID can tell you something. APARs beginning with the letters 'II' aren't problems, they're 'information' or 'informational' APARs. Or in other words, IBM has decided to provide some extra information for you.

The title seems straightforward, summarising what's happening. Just below the title, it states that a fix is available: IBM has released a fix for this APAR. We'll get to that shortly. There's an APAR status (more on that later as well), and a description of the error.

To the right, we find that this APAR is for the Omegamon for CICS product, version 530. This doesn't mean that the APAR is only relevant to version 530, as we'll see soon.

More Information

More information follows about the APAR:

The problem summary is the interesting part. It summarises the problem, who is affected, and what IBMs recommendation is (in this case, to apply the PTF). Sometimes, IBM will come up with a way to avoid the problem while you wait for the fix: a "local fix:" none for this APAR. IBM may also provide a temporary fix, and other relevant comments.

APAR Status

APARs are usually open (IBM support is still working on it) or closed (nothing more for IBM support to do). But there a few possible statuses other than simply 'open' or 'closed. In this example, it is "Closed as program error'. IBM have decided that there is an error with the product. Normally, IBM will have created a Program Temporary Fix (PTF). There is more information about the APAR at the bottom:

This repeats the Status: CLOSED PER: the APAR is closed with a code of 'PER' or program error. There are some other possible close codes, including:

• DOC – documentation error. The APAR will probably include information modifying IBM documentation that IBM support believe is sufficient to resolve the error.
• FIN – problem will be fixed in the next release of the product.
• DUA, DUB, DUU – this APAR is a duplicate of another APAR. The APAR will include details of the other APAR that likely has a resolution.
• CAN – cancelled by the person who opened the APAR.
• PRS – permanent restriction. No further resolution will occur.
• SUG – suggestion for program enhancement.

More Information

This bottom section reproduces some of the information at the top, but with more detail. It again shows the product (Omegamon for CICS) and the reported release (530).

It also provides the component name and ID. A search on the web shows the component of this APAR (5698A5800) is Omegamon for CICS (no surprise). Some products have multiple components, so this information is important. We talk more about components and component IDs in another article.

It also includes the date that the APAR was opened, closed, and last modified. Sometimes IBM will modify an APAR after it is closed. This may be because it is superseded by another APAR, or there was a problem with the PTFs.

PE and HIPER

In this bottom section, it states that PE is noPE, and HIPER is noHIPER. But if we look at APAR PH48266, we'll see that PE is yesPE, and HIPER is yesHIPER:

PE stands for 'PTF in Error.' PH48266 fixes a problem with a previous APAR. The text for PH48266 explains:

So, APAR PH44360 didn't fix the error, or created a new one. If we look at the 'problem' APAR PH44360, we'll see the comments:

HIPER stands for High Impact PERvasive APAR. Or in other words, this is an important APAR you'll want to action as soon as you can.

If you want to search the IBM support site for PE or HIPER APARs, add the string 'yespe' and 'yeshiper' respectively to your search.

Routing and Modules

Looking further down our APAR OA61767, we see:

This shows other APARs or PTFs that are connected or influenced by this APAR. In this case, this APAR has resulted in UJ06144. We'll soon see that this is a PTF.

Take a look at the APAR PH44630 we looked at earlier:

PH44630 is linked to PH47445: they both related to the same issue. APAR PH47445 seems to have created a PTF (UI81473) that fixes the issue.

Our APAR then lists a whole bunch of modules:

This shows modules that are affected by any PTF created for this APAR. These may be new modules, modules that are removed, or modules that are changed. They could be load modules, sample members, REXX and CLISTs, or any other resources used by the product.

PTFs

Finally, the APAR provides some information about the fix for the APAR:

In this case, there are two PTFs. You'll remember at the beginning of this article that our APAR was opened for version 530. However, IBM have not only provided a PTF for version 530 (UJ06144), but also a PTF for the later version (550).

The Best Problem Information

IBM APARs have been following this basic documentation format for ages, and it's brilliant. It clearly gives you everything you need to understand the problem, figure out if it applies to you, and follow IBMs recommendations if needed.

David Stephens