Peter - Thank you.
We have disagreed on this point before but let me say again that if a customer of mine posted here that my product's documentation was lacking in some particular area I would thank them, not tell them that they had told me in the wrong way. Yes, I quoted only a portion of the documentation. What could go in the Services Guide? Well, to begin with and as you note, the information that Dave was kind enough to post: that IARCP64 allocates a "PCELLCT" of (1MB-overhead)/(cell_size+overhead). (Frankly, above the bar or not, doesn't IARCP64 need a PCELLCT parameter? What if I know or fear that I am going to need more than 1MB worth of cells, but can't use EXPAND=YES because of lock considerations in my GET situation? Do I have to write a little initialization loop to drive the cell count up to > 1MB worth just so I will have them later? Or am I missing something?) I have never before seen a macro where the authorized and unauthorized descriptions were essentially identical. Nobody asked me, and it's really a new thread, but frankly I find the whole authorized/unauthorized documentation split to be needlessly burdensome and confusing. One always has to look in both places: macro X might be all authorized, and so only in authorized (TESTAUTH), or only in unauthorized, or in both places because some parameters were privileged (ATTACH) or in both places even when one might not expect it to be so (TCBTOKEN). One often has to read the entire Unauthorized doc, and then go read check the Authorized doc to make sure that there is not some useful bit that one has missed. And that's not even mentioning DYNALLOC which inexplicably is "reference" documented in the Authorized *Guide*, even though 90% of its functions are unauthorized. Nor to mention things like OPEN and READ which for all or most other operating systems are documented with other OS functions, not as some semi-add-on product. Further, the distinctions are arbitrary: TESTAUTH (except for BRANCH=YES) is completely available to and works perfectly for unauthorized callers: it correctly and quite usefully tells them that they are not authorized. Or to mention Callable Services. Or LE Callable Services. You want to increase the adoption of this platform? Publish a single manual that is an overall index to available z/OS program services and is arranged by general function in human terms and that points the reader to the proper manual. Thank you again. I do appreciate the mainframe and z/OS and what it has been to my career, and what you have done for IBM and z/OS. Charles -----Original Message----- From: IBM Mainframe Discussion List [mailto:[email protected]] On Behalf Of Peter Relson Sent: Tuesday, September 16, 2014 5:22 AM To: [email protected] Subject: Dumb IARCP64 question >Thanks for doing IBM's documentation for them. <g> I'm sure we all thank the posters for the clarifications and suggestions, but better would be for this information to be sent in by you as a suggestion. It is rarely helpful just to say that a section is bad (or to complain only in this venue), but often it is very helpful to point out just what is bad and/or missing. A question was raised why IARCP64 appears the same in the unauthorized and authorized books: the general intent is that the authorized books contain interfaces available to authorized programs (whether they are also available to unauthorized programs or not). So for a service that has no authorized-only components, it's quite understandable for the two books to be the same. That isn't to say that the books fully accomplish that intent. Regardless, for IARCP64, the "minimum authorization" section does identify the areas that could/should be different (i.e., that require authorization) But the non-authorized book for whatever reason does not omit those things (but certainly could and quite possibly should). >,EXPAND=NO > This parameter does not try expanding. Of course it would have been less misleading if a more complete snippet were shown. While no one could successfully argue that "this parameter does not try expanding" is other than horrible (and EXPAND=YES not surprisingly is similar), I'll bet every reader of this section would have no difficulty in understanding the complete section for EXPAND: ,EXPAND=YES ,EXPAND=NO When REQUEST=GET is specified, a required parameter that indicates whether to attempt expanding the pool if there is no available cell. ,EXPAND=YES This parameter tries expanding. ,EXPAND=NO This parameter does not try expanding. (and, yes, if it had said "This parameter indicates to try expanding" / "This parameter indicates not to expand" it would certainly have been better. Many chapters would have omitted "This parameter" but this chapter appears to like that style, even if not implemented well) >Apparently nada in the Services Guide. No overview. No usage. The >example in the reference is just a rehash of the parameters. What guidance would you want? This is quite a simple service. What would you want it to say that is not appropriate to place directly in the reference? If there is other information missing from the parameter sections then please bring them up. I'm sure we have all been in the position of being too familiar with something to be able to spot some simple errors (especially errors of omission). Description of the extent size is, as has been mentioned, a rather significant omission. ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to [email protected] with the message: INFO IBM-MAIN
