On 12/9/2010 9:00 AM, Walt Farrell wrote:
While I'll agree they prologs are interesting to look at, I'm not sure we view them as official documentation, and they certainly describe many things that are not officially programming interfaces, with all that implies for you (and potentially your program or system) if you try to use them.
Too often the books are incomplete or just plain wrong. Having time to file an RCF to get them fixed is a luxury. Sometimes I have time; sometimes I don't. In my experience, the macro prologues are the best place to find the accurate and most up-to-date interface and usage details. Even the return/reason codes are enumerated there and contain the latest information. The doc is often woefully out of date. Here's a recent true story: For a programming task started last month involving Health Checker, the book was so inadequate that the programmer couldn't figure out how to use the HZSQUERY interface to do what he knew should be possible. I spent a good deal of time looking at it myself and finally asked, "Did you look at the macro prolog?" Of course, what was needed was fully described there and the programming task proceeded to the next phase. The new functionality is now tested and working fine awaiting delivery to customers in the next release.
So anyone using the prologs -should- (in my opinion) be making sure that what they're using is also described in the books or they're taking some risks.
If we weren't supposed to read the macro prologues, the z/OS programmers would not create them in the first place or maintain them so painstakingly with each change.
Though in this case I see that the prolog does indicate that USE2GTO32G is not a programming interface, so one could get that info from a careful prolog reading, too, as long as one read -all- of the prolog and not just the keyword descriptions.
Exactly! IARV64 provides an on-point example of how the documentation in a modern macro prolog is often _far_ more complete than the books. The macros are carefully maintained by the highly-qualified z/OS programmers writing the code in the U.S. or Europe or wherever they may be located whereas the books are maintained by some non-programmer "ID" folks in a far-away land called China. The documentation the z/OS programmers provide is obviously intended to, and absolutely succeeds in, helping us (the exploiters) be more self-sufficient. I'd much rather read that information than waste everyone's time with days of experimentation or a call/email to my friends in POK asking how an interface actually works. What would make us even more self-sufficient would be access to the source code or compiler listing of the code behind the interface as is done in Linux--the most popular emerging operating system in the world. Where listings still exist for non-OCO z/OS modules, there are rarely any questions. In fact, experienced programmers can often fully diagnose abends in IBM code as I did recently for still-open PMR 06143,227,000 which resulted in still-open APAR OA34895. But, I digress...// -- Edward E Jaffe Phoenix Software International, Inc 831 Parkview Drive North El Segundo, CA 90245 310-338-0400 x318 [email protected] http://www.phoenixsoftware.com/
