What would be required to reverse the order of displayed call stack entries? In this article, we'll look at one way to accomplish this.

When we left off in the previous article, "The API Corner: Retrieving Information, Part II," we were successfully displaying the call stack of the current thread, with the current procedure being shown at the top of the listing. But various system functions, such as the Display Job (DSPJOB) command, show the call stack with the initial program or procedure first and the current procedure last. To mimic this behavior, what would be required?

One immediate problem is that while format CSTK0100 of the Retrieve Call Stack (QWVRCSTK) API gives great information when moving forward through the call stack entries (the length of this call stack entry field QWVEL providing a displacement value to move from one entry to the next), there isn't anything related to moving backward through the list of variable-length entries. We could maintain an array of the pertinent information (perhaps the offsets to each entry or the program and procedure names themselves) as we move through the call stack entries and then display this information processing the array in reverse sequence. But surely there's a better way.

And of course there is. This is not so much a "tip" about APIs, but rather a technique based on ILE RPG capabilities that can be applied to many situations, this being one of them. Rather than maintain an array or stack of values within our program, let's instead recursively dive to the appropriate call stack entry and then display the information associated with each call stack entry as we come back up.

A program demonstrating this approach is shown below:

h dftactgrp(*no)                                                   

dCallStack2       pr                  extpgm('CALLSTACK2')         

d NbrEntInput                   15p 5 const                        

dCallStack2       pi                                                

d NbrEntInput                   15p 5 const                        

dGetCallStack     pr                  extpgm('QWVRCSTK')           

d RcvVar                         1    options(*varsize)            

d LenRcvVar                     10i 0 const                        

d FmtRcvVar                      8    const                        

d JobID                      65535    const options(*varsize)      

d FmtJobID                       8    const                        

d ErrCde                              likeds(QUSEC)                

dDisplayCSE       pr                                                

d EntInfPtr                       *   value                      

 /copy qsysinc/qrpglesrc,qwvrcstk                                

 /copy qsysinc/qrpglesrc,qwcattr                                 

 /copy qsysinc/qrpglesrc,qusec                                   

dRcvVar           ds                  likeds(QWVK0100)           

d                                     based(RcvVarPtr)           

dProcName         s            256    based(ProcNamePtr)         

dNbrEnt           s             10i 0                            

dCurProcName      s             52                               

dPrvPgmName       s             10                               

dWait             s              1                               

 /free                                                           

  // Check for parameter, default to all                         

  if %parms = 0;                                                      

     NbrEnt = *hival;                                                  

  else;                                                               

     NbrEnt = NbrEntInput;                                            

  endif;                                                              

  // API is to return escape messages if an error is found            

  QUSBPRV = 0;                                                        

  // Initialize Job identification format JIDF0100                    

  QWCF0100 = *loval;                        // Set structure to x'00's

    QWCJN02 = '*';                          //   Job name: * = this job

    QWCUN = *blanks;                        //   User name            

    QWCJNBR00 = *blanks;                    //   Job number           

    QWCIJID = *blanks;                      //   Internal job ID      

    QWCTI00 = 1;                            //   Thread = this thread 

  // Call API to find out how much storage is needed                 

  GetCallStack(QWVK0100 :%size(QWVK0100) :'CSTK0100'                 

               :QWCF0100 :'JIDF0100' :QUSEC);                        

  // Check information status                                        

  select;                                                            

     when QWVIS = ' ';                      // Info OK               

     when QWVIS = 'I';                      // Info partial, still OK

     when QWVIS = 'N';                      // Info not available    

          dsply 'Information is not available.' ' ' Wait;            

          *inlr = *on;                                               

          return;                                                    

     other;                                                          

          dsply ('Unexpected status value of ' + QWVIS) ' ' Wait;    

          *inlr = *on;                                               

          return;                                                    

  endsl;                                                              

  RcvVarPtr = %alloc(QWVBAVL);              // Get the storage        

  GetCallStack(RcvVar :QWVBAVL :'CSTK0100'  // Call API again to get  

               :QWCF0100 :'JIDF0100' :QUSEC);  // all of the data     

  // Check information status in case anything has changed            

  select;                                                              

     when RcvVar.QWVIS = ' ';               // Info OK                

     when RcvVar.QWVIS = 'I';               // Info partial, still OK 

     when RcvVar.QWVIS = 'N';               // Info not available     

          dsply 'Information is not available.' ' ' Wait;             

          *inlr = *on;                                                

          return;                                                     

     other;                                                           

          dsply ('Unexpected status value of ' + RcvVar.QWVIS) ' 'Wait;

          *inlr = *on;                                                

          return;                                                     

  endsl;                                                               

  // If call stack isn't as large as user requested, then tell them   

  if NbrEnt > RcvVar.QWVERTN;                                         

     NbrEnt = RcvVar.QWVERTN;                                         

     dsply ('Showing ' + %char(NbrEnt) + ' call stack entries.');     

  endif;                                                              

  DisplayCSE(RcvVarPtr + RcvVar.QWVEO);     // Process all entries    

                                            //   that were requested  

  dealloc RcvVarPtr;                        // Free the storage       

  dsply 'End of call stack list.' ' ' Wait; // Wait for the operator  

                                            //   to indicate list read

  *inlr = *on;                                                        

  return;                                                             

 /end-free                                                    

