On 17/06/2009, at 2:44 AM, sjl wrote:
I just wish
someone would translate IBM's API documentation into something that is
easier to use for RPG programmers. It was written for 'C'
programmers.
Although the C run-time APIs and the Unix Type APIs (often
euphemistically termed industry-standard APIs) are written for C
programmers the others are not. It gets a little confused with
statically bound procedure APIs but certainly the documentation for
dynamically bound APIs such as QUSRJOBI is written in a language-
neutral form. The documentation lists the interface, then describes
each parameter, and all possible values, then describes the return
formats and the structure of same with a description of all possible
values. There is no C-specific stuff. Language-specific information is
provided in the API Concepts section of the Information Centre. See:
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/apiref/apiconcept.htm
Specific attention should be paid to the Data types and APIs topic:
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/apiref/data.htm
I note that the authors have taken pity on poor dumb RPG programmers
by providing RPG-specific information. Users of other languages must
fend for themselves (although I'm sure previous documentation had a
nice table mapping API data types to specific language data types but
I can't find it any longer--it was useful so it probably got removed).
What is it that you find so difficult to understand? Serious question.
I find the API documentation to be clear and concise. What is often
missing is the relationship between related functions e.g., why
iconv() will convert between two CCSIDs in different encoding schemes
but the Get Default Related CCSID does not have a valid default for
some conversions, or exactly what is the relationship between option,
load, and feature in Product Packaging APIs and how that relates to
multiple libraries, and how multiple libraries relate to language
library, etc. Or how one return value can affect another.
It would also help if they provided working examples in the
documentation,
but I can't read Hindi, so that would probably be out of the
question...
You just have to look. Try:
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/apiref/apiexmp.htm
for some examples. IBM do not provide examples for ALL the APIs. There
are sufficient examples for you to extrapolate from one to your
specific requirements. I never understood the constant cry for an
example of such-and-such API to do xyz when the documentation itself
is sufficient or similar examples can be found by searching.
Regards,
Simon Coulter.
--------------------------------------------------------------------
FlyByNight Software OS/400, i5/OS Technical Specialists
http://www.flybynight.com.au/
Phone: +61 2 6657 8251 Mobile: +61 0411 091 400 /"\
Fax: +61 2 6657 8251 \ /
X
ASCII Ribbon campaign against HTML E-Mail / \
--------------------------------------------------------------------
midrange.com
