API documentation (was RPG400-L Digest V3 #74)

Jim Langston wrote

>Hmm... So you're saying, Scott, that it's not their job to show us how
>to use these APIs in RPG.  1 page in the beginning of the manual showing
>how to declare each variable in each language would be sufficient.  But
>we don't even have that.

Throughout this thread, the specific APIs we've been talking about have been
rather vague.  The System API Reference Preface
http://publib.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/QB3AMA04/PREFACE.1
specifically says that "This book is intended for experienced application
programmers who are developing system-level and other OS/400 applications.
It provides reference information only; it is neither an introduction to the
OS/400 licensed program nor a guide to writing OS/400 applications."

>So, if it's not the job of the API manual to show us how to use them, what
>is the job of the API manual?  And, yes, I realize I am splitting hairs,
but
>how many RPG programmers haven't used the APIs just because the
documentation
>didn't explain how to use them in *their* language, RPG?

It's job is to be a reference: to look up the details of something I already
know.  Reading a dictionary won't teach me a language and reading a
reference work won't teach me how to use APIs.  I don't really expect a
reference work to be a tutorial.

>I know C, I know binary, I know pointers, but no way could I have told you
>to code their 4B as 10i 0!!!

I've never seen documentation that said 4B.  Here's where the specific API
is important.  The Unix style APIs like read() have documentation like this:

#include <unistd.h>
ssize_t read(int file_descriptor,
  void *buf, size_t nbyte);

There's no 4B here.  

The "native" APIs like Convert Edit Code (QECCVTEC) have documentation like
this:
Required Parameter Group: 
1 | Edit mask | Output | Char(256) 
2 | Edit mask length | Output | Binary(4)
etc.  There's no 4B here, either.  It says Binary(4) - Four bytes of data,
formatted as a binary number.  The line above is has 256 bytes of data,
formatted as character.  The System API Programming book
http://publib.boulder.ibm.com/cgi-bin/bookmgr/DOCNUM/SC41-5800-00/CCONTENTS
has a chapter (chapter 9 in V4R4) devoted to Common API Programming Errors.
The examples there clearly show Binary(4) to B 1 4.   The RPG User's Guide
explains about binary data:
http://publib.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/QBKAQU00/9.1.3.1  

When I first got into APIs I too thought the documentation was horrid.  My
very first attempt (one of the "native" list style APIs in RPG III) threw
all sorts of errors.  Oddly, I never got caught with the "what does
Binary(4) mean" error.  After I did my first "native" one, the documentation
seemed just right.  I had a little more adjustment to make when I did the
Unix APIs, but again, after the first one, the rest are easy.  

A last note: If you don't know how to interpret the documentation, you
should immediately write the documentation people.  Their web address/mail
address is in every manual.  It's their job to get it right.  If the docs
don't work for a lot of people, they will get changed, but only if the
documentation people hear about it!

Buck Calabro
Aptis; Albany, NY
"Nothing is so firmly believed as
 that which we least know" -- Michel Montaigne
Visit the Midrange archives at http://www.midrange.com
+---
| This is the RPG/400 Mailing List!
| To submit a new message, send your mail to RPG400-L@midrange.com.
| To subscribe to this list send email to RPG400-L-SUB@midrange.com.
| To unsubscribe from this list send email to RPG400-L-UNSUB@midrange.com.
| Questions should be directed to the list owner/operator: david@midrange.com
+---