pDisplayCSE       b                                          

dDisplayCSE       pi                                          

d EntInfPtr                       *   value                  

dEntryInfo        ds                  likeds(QWVCSTKE)       

d                                     based(EntInfPtr)       

 /free                                                       

  NbrEnt -= 1;                                                

  if NbrEnt > 0;                                             

     DisplayCSE(EntInfPtr + EntryInfo.QWVEL);                

  endif;                                                     

  // Display Pgm/Srvpgm name when it changes                        

  if EntryInfo.QWVPGMN <> PrvPgmName;                               

     PrvPgmName = EntryInfo.QWVPGMN;                                

     dsply ' ';                                                      

     dsply ('Program name: ' + EntryInfo.QWVPGMN);                  

  endif;                                                            

  // If procedure name was returned, display it up to the max       

  // byte limitation of the dsply opcode (currently 52)             

  if EntryInfo.QWVPD > 0;                                           

     ProcNamePtr = EntInfPtr + EntryInfo.QWVPD;                      

     if EntryInfo.QWVPL > %size(CurProcName);                       

        CurProcName = %subst(ProcName :1 :%size(CurProcName));      

     else;                                                          

        CurProcName = *blanks;                                      

        CurProcName = %subst(ProcName :1 :EntryInfo.QWVPL);         

     endif;                                                    

     dsply CurProcName;                                        

  else;                                                         

     dsply 'Cannot determine procedure name. OPM perhaps?';    

  endif;                                                       

  return;                                                      

 /end-free                                                     

pDisplayCSE       e                                                             

The actual changes to the original program are minimal.

First, we remove the declares for variables EntInfPtr and EntryInfo from the main procedure as we will be moving these variables into a new procedure, Display Call Stack Entry (DisplayCSE). We also remove the DoFor loop and associated control field Count found in the original program. Instead, we will use the NbrEnt field to control how deeply we recursively dive into the returned list of call stack entries. Where we previously entered into the DoFor loop, we now simply call DisplayCSE, passing a pointer to the first call stack entry. This is done with the statement 'DisplayCSE(RcvVarPtr + RcvVar.QWVEO);'.

Next, we define the procedure DisplayCSE. This procedure accepts one parameter: a pointer to the current call stack entry. DisplayCSE first decrements the global variable NbrEnt, which reflects how many entries remain to be processed. If NbrEnt is greater than 0, DisplayCSE recursively calls DisplayCSE , passing a pointer to the next call stack entry to be processed ('DisplayCSE(EntInfPtr + EntryInfo.QWVEL);'). When NbrEnt becomes 0, the program has read through the appropriate number of call stack entries, and DisplayCSE then continues processing the current entry. This display processing is the same as that used in the original program. The one difference is that instead of calculating the address of the next call stack entry, DisplayCSE simply returns to the previous instance of DisplayCSE at the bottom of the DoFor loop.  That instance processes its current call stack entry and again returns to its caller. This continues until all call stack entries have been processed and displayed. The program then ends in the same way as the original program: de-allocating the storage associated with RcvVarPtr and indicating that the list is finished.

If you have never used recursion in your applications, this capability of ILE RPG is a powerful tool that can greatly simplify the development of certain types of applications. If the call stack entries had been of fixed length, I would have used other techniques, but when working "backward" through variable-length entries, recursion can certainly simplify the application program.

If you have other API questions, send them to me at This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll see what I can do about answering your burning questions in future columns.