Re: Renaming copy member data structure fields

Thanks to everyone for the suggestions and discussion.

>From Scott:
> > 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.

Well, one could replace 'likerec' with 'likeDS' where the argument to 
likeDS is a DS copied from QSYSINC.  Sorry, I should have been more clear 
about that.

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

Well, I was using the QUSRJOBI API to retrieve the group information from 
a user profile.  The program was created on V5R2.  The return DS I was 
using, JOBI0600, had some time zone information tacked on the end at V5R3. 
 When I wrote the program, I didn't want to bother defining all the fields 
in the return DS, so I just did:

     D JOBI0600        DS           322
     D   @@GRPPRF            137    146

     D QUsrParmL       S              4B 0 inz(322)

I know it's not really pretty, but I didn't spend a lot of time thinking 
about a better way to define only the one subfield at the time.  When we 
upgraded to V5R3, some weird things started happening in a couple of 
programs that used my code.  It was fairly minor so we didn't get to it 
right away and the connection with the upgrade was not realized, but after 
a fair amount of debugging I found out that the API return DS had changed. 
 To be honest I'm still a bit confused as to why it caused an error, 
because the call was like this:

     C                   CALLP     QUsrJobI(JOBI0600    :
     C                                      qUsrParmL   :
     C                                      fmtName     :
     C                                      qualJobName :
     C                                      intJobID     )

where qUsrParmL is the length of the receiver variable.  My assumption was 
that the API would only return 322 bytes given in that it was being told 
that was how much room was available to it.  I think that when we 
upgraded, the API was returning a longer DS, so some other internal 
program memory was being corrupted.  Later on in the execution we would 
get pointer errors.  I suppose that none of the methods discussed thus far 
would really solve this problem, as it seems to be an API bug.

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

I had thought of this too.  I wouldn't go so far as to say it's harder to 
follow, but it is probably just as bad.

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

I was just using QUSEC as an example.  I realize that if any layout 
changes are made, this is the least likely one to be changed.

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

My goal was to come up with some way of defining the layouts that was as 
future proof as possible while being as understandable as possible.  I 
think you are right that coding my own DS is the way to go.  If I want to 
only define the subfields I am using in a return layout, I guess I will 
have to bite the bullet and use the positional notation.

Thanks again for your suggestions and comments,
Adam
#####################################################################################
Attention:
The above message and/or attachment(s) is private and confidential and is 
intended 
only for the people for which it is addressed. If you are not named in the 
address 
fields, ignore the contents and delete all the material. Thank you.

For more information on email virus scanning, security and content
management, please contact administrator@xxxxxxxxxxxx
#####################################################################################