Escolar Documentos
Profissional Documentos
Cultura Documentos
This is the second of two articles discussing the basics of working with API-related data.
By Bruce Vining
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.
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
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
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)
/copy qsysinc/qrpglesrc,qwvrcstk
/copy qsysinc/qrpglesrc,qwcattr
/copy qsysinc/qrpglesrc,qusec
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
dRcvVar
ds
likeds(QWVK0100)
based(RcvVarPtr)
dEntryInfo
ds
likeds(QWVCSTKE)
based(EntInfPtr)
dProcName
256
based(ProcNamePtr)
dNbrEnt
10i 0
dCount
10i 0
dCurProcName
52
dPrvPgmName
10
dWait
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
/free
if %parms = 0;
NbrEnt = *hival;
else;
NbrEnt = NbrEntInput;
endif;
QUSBPRV = 0;
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
QWCF0100 = *loval;
QWCJN02 = '*';
QWCUN = *blanks;
// User name
QWCJNBR00 = *blanks;
// Job number
QWCIJID = *blanks;
// Internal job ID
QWCTI00 = 1;
select;
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
// Info OK
*inlr = *on;
return;
other;
*inlr = *on;
return;
endsl;
RcvVarPtr = %alloc(QWVBAVL);
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
select;
// Info OK
*inlr = *on;
return;
other;
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
*inlr = *on;
return;
endsl;
NbrEnt = RcvVar.QWVERTN;
endif;
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
PrvPgmName = EntryInfo.QWVPGMN;
endif;
if EntryInfo.QWVPD > 0;
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
else;
CurProcName = *blanks;
endif;
dsply CurProcName;
else;
endif;
EntInfPtr += EntryInfo.QWVEL;
endfor;
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
dealloc RcvVarPtr;
dsply 'End of call stack list.' ' ' Wait; // Wait for the operator
*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.
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
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.
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
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).
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
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 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:45
MC Press Online
http://www.mcpressonline.com
Powered by Joomla!