RE: Multi Occurrence Data Structure returned from a procedure -- RPG400-L

I don't know about the new "red book" which I believe Jon is not doing by
the way (but Jon can speak for himself) but my RPG xTools is such a "class
library" and is supported. 

-Bob Cozzi
www.RPGxTools.com
If everything is under control, you are going too slow.
- Mario Andretti


-----Original Message-----
From: rpg400-l-bounces@xxxxxxxxxxxx [mailto:rpg400-l-bounces@xxxxxxxxxxxx]
On Behalf Of Alan Campin
Sent: Wednesday, July 06, 2005 3:37 PM
To: RPG programming on the AS400 / iSeries
Subject: RE: Multi Occurrence Data Structure returned from a procedure

>> (C) write their own
>> version. Most people choose (C) unfortunately. In addition, most people
>> continue to use CALL/CALLB for APIs rather than use the prototyped call.
>> This too is very disappointing.

Have to agree with you 100% on this one Bob. How many times have we seen
people re-implementation IFS in a program. Why do you need ten different
versions of IFS logic? Everyone at my company is using CALLB with no
prototyping. Enough to make me heave and worse implementing service programs
using *ENTRY PLIST's. Absolutely scary.  

There was talk at one time of developing standard class libraries (Standard
service programs) at one place but with all out ego's (Mine especially),
nothing has come of it. I would especially like to see libraries with
standard error handling models like I do in mine. Seems like that is the
piece I see missing in other stuff I see. 

Jon, I wonder if this is something you might consider for the new version of
"I Didn't Know You Could Do That?". Standard class libraries available for
download and all examples using the standard class libraries and discussion
of how the class libraries were developed. Just a thought. 

-----Original Message-----
From: Bob Cozzi [mailto:cozzi@xxxxxxxxx]
Sent: Wednesday, July 06, 2005 11:11 AM
To: 'RPG programming on the AS400 / iSeries'
Subject: RE: Multi Occurrence Data Structure returned from a procedure


I think both solutions are viable, depending on the situation.
Return a pointer for the caller's ability to do things with the data faster
and more directly, return a "handle" to dumb-down the interface and do all
the work for the caller.
I find most programmers in this market do use any helper functions
anyway--they love reinventing the wheel--so they will either (A) use your
interface, (B) wrap it in their own addition code, or (C) write their own
version. Most people choose (C) unfortunately. In addition, most people
continue to use CALL/CALLB for APIs rather than use the prototyped call.
This too is very disappointing.

