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.
LATEST COMMENTS
MC Press Online