Re: API data type prototyping

Pete,

As an addendum to what Rob said, a common format for many IBM APIs' is
to have a pair of parameters - a 'receiver' field and a 'length of
receiver' field. In these cases, you need to let the API know how much
data your program can accept into the receiver variable. The easiest way
of doing this is as follows:

...
D RcvVar               65535A   Options(*Varsize)
D RcvVarLen               10I 0 Const
...

...
C                   Callp(e) API( RcvVar :
C                                 %len( RcvVar) :
C             more parameters here   
...

i.e. define the receiver variable as a large arbitrary length and
specify that length as the second parameter. Also, in some cases, IBM
API's can return different types of information - you can often tell
these API's because one of the parameters will be called (as in your
example) 'Format name'. In these cases, you could actually pass a
structure name (of a data-structure you've already defined) and the
length of that structure, e.g.

...
D MyStruct     DS
D Field1                  10A
D Field2                  10I 0
D Field3                 128A
...

...
C                   Callp(e) API( MyStruct :
C                                 %len( MyStruct ) :
C             more parameters here   
...

The actual details of the possible structures (typically one per named
format parameter) are in the documentation. For instance,
http://publib.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/qb3amq02/5.12 shows
that the QUSROBJD API allows you to pass one of four different values
for the format parameter - 'OBJD0100', 'OBJD0200' etc., depending on
whow much information you need. Whichever value you pass in the format
parameter, you must pass the matching structure (and length of that
structure) in the first 2 parameters.

For other parameters marked as Char(*) (such as the 'Product
information' parameter in your example), the documentation will show the
size/length of that parameter to pass. If in doubt, define a Char(*) in
the D-specs as:

D RcvVar               65535A   Options(*Varsize)

which will allow you to pass any meaningful value to the API (according
to the documentation). IBM does this because it's easier to document a
parameter as 

4     Product information     Input     Char(*)

than as 

4     Product information     Input     Char(276)

and also, if the API ever changes, they don't need to change the entire
documentation.

Clear as mud?

Rory