Re: Renaming copy member data structure fields -- RPG400-L

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 reallyjust RPG III code converted to RPG IV. They're *REALLY* bad. Thedefinitions 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. Ithink 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 datastructures? There really isn't any point in defining the fields thatyou're not going to use. Unless, of course, you're creating a /copymember to be used by lots of programs, in which case it's worth taking thetime to do it right. Do it once and you're done.

Only for the absolutely unbelievably complex APIs would I stoop so low asto use the QSYSINC definitions. APIs like QDBRTVDB, for example.

The second method also makes it more of a challenge to adapt to APIformat changes - perhaps this doesn't really happen very often but I'vealready been burned by it once.

Really? APIs are almost always backward-compatible. With more than 2500APIs on the system, there have only been one or two exceptions over thepast 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 haveto change your DS, but until then your existing programs will continue towork. So there's little or no effort involved in keeping your programsworking.

I'm curious... how were you burned by an API change? I use APIs invirtually every project I work on, and have done so for 10 years now, andhave never been burned in a way that'd could've been fixed by usingQSYSINC.

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 recordformat. 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 thisdoes is introduce complexity and add errors (indeed, your definition iswrong, you missed the 1A reserved field, so this definition won't workproperly.)

You also can't overlay QUSED01, since it's commented-out in IBM'sdefinition. The only way to even get that field in your RPG program is tomake your own copy of the DS, or to make your own qualified DS where QUSECis brought in as a sub-DS and you add your own fields after it. (And ifyou use this second approach, you'd have to use free-format for allreferences to the QUSEC part of the DS, it wouldn't work with fixedformat.)

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 thebad 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 ofi5/OS would have to maintain separate packages for each level of theoperating system. They'd have open rebellion on their hands. It's notgonna 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 amolehill. You're going to create hours or even weeks of extra effort forthe people who have to maintain your programs, and why? To spare yourselfa few minutes work that you MIGHT (but it's unlikely) have to do for arelease upgrade?