Re: MI/C builtins/APIs documentation

Tom,

The short answer is to use the documentation for the function name minus any
"_".

Not sure if you have the C compiler, but if you looked at the errno.h
include in QCLE, you'd see that errno is a macro for __errno.  It's just a
layer of indirection.  The C programmer, would code errno not __errno.
That's why errno and not __errno is documented.    Since you're writting an
equivalent RPG prototype, you just need to know what's happening in C.   The
same goes for using the MI builtins.

You have a good point about the documentation.   It's there for the C
programmer, but the RPG programmer has to figure it out on his/her own.
Lacking the C prototypes, you could look at QC2xx service program exports
and deduce the function names.  For MI, there's Gene's REXX procedure that
will list the actual builtin names. Again, a little deduction is required.


Keith



----- Original Message -----
From: "Tom Liotta" <qsrvbas@netscape.net>
To: <midrange-l@midrange.com>
Sent: Tuesday, October 29, 2002 8:45 PM
Subject: MI/C builtins/APIs documentation


To all:

A C API that is often used is '__errno'. This API essentially returns the
errno that results from an error encountered while calling other C APIs such
as open() and write(). Look at the ILE RPG Sorceror's Guide Redbook and
you'll see '__errno' referenced many times.

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.

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.

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?

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?

Tom Liotta

--
--
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/
_______________________________________________
This is the Midrange Systems Technical Discussion (MIDRANGE-L) mailing list
To post a message email: MIDRANGE-L@midrange.com
To subscribe, unsubscribe, or change list options,
visit: http://lists.midrange.com/cgi-bin/listinfo/midrange-l
or email: MIDRANGE-L-request@midrange.com
Before posting, please take a moment to review the archives
at http://archive.midrange.com/midrange-l.