Rpg Pointers And User Space


Published on

Important Points to learn Pointers in RPG IV

1 Comment
  • This is a very badly copied version of my presentation 'Getting to Grips with Pointers and User Spaces'. The only thing that has been changed is the title. This presentation has been copied without my permission.
    It seems that Josan Ramandeep is one of those people that likes to take other peoples work and represent it as their own.
    Are you sure you want to  Yes  No
    Your message goes here
  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • You don't actually have to define Pointers. If the compiler comes across a pointer in a Based keyword, it will automatically define it for you - so watch the spelling! The only time you need to be concerned about the length of a pointer is when is is defined in a data structure - check out the ALIGN keyword for further details.
  • The nearest that traditional programming can come to this concept is a data area, but you have to input and output data areas to and from programs. In contrast, you can immediately change the content of a user space by merely changing the value of a field in your program.
  • CatData is an externally defined data structure that uses the table being copied to the user space for the external definition. When a record is read from the file it is automatically placed in this data structure. NumRows is the integer that contains the count of the number of rows. It will be mapped to the starting position of the user space. pNumRows is the basing pointer for NumRows . CatSpace is an array where each element contains an image of a record. It will be mapped to the remainder of the user space. Note that the array is defined with the maximum number of elements (32767) so you must ensure that the program does not try to reference an element that is beyond the actual size of the user space. Since the array is based on a pointer (CATPTR), no storage is allocated for the array; therefore, the size allocated would be the same if you had defined the array with 50 elements. pCatSpace is the basing pointed for CatSpace .
  • The program starts by calling QUSPTRUS to load the user space and retrieve the pointer to it. The pointer for the array of rows is calculated as the starting pointer ( pNumRows ) plus the size of the based field ( NumRows ).
  • NumRows is used as the index for the array. A loop is used to perform a sequential read of the table and for every record the data structure (into which the record is automatically placed) is copied to the next element of the loop. At end of file NumRows will reflect the number of rows copied. The user space now contains an image of the rows in the table along with a field that indicates how many rows there are. A sleight word of warning; if you need to perform a LOOKUP operation on an array in a user space ensure that you use one of the %LOOKUP BIFs and that you specify the optional number of elements parameter. Remember that the definition of the array in the program will more then likely exceed the actual number of elements in the user space.
  • Rpg Pointers And User Space

    1. 1. Coming to Grips with Pointers and User Spaces in RPG IV Phone: +91 9971458335 e-Mail: ramanjosan@yahoo.com Ramandeep Josan
    2. 2. Ramandeep Josan Ramandeep Josan has worked in the development of IBM Midrange applications for 8+ years and 3 years on Java using J2ME technology. He is Project Management professional (PMBOK4 - from PMI) and Sun Java certified. He is Project manager for Satyam and has worked for various banking organizations across the globe.
    3. 3. Agenda <ul><li>What are pointers? </li></ul><ul><li>How to use pointers. </li></ul><ul><li>Why use pointers? </li></ul><ul><ul><li>Allocating record layouts in trigger programs </li></ul></ul><ul><ul><li>Used with C functions </li></ul></ul><ul><ul><li>Dynamic memory allocation </li></ul></ul><ul><ul><li>User spaces </li></ul></ul><ul><ul><li>Procedure pointers </li></ul></ul>
    4. 4. What is a pointer? Basing pointers are used to locate the storage for based variables. The storage is accessed by defining a field, array, or data structure as based on a particular basing pointer variable and setting the basing pointer variable to point to the required storage location.
    5. 5. What is a pointer? <ul><li>A pointer is a field that contains a memory address. </li></ul><ul><ul><li>Assuming that Name is a 30-character field, translate the eval operation as &quot;from the address of Name, blank out the next thirty characters&quot;. </li></ul></ul><ul><ul><li>If we could control &quot;the address of Name&quot;, we would have a pointer! </li></ul></ul>Eval Name = *Blanks Program Storage
    6. 6. Pointers have always been used in . . . <ul><li>Pointers are not new to RPG -- we just have not been able to manipulate them. </li></ul><ul><li>Multiple Occurrence Data Structures </li></ul><ul><ul><li>The occurrence of the database is based on an offset of the address of the data structure. </li></ul></ul><ul><ul><ul><li>DS = Address of MODS + (Length of DS * (Occurrence – 1)) </li></ul></ul></ul><ul><li>Parameter Lists </li></ul><ul><ul><li>When passing a parameter the actual parameter field is not passed, but a pointer containing the address of the parameter field. This address is then used as the basis for the parameter field in the called program. </li></ul></ul><ul><ul><li>Lets take a closer look at parameters! </li></ul></ul>
    7. 7. Parameter lists BProgram(I: J: K); <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> D BProgram PI D X 15 D Y 10 D Z 5 Storage of Calling Program I J K Storage of Called Program X Y Z
    8. 8. The problem with pointers BProgram(I: J: K); <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> D BProgram PI D X 15 D Y 10 D Z 15 Z = *Blanks; Storage of Calling Program I J K Storage of Called Program X Y Z Oops!
    9. 9. The problem with pointers BProgram(I: J: K); <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> D BProgram PI D X 15 D Y 10 D Z 15 Z = *Blanks; Storage of Calling Program I J K Storage of Called Program X Y Z Oops!
    10. 10. Better get used to . . . Message ID . . . . . . : RNQ0222 Date sent . . . . . . : 13/09/02 Time sent . . . . . . : 11:40:31 Message . . . . : Pointer or parameter error (C G D F). Cause . . . . . : RPG procedure BASICF in program SPACE01/BASICF at statement 51 had an error due to a pointer not being correctly set. The cause of the error is most likely one of the following: * A basing pointer was not set. * A procedure pointer was not set. * The pointer was set, but the object it referenced has been destroyed. * A parameter was not passed to the program containing the procedure. * A parameter was not passed to the procedure by its caller within the program. * A pointer offset was greater than the size of the space the pointer was pointing to.
    11. 11. Remember When you are using pointers . . . You are indiscriminately playing with memory. You must be careful.
    12. 12. DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords++++++++++++++++++++ D pPointer S * D BasedField S 20 Based(pPointer) Pointers in RPG IV <ul><li>We can now define pointer data types. </li></ul><ul><li>Also, we can define fields, arrays and data structures whose &quot;positioning&quot; in memory is based on the value of a pointer. </li></ul><ul><ul><li>In other words, when a field is based on a pointer, memory is not allocated for the field when the program loads but is allocated dynamically based on the value of the pointer field. </li></ul></ul><ul><li>If a pointer is used but not defined, the compiler will automatically define it – so watch out for spelling! </li></ul>
    13. 13. Pointers at work Storage of Program <ul><li>pPointer = *Null </li></ul>BasedField 1
    14. 14. Pointers at work Storage of Program 2 <ul><li>pPointer = *Null </li></ul><ul><li>pPointer = An Address </li></ul><ul><li>pPointer = Another Address </li></ul><ul><li>pPointer = Yet Another Address </li></ul><ul><li>pPointer = %Addr(BlueField) </li></ul>BasedField 1 4 3 5
    15. 15. Using pointers DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords++++++++++++++++++++ D pPointer S * Inz(%Addr(Text1)) D BasedField S 5 Based(pPointer) * &quot;Overlays&quot; Text1 D MyDS DS D Text1 4 Inz('ABCD') D Text2 4 Inz('WXYZ') C Eval pPointer = %Addr(Text2) * Now, BasedField &quot;Overlays&quot; Text2 <ul><li>Pointers have a data type of '*' and you don't define a length. </li></ul><ul><ul><li>Actually uses 16 bytes of storage. </li></ul></ul><ul><li>Fields are &quot;subject&quot; to a pointer using the Based Keyword. </li></ul><ul><li>The value of a pointer is set using the %Addr Built-in Function. </li></ul>
    16. 16. Why use pointers? * When allocating record layouts in trigger programs. * Used with C functions. * Dynamic memory allocation. * Used with many APIs - e.g., user spaces * As a way of calling procedures.
    17. 17. Standard trigger buffer D TriggerBuffer DS Qualified D FileName 10 D LibraryName 10 D MemberName 10 D Event 1 D Time 1 D CommitLock 1 D Fill01 3 D CCSID 10I 0 D RRN 10I 0 D Fill02 4 D OldOffset 10I 0 D OldLength 10I 0 D OldNullOff 10I 0 D OldNullLen 10I 0 D NewOffset 10I 0 D NewLength 10I 0 D NewNullOff 10I 0 D NewNullLen 10I 0 * Before and After Images Offset to New Record Offset to Original Record
    18. 18. D OldFile E DS ExtName(FileName) D Qualified D NewFile E DS ExtName(FileName) OldFile = %SubST(TriggerBuffer: TriggerBuffer.OldOffset+1: TriggerBuffer.OldLength); NewFile = %SubST(TriggerBuffer: TriggerBuffer.NewOffset+1: TriggerBuffer.NewLength) Accessing the Trigger Buffer The %SUBST Built-in Function can be used to copy the contents of the Trigger Buffer to the relevent externally described data structures.
    19. 19. D OldFile E DS ExtName(FileName) D Qualified D Based(OldPtr) D NewFile E DS ExtName(FileName) D Based(NewPtr) D OldPtr S * D NewPtr S * OldPtr = %Addr(TriggerBuffer) + TriggerBuffer.OldOffset NewPtr = %Addr(TriggerBuffer) + TriggerBuffer.NewOffset Using pointers <ul><li>The two externally described data structures can be mapped onto the relevent portions of the Trigger Buffer by basing them on pointers and setting the values of the pointers to be the address of the buffer + the relevent offset. </li></ul><ul><ul><li>No data is copied!!! </li></ul></ul>
    20. 20. C functions D GetToken Pr * ExtProc('strtok') D pString * Value Options(*String) D pDelimiters * Value Options(*String) <ul><li>Many C functions require pointers as parameters and return a pointer. </li></ul><ul><ul><li>Example: The strtok (string tokenize) function. </li></ul></ul><ul><ul><li>This function breaks up a string into &quot;tokens“ </li></ul></ul><ul><ul><li>Refer to the Redbook &quot;Who Knew You Could Do That With RPG IV?&quot; for detailed details. </li></ul></ul><ul><li>C functions are not easy to interpret. </li></ul><ul><ul><li>Function names are case sensitive. </li></ul></ul><ul><ul><li>Refer to Barbara Morris’ &quot; Converting from C prototypes to RPG prototypes&quot; </li></ul></ul><ul><ul><li>http://www.opensource400.org/callc.html. </li></ul></ul>
    21. 21. D SortIt PR ExtProc('qsort') D DataStart * Value D Elements 10U 0 Value D Size 10U 0 Value D CompFunc * ProcPtr Value D FindIt PR * ExtProc('bsearch') D LookFor * Value D DataStart * Value D Elements 10U 0 Value D Size 10U 0 Value D CompFunc * ProcPtr Value Other C functions <ul><li>qsort and bsearch can be used as more powerful versions of SORTA and LOOKUP. </li></ul><ul><ul><li>Refer to the Redbook &quot;Who Knew You Could Do That With RPG IV?&quot; for details and examples. </li></ul></ul>
    22. 22. Dynamic Memory Allocation D Array S 10 Based(pArray) Dim(10000) D pArray S * D MaxElem S 10U 0 Inz(10) /Free pArray = %Alloc(%Size(Array) * MaxElem); MaxElem = MaxElem + 10; pArray = %ReAlloc(pArray: %Size(Array) * MaxElem); DeAlloc pArray; *InLR = *On; /End-Free <ul><li>Dynamic Memory Allocation is useful if you are unsure how much space will be required by a variable at run time. </li></ul><ul><ul><li>%Alloc - allocates the required amount of storage. </li></ul></ul><ul><ul><li>%ReAlloc - reallocates the current storage to a new size </li></ul></ul><ul><ul><li>DeAlloc - frees the allocated storage </li></ul></ul><ul><ul><ul><li>N.B. Allocated storage should be freed. </li></ul></ul></ul>
    23. 23. Example of Dynamic Memory Allocation D PathArray S * Dim(32767) D Based(pPathArray) // Allocate memory for the array of pointers pPathArray = %alloc((%size(pDataPtr) * NumberInList)); // Build the array of pointers to the path entries for i = 1 to NumberInList; j = j + 1; If (j > %Elem(PathArray)); pPathArray = pPathArray + (%Size(pDataPtr) * %Elem(PathArray)); j = 1; EndIf; PathArray(j) = pDataPtr; This example shows the use of dynamic memory allocation for an array that may have more then 32767 elements. The array is “repositioned” every 32767 elements.
    24. 24. Example of Dynamic Memory Allocation PathArray 1. NumberInList = 70,000 %Size(PDataPtr) = 16 2. PathArray pPathArray = address of allocated memory 3. Program loops through 32767 elements of PathArray 4. “Move” the position of the array pPathArray = pPathArray + (%Size(pDataPtr) * %Elem(PathArray)); 5. etc. < 1 ---------------- 524,272 > < 524,273------------ 1,048,544 > < 1,048,545 --------- 1,572,816 > 5. PathArray 4. PathArray %Alloc assigns 1,120,000 bytes 2. pPathArray= %alloc((%size(pDataPtr)*NumberInList)); < 1 ----------------------------------------------------- 1,120,000 >
    25. 25. <ul><li>Contrary to popular belief, a user space is not what you find between a user's ears. </li></ul><ul><li>It is </li></ul><ul><ul><li>An object on the iSeries (I5, AS/400) with an object type of *USRSPC. </li></ul></ul><ul><ul><li>It is simply a stream of bytes that you can access directly from within a program. </li></ul></ul><ul><ul><li>A user space effectively becomes a field in your program. </li></ul></ul><ul><ul><li>More precisely (even though it might sound extremely vague), a user space is whatever you want it to be. </li></ul></ul><ul><li>The advantages to employing a user space lie in speed of access and the fact that data can be shared between programs without having to perform I/O!!!! </li></ul>What is a user space?
    26. 26. User space APIs <ul><li>You must use APIs to create user spaces and manipulate their contents. </li></ul><ul><ul><li>In fact, the only user space command you will find is the Delete User Space (DLTUSRSPC) command. </li></ul></ul><ul><li>Incorporating a user space into an application involves two user space APIs: </li></ul><ul><ul><li>Create User Space (QUSCRTUS). </li></ul></ul><ul><ul><li>Retrieve Pointer to User Space (QUSPTRUS). </li></ul></ul>
    27. 27. Create user space D CreateSpace PR ExtPgm('QUSCRTUS') D UserSpaceName 20 Const D Attribute 10 Const D Size 10I 0 Const D Initial 1 Const D Authority 10 Const D Text 50 Const * Optional Parameter Group 1 D Replace 10 Const Options(*NOPASS) D ErrorCode Const Options(*NOPASS) D Like(StandardAPIError) * Optional Parameter Group 2 D Domain 10 Const Options(*NOPASS) * Optional Parameter Group 3 D TransferSize 10I 0 Const Options(*NOPASS) D OptimumAlign 1 Const Options(*NOPASS) CreateSpace(UserSpace:'DTA':10000: X'00':'*ALL':Text); The QUSCRTUS API is called to create a user space
    28. 28. Create user space DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords++++++++++++++++++++ D UserSpace S 20 Inz('USERSPACE *CURLIB') D Attribute S 10 Inz('DTA') D Size S 10I 0 Inz(10000) D Initial S 1 Inz(X'00') D Authority S 10 Inz('*ALL') D Text S 50 Inz('Sample User Space') <ul><li>The parameters used on the QUSCRTUS API are: </li></ul><ul><ul><li>UserSpace: The name and library of the user space. </li></ul></ul><ul><ul><li>Attribute: The attribute parameter is any name you wish it to be. </li></ul></ul><ul><ul><li>Size: The initial length of the user space in bytes. </li></ul></ul><ul><ul><li>Initial: The initial value used to fill the user space. </li></ul></ul><ul><ul><li>Authority: Public authority to the user space. </li></ul></ul><ul><ul><li>Text: The text description. </li></ul></ul>
    29. 29. Fill user space D CatData E DS ExtName(Category) D NumRows S 5I 0 Based(pNumRows) D pNumRows S * D CatSpace S Dim(32767) Based(pCatSpace) D Like(CatData) D pCatSpace S * <ul><li>We map a variable in the program onto the user space. </li></ul><ul><ul><li>If we change the variable, we are also changing the user space. </li></ul></ul><ul><ul><li>We map the CATSPACE array onto the CATEGORY user space. </li></ul></ul><ul><ul><li>Each element of CATSPACE will contain a record from the Category file. </li></ul></ul>
    30. 30. Fill user space D GetSpace PR ExtPgm('QUSPTRUS') D SpaceName 20 Const D pSpacePtr * * Optional Parameter Group D ErrorCode Const Options(*NOPASS) D Like(StandardAPIError) D UserSpace S 20 Inz('CATEGORY *LIBL ') GetSpace(SpaceName:pNumRows); pCatSpace = pNumRows + %Size(NumRows); <ul><li>The call to QUSPTRUS API returns a value in the pNumRows field. </li></ul><ul><ul><li>This value reflects the address of the requested user space. </li></ul></ul><ul><ul><li>NumRows now overlays the first two bytes of the user space. </li></ul></ul><ul><ul><li>pCatSpace is equal to the value of pNumRows + 2. </li></ul></ul><ul><ul><li>The array CatSpace overlays the user space starting at position 3. </li></ul></ul>
    31. 31. Fill user space NumRows = 0; Read Category; DoW Not %EOF(Category); NumRows = NumRows + 1; CatSpace(NumRows) = CatData; Read Category; EndDo; We have a loop that fills the user space by reading a record from the category file and adding it to the next element of the array.
    32. 32. Using the user space D CatData E DS ExtName(Category) D NumRows S 5I 0 Based(pNumRows) D pNumRows S * D CatSpace S Dim(32767) Based(pCatSpace) D Like(CatData) D pCatSpace S * <ul><li>This example shows a subfile being loaded from a user space instead of a file. </li></ul><ul><ul><li>The program DOES NOT contain a F spec for the file. </li></ul></ul><ul><ul><li>Again, we define the array based on a pointer. </li></ul></ul>
    33. 33. Using the user space // Obtain pointers to the user space GetSpace(SpaceName:pNumRows); pCatSpace = pNumRows + %Size(NumRows); <ul><li>The call to the QUSPTRUS API maps the array to the user space. </li></ul><ul><ul><li>The call to QUSPTRUS is usually issued in the *INZSR subroutine, since it needs to be done only when the program is first loaded. </li></ul></ul>
    34. 34. Using the user space For RRN = 1 To NumRows; CatData = CatSpace(RRN); Write SubRec; EndFor; <ul><li>The subfile is now loaded from the array as opposed to the category file. </li></ul><ul><ul><li>The relative record number (RRN) for the subfile doubles as the element pointer for the array. </li></ul></ul><ul><ul><li>Each iteration of the For loop places the next element of the array in the next subfile record. </li></ul></ul><ul><ul><ul><li>The same field names are used in the subfile record format and the CatData data structure. </li></ul></ul></ul>
    35. 35. <ul><li>User spaces are used with many of the system-supplied APIs, especially any of the &quot;list style&quot; APIs. </li></ul><ul><ul><li>Data is &quot;output&quot; to a user space and your program pages through the user space. </li></ul></ul><ul><li>This is an example of using the List Objects API </li></ul>APIs and user spaces D ListObjects PR ExtPgm('QUSLOBJ') D UserSpace 20 Const D Format 8 Const D Objects 20 Const D ObjectType 10 Const D ErrorCode Like(StandardAPIError) CreateSpace('MYSPACE QTEMP ':'DTA':10000: X'00':'*ALL': 'All Objects in MYLIB'); ListObjects('MYSPACE QTEMP ':'OBJL0100': '*ALL MYLIB ':'*ALL ':APIError);
    36. 36. The user space APIs are documented in the Information Center under Programming->APIs->APIs by Category->Object APIs. The use of user spaces for other APIs is detailed in the documentation of the individual APIs (like QUSLOBJ) API documentation
    37. 37. Backup and Recovery APIs Office APIs Client Management Support APIs Operational Assistant APIs Communications APIs Performance Collector APIs Configuration APIs Print APIs Debugger APIs Problem Management APIs Dynamic Screen Manager APIs Program and CL Command APIs Edit Function APIs Registration Facility APIs File APIs Remote Procedure Call APIs Hardware Resource APIs Security APIs Hierarchical File System APIs Server Support APIs High-Level Language APIs Software Product APIs ILE CEE APIs UNIX-Type APIs Journal and Commit APIs User Interface APIs Message Handling APIs Virtual Terminal APIs National Language Support APIs Work Management APIs Network Management APIs Work Station Support APIs Object APIs Miscellaneous APIs Categories of APIs Each has its own section, so pick a topic and while away a weekend in perusal.
    38. 38. Procedure pointers D pGenProc S * ProcPtr D GenProc PR 30 ExtProc(pGenProc) pGenProc = %PAddr('Proc01'); Returned = GenProc(); pGenProc = %PAddr('AnotherProcAltogether'); Returned = GenProc(); <ul><li>Procedure pointers point to the address of a procedure </li></ul><ul><ul><li>Identified by the ProcPtr Keyword </li></ul></ul><ul><ul><li>The ExtProc keyword has the name of the pointer </li></ul></ul><ul><ul><li>Value set using the %PAddr BIF. </li></ul></ul><ul><ul><ul><li>Watch those quotes! </li></ul></ul></ul><ul><ul><ul><li>Watch case! </li></ul></ul></ul><ul><ul><ul><li>Parameters should be the same for all procedures. No check; it is up to you. </li></ul></ul></ul>
    39. 39. Any clearer now? Basing pointers are used to locate the storage for based variables. The storage is accessed by defining a field, array, or data structure as based on a particular basing pointer variable and setting the basing pointer variable to point to the required storage location.
    40. 40. Check out the RPG IV Redbook Who Knew You Could Do That with RPG IV? A Sorcerer's Guide to System Access and More SG24-5402 International Technical Support Organization Rochester, Minnesota <ul><ul><li>Go to www.redbooks.ibm.com </li></ul></ul><ul><ul><ul><li>You can read it online, download the PDF file, or order a hardcopy </li></ul></ul></ul><ul><ul><li>Includes worked examples of </li></ul></ul><ul><ul><ul><li>TCP/IP sockets </li></ul></ul></ul><ul><ul><ul><li>CGI programming </li></ul></ul></ul><ul><ul><ul><li>Using the C function library </li></ul></ul></ul><ul><ul><ul><li>ILE error handling </li></ul></ul></ul><ul><ul><ul><li>and much more </li></ul></ul></ul>
    41. 41. Summary <ul><li>Pointers open new possibilities. </li></ul><ul><li>Pointers can be dangerous. </li></ul><ul><ul><li>Treat them with respect. </li></ul></ul><ul><li>They are a neccessity for many C functions. </li></ul><ul><li>They are a neccessity for many APIs. </li></ul><ul><li>User spaces are great! </li></ul>