MC Press Online

The API Corner: Retrieving Information, Continued

Contributed by Bruce Vining Wednesday, 21 May 2008 Last 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 to accomplish this.

By Bruce Vining

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?

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:

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:46

MC Press Online

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

options(*varsize)

d LenRcvVar

10i 0 const

d FmtRcvVar

const

d JobID

65535

const options(*varsize)

d FmtJobID

const

d ErrCde

likeds(QUSEC)

dDisplayCSE

pr

d EntInfPtr

* value

/copy qsysinc/qrpglesrc,qwvrcstk

/copy qsysinc/qrpglesrc,qwcattr

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

MC Press Online

dRcvVar

ds

likeds(QWVK0100)

based(RcvVarPtr)

dProcName

256

based(ProcNamePtr)

dNbrEnt

10i 0

dCurProcName

52

dPrvPgmName

10

dWait

/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

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

MC Press Online

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;

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:46

MC Press Online

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

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:46

MC Press Online

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

dDisplayCSE

pi

d EntInfPtr
http://www.mcpressonline.com

* value
Powered by Joomla! Generated: 28 August, 2008, 23:46

MC Press Online

dEntryInfo

ds

likeds(QWVCSTKE)

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;

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:46

MC Press Online

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

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
http://www.mcpressonline.com Powered by Joomla! Generated: 28 August, 2008, 23:46

MC Press Online

'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: deallocating 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 bvining@brucevining.com. I'll see what I can do about answering your burning questions in future columns.

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:46