Re: Poorly documented APIs

[Rajeev_Asthana@xxxxxxxxxxxxxxx]

Exaclly! What I really wanted what was this. They should provide a "OS/400
Programmers Guide to Using APIs" sort of manual which should explain various
kinds of procdeures to use APIs. And include more examples. One manual "System
API Programming" is a bit of help, but something more is required in very clear
terms.








Scott Klement <klemscot@klements.com> on 08/14/2000 05:29:01 AM

Please respond to RPG400-L@midrange.com
                                                                                
                                                                                
                                                                                


                                                              
                                                              
                                                              
 To:      RPG400-L@midrange.com                               
                                                              
 cc:      (bcc: Rajeev Asthana/TCSNOIDA/TCS)                  
                                                              
                                                              
                                                              
 Subject: Re: Poorly documented APIs                          
                                                              









I actually like the way that (most of) the APIs are documented in the
manuals.   Its a bit difficult to get started at first, but after you've
done a few, they make great reference material.  IMHO, when you're already
familiar with API programming, the current manuals are "Just what the
doctor ordered".

They should keep the documentation that they have, and perhaps release
more example programs (and better written ones!!), and a better "getting
started" guide.


On Sat, 12 Aug 2000 Rajeev_Asthana@noida.tcs.co.in wrote:

> Hi All,
>
> Recently, I tried to design a job monitoring utiltiy using various
> APIs which included Job APIs and Message APIs. Till now, I haven't
> acheived the full requirement. The main reason behind this is because
> of very poor documentation of APIs. For example, consider List Job Log
> Message (QMHLJOBL) API. This API has an input parameter as structure
> which contains over 20 fields. In the documetation, it's not very much
> clear what values to use. I tried for 2 days and nothing came
> fruitful. Take for example, the field 'Offset to identifiers of fields
> to return'. How can I know this value in advance in input parameter?
> The way to get this info is no where mentioned. There are several
> examples of this kind.

Why would you need to know the offset to the next field identifier in
advance?  It seems to me that you want to read the offset value so you
know how to jump to the next entry.   If you knew the offset in advance,
it'd completely defeat the purpose of using an offset, wouldn't it?  I
mean, the whole idea is that the position varies, isn't it?

Or isnt that what you're saying?


>
> Then there is this key values that are used in many APIs. The processing of
key
> values are so confusing too. For example, consider List Job (QUSLJOB)  API.
> I'm not still sure how to use keys in this API.
>

This is almost the exact same thing as the "offset to next field"
described above, except that instead of an offset, they give you the
length of the entry.  The offset is simply start position plus length :)
Just like in the other example, the length of each entry varies, you must
use the offset to get to the next entry.

In either case, the method that I'd use is to base a structure for the
data you want on a pointer.   Then offset the pointer to the offset that
you can calculate from the data in the structure.


> Can someone from API team in IBM take some initiative to document
> these properly and provide some examples for each APIs?
>
> Thanks,
> Rajeev.
>

If you have a specific question, or need a specific example, just ask...
someone on the list will have a solution. :)


+---
| 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
+---



+---
| 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
+---