Re: Prototypes for System APIs

Hi Jon,

Not to say it's right or wrong, but over time there have been many RPG IV
enhancements that have not made it into QSYSINC.

QSYSINC was first provided back in V2R3 and, if I remember correctly,
prototyping wasn't supported until V3R2/V3R6. To introduce prototypes at
that later point might have caused problems as some RPG developers may have
already coded their own prototypes (a topic I seem to recall that was
covered in a rather well received red book way back when) within their
source.

Along the same lines names greater than 10 characters in length came around
V3R7 but QSYSINC continued to use the previous 10 character limit. Longer
names, such as used in the COBOL and C QSYSINC includes, could have been
introduced but would probably have meant a new source file or conditional
compilation directives (and complexity). I know way back when just the
simple introduction of I and U datatypes for new fields caused complaints
from some.

As for finding the word "prototype" in QRPGLESRC members, that is due to
using the C include source to generate the corresponding RPG III, RPG IV,
and COBOL source includes. It was felt that trying to teach all API
developers how to code/provide RPG (in different flavors), COBOL, and C
include files, it might be more consistent/productive to just require C
knowledge. Even with that simplification though you can find wide variance
in C include coding styles if you look... In this case it is the simple
conversion of C comments to RPG/COBOL comments where some of the comments
happened to have the word "prototype" in them. Perhaps a smarter conversion
tool could have been used to avoid this, but it wasn't.

I do vaguely recall that a few RPG prototypes were actually provided in
conjunction with some APIs developed in Toronto, but I haven't had access
to an i in months so I can't confirm that. Anyone happen to have an i I
could jump onto every once in a while?

On Sat, Dec 1, 2018 at 2:31 AM Frank Kolmann <frank.kolmann@xxxxxxxxx>
wrote:

Hi Jon

You probably know this already, apologies in advance.
Perhaps the reason why the prototypes are not set up is because many
APIs use pointer variables.
For a C programmer the API documentation in the manuals probably is
completely obvious.
For an RPG programmer translating the C-like documentation into an RPG
prototype is not so obvious.
The pointer variables such as 1 Receiver variable Output Char(*) below
for QDFRTVFD can be a mystery.
I think someone perhaps Scott Klement once documented how to translate
the API documentation into RPG code.
Perhaps these days RPG coders are completely conversant with pointers
and understand that pointers effectively become variable length data
elements not to be confused with varying length character fields.
I was not until I learnt C that I began to understand the power of
pointers.

The below is an example of a prototype I got from Scott , I believe,
and although the API doc mentions Char(*) for the return variable, I
have coded an 8 byte value.
However by using pointer variables and %alloc the API recognises the
space for the returned data is no longer 8 bytes.

Frank Kolmann

From the API manual.
'-- start --'
Retrieve Display File Description (QDFRTVFD) API
Required Parameter Group:
1 Receiver variable Output Char(*)
2 Length of receiver variable Input Binary(4)
3 Format name Input Char(8)
4 Qualified file name Input Char(20)
5 Error code Output Char(*)

Default Public Authority: *USE
Threadsafe: No

Receiver variable OUTPUT; CHAR(*) The receiver variable that receives
the information requested.
You can specify the size of the area smaller than the format requested
as long as you specify the length of receiver variable parameter correctly.
As a result, the API returns only the data the area can hold.
-- end --'


This is from some code I did for the Retrieve File Description API,
again I borrowed from Scotts work.
There are 2 calls to the API, first to get the space needed for the
return data, then the real call to get the data.

D RtvDspFDesc PR ExtPgm( 'QDFRTVFD' )
D 8
D 10I 0 Const
D 8 Const
D 20 Const
D 272


C CallP RtvDspFDesc(
C RtvSizeInfo :
C 8 :
C 'DSPF0100' :
C QDspFil :
C APIErrDS
C )
C If BytesAvail > 0
C Return *Off
C EndIf

C eval p_QDFFBASE = %alloc(RtvSize)

*-------------------------------------------------------------------
C Reset APIErrDS
* Retrieve display file description ( QDFRTVFD ) API
C CallP RtvDspFDesc(
C QDFFBASE :
C RtvSize :
C 'DSPF0100' :
C QDspFil :
C APIErrDS
C )
C If BytesAvail > 0
C Return *Off
C EndIf



On 1/12/2018 9:16 AM, Jon Paris wrote:

Anyone know what the IBM rules are for when a proto is supplied in

QSYSINC ?

Going through them a lot are supplied (such as QUSLRCD for example) but

others such as QUSPTRUS are not there.

I'm trying to come up with a way for clients to determine which ones

they have and which they need to potentially create.

Jon Paris

www.partner400.com
www.SystemiDeveloper.com

--
This is the RPG programming on the IBM i (AS/400 and iSeries) (RPG400-L)
mailing list
To post a message email: RPG400-L@xxxxxxxxxxxx
To subscribe, unsubscribe, or change list options,
visit: https://lists.midrange.com/mailman/listinfo/rpg400-l
or email: RPG400-L-request@xxxxxxxxxxxx
Before posting, please take a moment to review the archives
at https://archive.midrange.com/rpg400-l.

Please contact support@xxxxxxxxxxxx for any subscription related
questions.

Help support midrange.com by shopping at amazon.com with our affiliate
link: https://amazon.midrange.com