Re: Renaming copy member data structure fields

[Scott Klement <rpg400-l@xxxxxxxxxxxxxxxx>]

> Now, on to my problem.  I don't like the names used in the qsysinc copy
> members that define data structures for use with system APIs.  When using
> these copy members in the past, I have either decided to live with the
> arcane names or I have created my own data structures with readable names.
Yep, that's the situation we all face.  It's not just the names, though. 
They don't give you protototypes.  They don't use the integer data type. 
They don't use pointers where needed.  The QSYSINC definitions are really 
just RPG III code converted to RPG IV.  They're *REALLY* bad.  The 
definitions for C programmers are great, and RPG has the same capabilties, 
but IBM for some reason won't code the RPG definitions the same way.  I 
think it's probably because they hate me.

> Neither of these solutions is really to my liking, as the first makes
> code difficult to figure out later on while the second can be very work
> intensive for large data structures.
Yes and no.  Do you really need to use all of the fields in the large data 
structures?  There really isn't any point in defining the fields that 
you're not going to use.  Unless, of course, you're creating a /copy 
member to be used by lots of programs, in which case it's worth taking the 
time to do it right.  Do it once and you're done.
Only for the absolutely unbelievably complex APIs would I stoop so low as 
to use the QSYSINC definitions.  APIs like QDBRTVDB, for example.

> The second method also makes it more of a challenge to adapt to API 
> format changes - perhaps this doesn't really happen very often but I've 
> already been burned by it once.
Really?  APIs are almost always backward-compatible. With more than 2500 
APIs on the system, there have only been one or two exceptions over the 
past decade or so.
Most API changes involve adding additional information to the formats. 
Granted, when the time comes that you need the new information, you have 
to change your DS, but until then your existing programs will continue to 
work.  So there's little or no effort involved in keeping your programs 
working.
I'm curious... how were you burned by an API change?  I use APIs in 
virtually every project I work on, and have done so for 10 years now, and 
have never been burned in a way that'd could've been fixed by using 
QSYSINC.

> Searching the archives I found this suggestion from Rob Berendt (sorry if
> spacing is off):
>
>     D FLWORKREC       DS                  likerec(flworkr)
>     D pDuh            s               *   inz(%addr(flworkrec))
>     D duh             ds                  based(pDuh)
>     D  col                          15p 4 overlay(duh:39) dim(389)
Okay.  This looks like a way of coding an array over a LIKEREC record 
format.  I have no clue what it has to do with APIs.
> This is similar to something I had done when talking this problem earlier
> today:
>
>      // IBM copy member for API error data structures
>      *+  PLEASE keep the next two lines TOGETHER!!!           -
>     D/Copy qsysinc/qrpglesrc,qusec
>     D QUSED01                     1024
>      *+  PLEASE keep the previous two lines TOGETHER!!!           -
> ...
>      // rename QUSEC to make things easier to read
>     D pAPIErrorDS...
>     D                 S               *   inz(%addr(QUSEC))
>     D APIErrorDS...
>     D                 DS                  based(pAPIErrorDS)
>     D                                     qualified
>     D bytesProvided...
>     D                                     like(QUSBPRV)
>     D bytesAvailable...
>     D                                     like(QUSBAVL)
>     D errorID...
>     D                                     like(QUSEI)
>     D errorData...
>     D                                     like(QUSED01)
What advantage would that give you over writing your own DS?  All this 
does is introduce complexity and add errors (indeed, your definition is 
wrong, you missed the 1A reserved field, so this definition won't work 
properly.)
You also can't overlay QUSED01, since it's commented-out in IBM's 
definition.  The only way to even get that field in your RPG program is to 
make your own copy of the DS, or to make your own qualified DS where QUSEC 
is brought in as a sub-DS and you add your own fields after it.  (And if 
you use this second approach, you'd have to use free-format for all 
references to the QUSEC part of the DS, it wouldn't work with fixed 
format.)
> I'm not really happy with either of these solutions because both make
> assumptions about the order of the fields in the copied data structure.
>
> What I'd really like to be able to do is this:
>
>     D APIErrorDS...
>     D                 DS                  likeDS(QUSEC)
>     D bytesAvailable...
>     D                                     like(QUSBAVL)
>             D                                       overlay(QUSBAVL)
You could do SOMETHING like that, by coding the following:

      /copy QSYSINC/QRPGLESRC,QUSEC

     D APIErrorDS      ds                  qualified
     D   QUSEC                             likeds(QUSEC)
     D   errorData                 1000A

     D bytesProvided   s                   like(QUSBPRV)
     D                                     based(p_bytesProvided)
     D bytesAvailable  s                   like(QUSBAVL)
     D                                     based(p_bytesAvailable)
     D errorId         s                   like(QUSEI)
     D                                     based(p_errorId)

      /free
         p_bytesProvided  = %addr(APIErrorDS.QUSEC.QUSBPRV);
         p_bytesAvailable = %addr(APIErrorDS.QUSEC.QUSBAVL);
         p_errorId        = %addr(APIErrorDS.QUSEC.QUSEI);

However, I think this probably makes your code harder to follow than the 
bad names from IBM's DS does.  It's much better to code your own DS.
> This way, if I only want to use the bytesAvailable variable in my program
> I don't have to worry about any of the others.  I can also use APIErrorDS
> wherever I would use QUSEC.  The best part is that if the layout of the
> QUSEC data structure were to change between releases, all I have to do is
> recompile the program.
IBM won't change the layout of QUSEC -- they really can't, if they did, 
every program that uses it would (at a minimum) have to be re-compiled. 
And software companies that write code to run on more than one version of 
i5/OS would have to maintain separate packages for each level of the 
operating system.  They'd have open rebellion on their hands. It's not 
gonna happen.

> My preferred method doesn't work because using likeDS precludes defining
> extra fields on the DS.  Does anyone have any suggestions of another way
> to do this?
My suggestion is to code your own DS.  You're making a mountain out of a 
molehill.  You're going to create hours or even weeks of extra effort for 
the people who have to maintain your programs, and why?  To spare yourself 
a few minutes work that you MIGHT (but it's unlikely) have to do for a 
release upgrade?