This is the second of two articles discussing the basics of working with API-related data.

When we left off in Part I, we were just calling the Retrieve Call Stack API, QWVRCSTK, for the first time. The program being discussed is repeated below. If you would like to review the API documentation, it can be found here.

dCallStack        pr                  extpgm('CALLSTACK')          

d NbrEntInput                   15p 5 const                        

dCallStack        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)                

 /copy qsysinc/qrpglesrc,qwvrcstk                                  

 /copy qsysinc/qrpglesrc,qwcattr                                   

 /copy qsysinc/qrpglesrc,qusec                                  

dRcvVar           ds                  likeds(QWVK0100)         

d                                     based(RcvVarPtr)         

dEntryInfo        ds                  likeds(QWVCSTKE)         

d                                     based(EntInfPtr)         

dProcName         s            256    based(ProcNamePtr)       

dNbrEnt           s             10i 0                          

dCount            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;                                                              

  EntInfPtr = RcvVarPtr + RcvVar.QWVEO;     // Get the first entry    

  for Count = 1 to NbrEnt;                  // Process all entries    

                                            //   that were requested  

      // 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;                                                        

      EntInfPtr += EntryInfo.QWVEL;         // Move to next entry     

  endfor;                                                             

  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                                                            

As a review, we had just called the QWVRCSTK API, passing the data structure QWVK0100 as our Receiver variable. This data structure is not large enough to have any call stack entries returned, which is controlled by the second parameter (length of receiver variable or '%size(QWVK0100)'), but it's large enough to provide us with critical information.

One piece of information is the status of the information available. The value of field QWVIS may be an 'N', indicating that call stack information is not available; an 'I', indicating that only partial information is available; or a ' ' (blank), indicating that all information is available. As the API makes this status information available to us, we should certainly take advantage of it before doing any more processing. To simply assume that all information was returned, without checking first, is just looking for trouble.

A key consideration when working with returned values is to always be prepared for IBM to add new values in the future. For this reason, the program explicitly checks for each known information status value and also checks for any unexpected value. In the case of complete information (QWVIS = ' ';) or partial information (QWVIS = 'I';) being available, the program proceeds. For this program, partial information is sufficient as the program only needs data that would still be available. For no information being available (QWVIS = 'N';) or an unexpected status value (other;), the program informs the user of the problem and ends. This explicit checking of values may initially appear as being unnecessary, but I assure you it isn't.

One approach you never want to use is to code an implicit assumption (an ELSE or OTHER statement) and then perform processing (other than a simple display, print, or error reporting of the value) based on that assumption. That is, do not check for 'Y' (Yes), assume that if it's not 'Y' it must be 'N' (No), and then process a related value, such as an offset, based on that assumption. The exposure here is assuming 'N' and not being prepared in any way if IBM decides to add 'M' for Maybe or 'C' for Calculate (*CALC). There are many cases in the past where Yes/No values evolved into an enhanced "dynamically calculate the appropriate value"; security level values of 10, 20, 30, and 40 evolved to include 50; executable objects such as *PGMs and *SQLPKGs evolved to include *SRVPGMs; etc. Do not get caught incorrectly processing the data returned by an API because you didn't explicitly verify what your program is working with. That "offset" value from our earlier assumption of 'N' may not be there if the value is really a 'C'!

If call stack information is available, the program then uses the Bytes available field QWVBAVL returned by QWVRCSTK to allocate sufficient storage to hold all of the call stack information. The Bytes available field returned by an API will represent the maximum amount of storage necessary in order to retrieve all relevant information. This is assuming that the environment does not change and that the other parameters used with the API call do not change. In our current program, we would not expect the number of call stack entries (the environment if you will) to change in between calls to QWVRCSTK, but this assumption may not be valid if we were accessing the call stack of another job or thread that is actively running. In the case of a changing environment, we may simply be satisfied with a snapshot (as we use in this example program), or we may alternatively loop on calling QWVRCSTK until Bytes available stabilizes.

After allocating sufficient storage, we then call QWVRCSTK a second time. Note that with this second call we are using a Receiver variable parameter of RcvVar, which is defined as 'likeds(QWVK0100)' and 'based(RcvVarPtr)' and a Length of receiver variable parameter value of  QWVBAVL. The variable RcvVarPtr is the pointer associated with our previous allocation of QWVBAVL bytes, so what we are passing to the API is our recently allocated storage.

As we have called the API a second time, we first verify, with the new Information status field RcvVar.QWVIS, that the call stack information we need is still available. The program then sets the variable NbrEnt to the number of call stack entries to display: the lesser of the number requested by our caller or the Number of call stack entries returned (RcvVar.QWVERTN) by the API.

The program then accesses the first call stack entry by setting the pointer EntInfPtr to the starting address of the Receiver variable parameter (contained in the pointer variable RcvVarPtr) plus the Offset to the call stack entry information field (RcvVar.QWVEO). A key point here is the use of the word offset. The convention when using a retrieve type API is that an offset indicates a number of bytes from the start of the Receiver variable. So the program adds this value (RcvVar.QWVEO) to the pointer addressing the start of the Receiver variable. As EntInfPtr is used as a base pointer for the data structure EntryInfo, which is defined 'likeds(QWVCSTKE)', we now have access to the first call stack entry information.

The program then enters into a DoFor loop conditioned by the number of call stack entries to be displayed. Within the DoFor loop, the program determines if the *PGM or *SRVPGM name (EntryInfo.QWVPGMN) has changed since the previous call stack entry. If it has, the *PGM or *SRVPGM name is displayed. The program then determines if a procedure name is associated with the call stack entry. This is done by determining if the Displacement to the procedure name field (EntryInfo.QWVPD) is not 0.

If it is not 0, the program sets the pointer variable ProcNamePtr to the address of the call stack entry plus the Displacement to the procedure name. The key point here is the use of the word displacement. While offset is used to indicate the number of bytes from the start of the Receiver variable, displacement is used to indicate the number of bytes from the start of the entry currently being processed. So rather than adding EntryInfo.QWVPD to RcvVarPtr, we add it to EntInfPtr. As ProcNamePtr is used as a base pointer for the character variable ProcName, we now have access to the procedure name associated with this call stack entry. The program then displays the procedure name (or as much of it as can be displayed using the dsply opcode).

If the Displacement to the procedure name is 0, the program displays the message "Cannot determine procedure name. OPM perhaps?"

The program then adds the Length of the current call stack entry (EntryInfo.QWVEL) to the pointer variable EntInfPtr and processes the next call stack entry. As the length of a call stack entry is simply the number of bytes from the start of the current entry to the start of the next entry, the program uses this information as a displacement value.

After displaying the correct number of entries, the program then de-allocates the storage previously allocated, displays the message "End of call stack list." and ends.

That's it! Not a large program but you have seen how to determine the amount of storage to allocate in order to retrieve all available information from an API, how to correctly test returned values, how to properly use offset values, and how to properly use displacement values. Not bad.

You may notice, though, that the call stack entries are displayed in "reverse" order from how system commands such as Display Job (DSPJOB) show the call stack. What would be required to reverse the order of the call stack entries we're displaying? Not much! And we'll see that next time.

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

Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it.. 

---

MC Press books written by Bruce Vining available now on the MC Press Bookstore.

		IBM System i APIs at Work Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale

Also Read

The API Corner: Moving Jobs Within and Across Job Queues

The API Corner: What Time Zone Do You Want That Date and Time In?

The API Corner: How Do You Want That Date and Time?