The API Corner Retrieving Information, Continued

7/27/2019 The API Corner Retrieving Information, Continued

1/9

The API Corner: Retrieving Information, Continued

Contributed by Bruce ViningWednesday, 21 May 2008Last Updated Monday, 19 May 2008

What would be required to reverse the order of displayed call stack entries? In this article, we'll look at one way toaccomplish this. By Bruce Vining When we left off in the previous article, "The API Corner: Retrieving Information, Part II," we were successfully displayingthe call stack of the current thread, with the current procedure being shown at the top of the listing. But various systemfunctions, such as the Display Job (DSPJOB) command, show the call stack with the initial program or procedure firstand the current procedure last. To mimic this behavior, what would be required?

What would be required to reverse the order of displayed call stack entries? In this article, we'll look at one way toaccomplish this. When we left off in the previous article, "The API Corner: Retrieving Information, Part II," we were successfully displayingthe call stack of the current thread, with the current procedure being shown at the top of the listing. But various systemfunctions, such as the Display Job (DSPJOB) command, show the call stack with the initial program or procedure firstand 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 greatinformation when moving forward through the call stack entries (the length of this call stack entry field QWVEL providinga displacement value to move from one entry to the next), there isn't anything related to moving backward through the listof variable-length entries. We could maintain an array of the pertinent information (perhaps the offsets to each entry orthe program and procedure names themselves) as we move through the call stack entries and then display thisinformation 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 thatcan be applied to many situations, this being one of them. Rather than maintain an array or stack of values within ourprogram, let's instead recursively dive to the appropriate call stack entry and then display the information associated witheach call stack entry as we come back up. A program demonstrating this approach is shown below:

MC Press Online

http://www.mcpressonline.com Powered by Joomla! Generated: 28 August, 2008, 23:46


2/9

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

MC Press Online



3/9

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

MC Press Online



4/9

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;

MC Press Online



5/9

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

MC Press Online



6/9

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

MC Press Online



7/9

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;

MC Press Online



8/9

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 thesevariables into a new procedure, Display Call Stack Entry (DisplayCSE). We also remove the DoFor loop and associatedcontrol field Count found in the original program. Instead, we will use the NbrEnt field to control how deeply werecursively dive into the returned list of call stack entries. Where we previously entered into the DoFor loop, we nowsimply call DisplayCSE, passing a pointer to the first call stack entry. This is done with the statement

MC Press Online



9/9

'DisplayCSE(RcvVarPtr + RcvVar.QWVEO);'. Next, we define the procedure DisplayCSE. This procedure accepts one parameter: a pointer to the current call stackentry. 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 beprocessed ('DisplayCSE(EntInfPtr + EntryInfo.QWVEL);'). When NbrEnt becomes 0, the program has read through theappropriate number of call stack entries, and DisplayCSE then continues processing the current entry. This displayprocessing is the same as that used in the original program. The one difference is that instead of calculating the addressof the next call stack entry, DisplayCSE simply returns to the previous instance of DisplayCSE at the bottom of the DoForloop.That instance processes its current call stack entry and again returns to its caller. This continues until all call stackentries 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 greatlysimplify the development of certain types of applications. If the call stack entries had been of fixed length, I would haveused other techniques, but when working "backward" through variable-length entries, recursion can certainly simplify theapplication program. If you have other API questions, send them to me at [email protected]. I'll see what I can do about answeringyour burning questions in future columns.

MC Press Online


Documents

The API Corner Retrieving Information, Continued