I have a routine called "Get Pointer to User Space" (the name isn't
important. But most people will still call the QUSCRTUS and QUSRPTRUS APIs,
as follows:

      *********************************************************
      ** C R E A T E  U S E R  S P A C E
      *********************************************************
     D QusCrtUsrSpace  PR                  ExtPgm('QUSCRTUS')
     D  UsrSpace                     20A   Const
     D  ExtAttr                      10A   Const
     D  nSize                        10I 0 Const
     D  InitValue                     1A   Const
     D  PubAuth                      10A   Const
     D  szTextDesc                   50A   Const
     D  Replace                      10A   Const
     D  api_error                          Like(xt_QUSEC) OPTIONS(*NOPASS)
     D  bSysDomain                   10A   Const OPTIONS(*NOPASS)

      *********************************************************
      ** R E T R I E V E   P T R   to   U S E R  S P A C E
      *********************************************************
     D QusRtvPtrToUserSpace...
     D                 PR                  ExtPgm('QUSPTRUS')
     D  szUserspace                  20A   Const

     D  pRtnPtr                        *
     D  api_error                          Like(QUSEC) OPTIONS(*NOPASS)

What my wrapper procedure does is create the user space (if it doesn't
already exist) and then retrieve the pointer to the user space. So you call
the wrapper/add-in procedure as follows:

   Eval   pArray = CrtUserSpacePtr('QTEMP/MYUSRSPC')

The prototype is as follows:

      **************************************************************
      **  C R E A T E   U S E R   S P A C E   G E T   P O I N T E R
      **************************************************************
     D CrtUserSpacePtr PR              *   ExtProc('CRTUSRSPCPTR')
     D  szUserSpace                  21A   Const OPTIONS(*NOPASS:*OMIT)
     D  nInitSize                    10I 0 Const OPTIONS(*NOPASS:*OMIT)


You call CrtUserSpacePtr and it will create the user space unless it already
exists, and then return the pointer to that user space. If you don't pass in
a user space name, then it creates one in QTEMP and returns a pointer to
that user space. A random name is generated to insure uniqueness. Once you
have the pointer, assign it to the pointer variable on which your "dynamic"
array is based, and you're done. The caller really doesn't need to worry
about the pointer any more since user spaces created with CrtUsrSpcPtr() are
automatically increased.  (Just be sure to use the new V5R3 %SUBARR()
built-in when accessing or sorting a subset of the array's elements.


-Bob Cozzi
www.RPGxTools.com
If everything is under control, you are going too slow.
- Mario Andretti


-----Original Message-----
From: rpg400-l-bounces@xxxxxxxxxxxx [mailto:rpg400-l-bounces@xxxxxxxxxxxx]
On Behalf Of Alan Campin
Sent: Wednesday, July 06, 2005 12:49 PM
To: RPG programming on the AS400 / iSeries
Subject: RE: Multi Occurrence Data Structure returned from a procedure

>> Sure, it would be possible to return a numeric value that provided a
reference to an index, which provided a >>    >> reference to an "instance",
but returning the "instance" pointer is a simpler solution.

It might be simpler but I don't agree it is better. Like I indicated in the
previous post, have the user assign a name to the instance and reference it
by the name. A little more work in the service program but a hell of lot
less dangerous for the user of the function. That pointer you are returning
can go anywhere. It is completely type less and can be pointed to anything.
If you assign a name, you can verify the name exists and is valid. Pointer
could be from anywhere.

I have a program I am working on that does dynamic array management. I am
implementing differently but just having the user pass a name to me to
create the array. Internally, I just need a few extra lines of code to
manage the list since you could have multiple arrays open. User just passes
name and I get from list. I have to manage a list with information from the
array anyway. Why not just add the name to the list?

Anyway, my opinion only. I just feel there is always an alternative.

-----Original Message-----
From: Nathan Andelin [mailto:nandelin@xxxxxxxxx]
Sent: Tuesday, July 05, 2005 8:40 PM
To: RPG programming on the AS400 / iSeries
Subject: RE: Multi Occurrence Data Structure returned from a procedure


Scott,
 
I'm with you on this one.  You've described a technique that I've used a
lot, and found to be very practical.
 
Consider the example of a service program that exports a set of procedures
for managing linked lists, which some folks call dynamic arrays.  One
procedure could instantiate a new list, and return a pointer to that
"instance".
 
The instance pointer could be passed to other procedures used to add or
remove entries in the list.  The list "instance" is a reference to a
dynamically allocated data structure, having sub-variables that specify the
number of entries in the list, the pointer to the first entry in the list,
and so forth.
 
Sure, it would be possible to return a numeric value that provided a
reference to an index, which provided a reference to an "instance", but
returning the "instance" pointer is a simpler solution.
 
Nathan M. Andelin


Scott Klement <rpg400-l@xxxxxxxxxxxxxxxx> wrote:Hi Alan,

> Returning pointers from a service program or external routine is
> extremely bad form no matter what. The only time that I find it
> appropriate is where it must be returned as with a
> USPC_GetPointerToUserSpace.

I agree with you that you should not return pointers in situations where
the calling routine is expected to interpret the contents of the memory
that it points to.

However, by the same token, I don't think returning a pointer to a user
space is a good idea, either!! The calling program shouldn't need to know
that you've stored your data in a user space, or dynamic memory, or a
file, or anything else -- all of that should be transparent to the caller!
Returning a pointer to a user space is every bit as bad as returning a
pointer to allocated memory or to a static variable.

Unfortunately, in the case of MODS, there's no other way to pass them from
one procedure to another. So, if you MUST pass a MODS, that's how you have
to do it. Though, I agree that replacing the MODS with multiple calls to
a procedure is better, if it's possible.

The one place that I do allow returning a pointer is when the pointer is
"opaque". In other words, the caller doesn't need to know what it points
to, what the format of that space is, how big it is... it doesn't have to
know anything about it. Although I know that some people on this list
won't agree with me, I don't think an opaque pointer is that bad. It's
certainly better than returning a data structure (which is the workaround
that I've seen many people do)

For example, let's say you're creating a service program that works with
an order. You want to use a pseudo-object-oriented approach. So you do
something like this:

x = order_new();
order_load(x: 'SA12354');
order_setShipTo(x: 'Scott Klement'
: '123 Sesame St'
: 'Milwaukee'
: 'WI'
: '53201' );
order_save(x);
order_destroy(x);

In the code above, X is a pointer. The "ORDER" service program contains
subprocedures called "order_new" "order_load" "order_setShipTo", etc.
Inside that service program, it points to a data structure that contains
all of the per-order state information. That way, the srvpgm can be
written to allow many different "order objects" to be created at once.

To encapsulate this, order_new() allocates space for the DS, and returns
the pointer. The caller doesn't know what the format of the memory, the
size of the allocatation, etc are. All it knows is that this is a "handle"
that it has to pass back to the other routines in the order srvpgm.
Obviously, order_destroy() frees up that memory.

That way, if I need to add more stuff to the ORDER srvpgm's data
structure, I can make the allocation bigger, add fields, etc, without
breaking anything.

I consider this approach to be acceptible. Now, I know someone is going
to reply to this message and tell me that I should use a numeric handle
instead of a pointer. And, I don't disagree, but I don't think the
pointer method is bad, either. If someone is foolish enough to examine
the memory that the pointer points to and try to reverse engineer the data
structure, they deserve their fate when an upgrade breaks compatibility :)

But, for sure, in a situation like yours where people are returning a
pointer and expecting the caller to interpret the memory, I think that's a
bad idea, and should be nipped in the bud.
--
This is the RPG programming on the AS400 / iSeries (RPG400-L) mailing list
To post a message email: RPG400-L@xxxxxxxxxxxx
To subscribe, unsubscribe, or change list options,
visit: http://lists.midrange.com/mailman/listinfo/rpg400-l
or email: RPG400-L-request@xxxxxxxxxxxx
Before posting, please take a moment to review the archives
at http://archive.midrange.com/rpg400-l.



__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around
http://mail.yahoo.com



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