RE: MI/C builtins/APIs documentation -- MIDRANGE-L

Jon:

Unfortunately, no, V5R2 doesn't help since I must compile for older releases. 
Even if that weren't so, it wouldn't help because those weren't really the 
problem; they were simply the builtins/functions I was looking at at the time 
and they got me seriously thinking about the whole problem of using such 
functions in the first place.

There are _LOTS_ of builtins/functions that are not in any "official" IBM 
documentation. As mentioned in another post, one introduction to them is 
available through a Gene Gaunt REXX procedure (which is how I learned about the 
'_OPNTH1' that I referenced in the initial post.)

Scott Klement gave an excellent discussion of '__errno' that is very 
appropriate to C, but I'm not _fully_ convinced it applies to RPG. It's 
possible, however remotely, that IBM could change the macro in V5R3 so that 
'ERR_NO' would be the "new, improved API" while '__errno' continued to work 
until dropped with little fanfare in VxRy. In some ways, that's why macros are 
used, to enable such changes as well as to enable portability and environment 
customization. Attrition would handle some existing C programs; new ones 
wouldn't ever see an issue; and eventually IBM _could_ say "Recompile whatever 
C programs haven't been compiled since V5R2." With the macro, the change would 
be otherwise transparent -- for C. C programs that did not reference the macro 
would be in the same trouble RPG or COBOL would be in. (I last used '__errno' 
in COBOL.)

The whole of what I was wondering was the issue of documentation. Some things 
are undocumented but we use them. '__errno' is in itself "undocumented". 
Perhaps I'm just overly sensitive about it because I had a couple PMRs open a 
while back for weeks on V5R1 about it in ILE RPG when open() would return FD=-1 
and '__errno' only returned '0000' which means "There was no error." A PTF 
eventually cleared that up but it's made me think about it in the larger 
picture.

Ideally, I'd simply like to know if official documentation really exists. For 
items such as '_XORSTR', I can accept the principle that the MI Functions 
Reference is official if there's a match with an MI statement. I'm actually 
comfortable with '__errno' for essentially the reasoning Scott gave. But does 
anybody know how far that reasoning extends? Which builtins/functions are 
acceptable? Which should be avoided? And which are in the gray in-between? So 
far, Scott seems to have given the best available guidelines.

Any other views?

Tom Liotta




midrange-l-request@midrange.com wrote:

>  12. MI/C builtins/APIs documentation (Jon Paris)
>
> >> I'm looking at some code built around '_XORSTR', '_ORSTR' and '_ANDSTR'
>to do bitwise manipulation in ILE RPG.
>
>Is waiting for V5R2 an option?  If it is you can use the new RPG bitwise
>BIFs and avoid all of this.

--
Tom Liotta
The PowerTech Group, Inc.
19426 68th Avenue South
Kent, WA 98032
Phone  253-872-7788 x313
Fax    253-872-7904
http://www.powertechgroup.com


__________________________________________________________________
The NEW Netscape 7.0 browser is now available. Upgrade now! 
http://channels.netscape.com/ns/browsers/download.jsp

Get your own FREE, personal Netscape Mail account today at 
http://webmail.netscape.com/