1. Coming to Grips with Pointers and User Spaces in RPG IV Phone: +91 9971458335 e-Mail: ramanjosan@yahoo.com Ramandeep Josan
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.
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.
6.
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. 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. 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. 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. Remember When you are using pointers . . . You are indiscriminately playing with memory. You must be careful.
12.
13.
14.
15.
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. 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. 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.
20.
21.
22.
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. 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.
26.
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.
29.
30.
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.
33.
34.
35.
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. 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.
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.
41.
Hinweis der Redaktion
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.