This post is part of a series exploring the unique aspects and capabilities of WebSphere Liberty when running on z/OS.
We'll also explore considerations when moving from WebSphere traditional on z/OS to Liberty on z/OS.
The next post in the series is here.
To start at the beginning, follow this link to the first post.
---------------
This week we’re going to look at three different ways that the Angel could terminate: stop, cancel, and abend. The proper way to shut down an Angel is to stop it. This means using the z/OS console ‘stop’ command directed at the Angel you want to shut down. Because there might be Liberty servers actively using the Angel and it would be rude of it to go away and leave them hanging, the Angel won’t stop if it is supporting any servers.
If that’s the case and you try to stop it, the Angel will tell you it can’t do that (I wanted a message that said, “I’m sorry Dave, I’m afraid I can’t do that” but apparently not all WebSphere z/OS sysprogs are named ‘Dave’). It will also list all the servers it knows about that are using it right now (this is the same as the output of the display-servers command we talked about last time, so you might issue that before a ‘stop’ to find out yourself if it will work or not).
If there are no active servers using the Angel it will quietly go away. The Angel will leave some common/shared storage structures around to be re-used next time it is started, so common-storage-tracking utilities will show this as ‘abandoned’ but it isn’t really as long as you restart this Angel at some point in the future.
That seems easy enough, so why would you ever want to cancel the Angel? Well, I suppose it is theoretically possible some bug could keep it from shutting down cleanly. Perhaps some control structures are corrupted and it thinks there are active Liberty servers using it but there really aren’t. Or some other problem keeps it from ending and you have no choice but to cancel it. You really shouldn’t ever need to do this. If you do, something has already gone very wrong.
What’s going to happen when you cancel it? Well, a cancel causes a non-retryable abend, so the Angel is going to end quite abruptly. In the early days of Liberty, that was all that happened and we just left registered servers hanging. Eventually, maybe hours or days later, those servers might try to use an Angel service and abend and probably come down violently. That seemed messy and unpredictable, so we changed it to forcibly abend any servers using this Angel and the Angel itself dies. It knows who they are, so it will hit them with a non-retryable abend to bring them down.
This is kind of bad if your Liberty servers are running in CICS because you can have more than one Liberty server inside a CICS region and they might not all be using the same Angel. Canceling an Angel used by one of them would bring down the whole CICS region, hard. If this is a concern for you, see Liberty APAR PH48202 and CICS APAR PH51510 where we tried to finesse this situation.
What about an abend of the Angel itself? Well, again, this shouldn’t really happen. The Angel itself doesn’t run any code after initialization unless you throw a Modify or Stop command at it. All the Angel-service code runs in the caller’s address space, not the Angel’s. But still, bad things happen, so it is possible maybe a display command hits a corrupted bit of storage and abends or something. After that it behaves just like when a cancel command hits the Angel and everything comes down violently. You should collect doc and open a support case because this shouldn’t happen.