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