Re: MI/C builtins/APIs documentation

Hi Tom,

comments in-line.

On Tue, 29 Oct 2002, Tom Liotta wrote:
>
> However, I haven't been able to locate any clear documentation from IBM
> that defines the '__errno' API. For some discussions, it seems that
> '__errno' could be thought of as an "undocumented interface". Of course,
> it's now used so pervasively that IBM would have a difficult time ever
> changing its interface or blocking it nor do I think they'd ever want to
> since it exists on other platforms and possibly is even defined within
> some 'standard' someplace, not to mention the fact that it's too
> valuable to interfere with.

While '__errno' is not directly referenced in the IBM manuals, there is
a lot of references to 'errno' in the ILE C manuals.   The definition of
errno that they use can be found by looking at the "#include <errno.h>"
file, which I view by doing the command:  STRSEU QCLE/H ERRNO

Near the end of this source member, I see the following definition:

#define errno (*__errno())

Which shows me that when an ILE C programmer is referencing the 'errno'
variable, he's actually calling the __errno() procedure, and then
dereferencing the result.  (the * is deref)

Since that #define is a preprocessor macro, changing the way it worked
(without keeping the interface for backwards compatibility) would require
people to recompile (including re-run it through the preprocessor) every
single ILE C program that used errno.   They didn't even require that much
work for a CISC to RISC conversion, I don't think they'll just up and change
that one day! :)

So, although '__errno' is "undocumented", 'errno' is WIDELY documented,
and since one is just a macro converting the source to the other, it's
not going to change.

>
> But still, I can't find documentation. Further, there are numerous other
> builtins/functions that seem undocumented but fully available for use,
> once you know they exist. E.g., I'm looking at some code built around
> '_XORSTR', '_ORSTR' and '_ANDSTR' to do bitwise manipulation in ILE RPG.
> Now, technically, the MI instructions XORSTR, ORSTR and ANDSTR are
> indeed documented; but just because an MI instruction exists does not
> mean a function or builtin exists for it. And apparently, just because a
> builtin/function exists doesn't mean it's documented nor even that an MI
> instruction is available for it.

I haven't yet puzzled this one out, either.  I think that the MI
Functional Reference probably does spell out which MI instructions are
available as builtins, but I haven't done enough research yet to figure
out how to tell.

As for the 'MI functions' (as opposed to the built-ins) they are
documented in the ILE C/C++ MI Library Reference SC09-2418.

>
> Other than a reference in a Redbook or spreading the word through a
> mailing list, how would anybody know that '__errno' is available? What
> about '_XORSTR'? or '_OPNTH1'??? How would anybody know what to do with
> them or even if they should be used?
>

How would you know that errno is available?  You'd see manuals, that
say
     '2.  The UNIX-type APIs and the National Language Data Conversion
      APIs use errno to report error conditions. '
                   -- From the "API Error Reporting" topic in V4R5
                         Information Center

and then you'd do a STRSEU QCLE/H ERRNO  to see how errno is accessed
by ILE C routines, and convert that same code to RPG.   This may seem
cumbersome, but all of the APIs which use it will ALSO require you to
convert C prototypes to RPG, so you should be used it it :)


> The C/C++ Run-Time Library, C Library and MI Library manuals are very
> useful, but they don't mention '__errno'... AFAIK. What guidelines do
> you use to decide whether to use it or not?

That's a tough question to answer.   I guess I weighed the risks and
decided that IBM isn't going to require a recompile of all ILE C software,
so the risks were low, and worth it for me.

If IBM does change the interface, and requires all ILE C programs to be
recompiled, all I'd have to do is change my header member and/or service
program that accesses errno, and simple recompile/bind the appropriate
programs.  Just as every ILE C programmer would have to do...  I can
live with it.

Of course, I'd much prefer that IBM provided the same prototypes for
RPG programmers that they do for C programmers, in a standard library
where we can just /copy them, and go.  :)