The API Corner Retrieving Information, Part I

7/27/2019 The API Corner Retrieving Information, Part I

1/31

The API Corner: Retrieving Information, Part I

Contributed by Bruce ViningWednesday, 19 March 2008Last Updated Thursday, 05 June 2008

In previous columns, we discussed the basics of API error handling and data types. Today, we'll talk about accessingand using information returned by retrieve type APIs.

By Bruce Vining System APIs generally return information to you in one or more structures. One API that uses this approach, and thatyou might find handy to know about, is the Retrieve Call Stack (QWVRCSTK) API and format CSTK0100. This API andformat is shown below and documented here.

In previous columns, we discussed the basics of API error handling and data types. Today, we'll talk about accessingand using information returned by retrieve type APIs.

System APIs generally return information to you in one or more structures. One API that uses this approach, and thatyou might find handy to know about, is the Retrieve Call Stack (QWVRCSTK) API and format CSTK0100. This API andformat is shown below and documented here.

Retrieve Call Stack (QWVRCSTK) API

Required Parameter Group: 1

MC Press Online

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


2/31

Receiver variable

Output

Char(*)

2

Length of receiver variable

Input

Binary(4)

3

Format of receiver information

Input

MC Press Online



3/31

Char(8)

4

Job identification information

Input

Char(*)

5

Format of job identification information

Input

Char(8)

MC Press Online



4/31

6

Error code

I/O

Char(*)

Default Public Authority: *USE

Threadsafe: Yes

Format CSTK0100: Return OPM and ILE Call Stack Entries

Offset

Type

MC Press Online



5/31

Field

Dec Hex

0 0

BINARY(4)

Bytes returned

4 4

BINARY(4)

MC Press Online



6/31

Bytes available

8 8

BINARY(4)

Number of call stack entries for thread

12 C

BINARY(4)

Offset to call stack entry information 16

MC Press Online



7/31

10

BINARY(4)

Number of call stack entries returned

20 14

CHAR(8)

Returned thread identifier

28 1C

CHAR(1)

MC Press Online



8/31

Information status

29 1D

CHAR(*)

Reserved

These fields repeat, in the order listed, for the number of call stack entries.

BINARY(4)

Length of this call stack entry

BINARY(4)

MC Press Online



9/31

Displacement to statement identifiers

BINARY(4)

Number of statement identifiers

BINARY(4)

Displacement to the procedure name

BINARY(4)

Length of procedure name

BINARY(4)

MC Press Online



10/31

Request level

CHAR(10)

Program name

CHAR(10)

Program library name

BINARY(4)

MI instruction number

CHAR(10)

MC Press Online



11/31

Module name

CHAR(10)

Module library name

CHAR(1)

Control boundary

CHAR(3)

Reserved

BINARY(4), UNSIGNED

Activation group number

MC Press Online



12/31

CHAR(10)

Activation group name

CHAR(2)

Reserved

CHAR(10)

Program ASP name

CHAR(10)

Program library ASP name

MC Press Online



13/31

BINARY(4)

Program ASP number

BINARY(4)

Program library ASP number

BINARY(8), UNSIGNED

Activation group number long

CHAR(*)

Reserved

MC Press Online



14/31

ARRAY(*) of CHAR(10)

Statement identifiers

CHAR(*)

Procedure name

This API, which returns information about all programs and procedures active in a thread's call stack, requires sixparameters. The Receiver variable is where the API returns the information, and, as we learned in "Understanding APIData Types," the Char(*) definition tells us it's a variable-length parameter. The Length of receiver variable is a 4-byte

integer used to tell the API how much storage we've allocated for the Receiver variable parameter. Format of receiverinformation is an 8-byte character value that defines the type of information we want the API to return in the Receivervariable parameter. We will be using format CSTK0100, which instructs the API to only return information on OPM andILE programs (*PGM) and service programs (*SRVPGM) and to return the information in the form shown immediatelyabove. Job identification information is a variable-length input structure where you identify the job thread you want callstack information about, and Format of job identification information is an 8-byte character value defining the format ofthe Job identification parameter. We will be using format JIDF0100, which is shown here:

Format JIDF0100: Identify Job and Thread of Interest

MC Press Online



15/31

Offset

Type

Field

Dec Hex

0 0

CHAR(10)

Job name 10

MC Press Online



16/31

A

CHAR(10)

User name

20 14

CHAR(6)

Job number

26 1A

CHAR(16)

MC Press Online



17/31

Internal job identifier

42 2A

CHAR(2)

Reserved

44 2C

BINARY(4)

Thread indicator 48

MC Press Online



18/31

30

CHAR(8)

Thread identifier

The sixth parameter, Error code, is a variable-length structure that was discussed in "System API Basics."

The structures returned by this API are more complex than what you will find with many APIs, but they do include variousfeatures that I want to discuss. Below is a program that accepts one parameter: the number of call stack entries you wantinformation about, starting with the procedure currently running. The program then displays the procedure and programnames found.

dCallStack pr extpgm('CALLSTACK')

d NbrEntInput 15p 5 const

MC Press Online



19/31

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

MC Press Online



20/31

/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

MC Press Online



21/31

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;

MC Press Online



22/31

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

MC Press Online



23/31

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

MC Press Online



24/31

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;

MC Press Online



25/31

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

MC Press Online



26/31

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;

MC Press Online



27/31

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

MC Press Online



28/31

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

While the program is shown in its entirety, today we will only look at this program up through the initial call to theQWVRCSTK API. Because of space considerations, we will defer discussion of the remainder of the program to the nextarticle.

MC Press Online



29/31

As you are quite familiar with RPG, I won't go into the details of the program other than to explain how they relate to APIusage or to explain an implementation decision. The first decision is the declaration of the NbrEntInput parameter as apacked decimal 15,5. This was done for ease of use in testing the program from the command line. If this parameter isnot provided, the program will default to showing all call stack entries.

The program uses several include files that are provided with i5/OS in the QSYSINC library. The QWVRCSTK include fileprovides the definitions for format CSTK0100, QWCATTR the definition for format JIDF0100, and QUSEC the definitions

for the QUSEC Error code structure. In case you're wondering how I knew to use these particular include files, theconvention is that include file names are the same as the name of the *PGM or *SRVPGM implementing the API. As I'musing the QWVRCSTK API, the associated file member in QSYSINC/QRPGLESRC is QWVRCSTK. While I might expectmember QWVRCSTK to also define format JIDF0100, I find in looking at the QWVRCSTK include that there is acomment saying that the job identification structures are found in include QWCATTR, so I /copy that include also. And asdiscussed in "System API Basics," the standard API error code structures are found in QUSEC. If you don't haveQSYSINC on your system, you can install it with option 13 of i5/OS.

From an API usage point of view, the first item the program takes care of is how API error messages are to be returned.In our case, we are setting the Bytes provided field (QUSBPRV) of the Error code structure (QUSEC) to 0. This tells theAPI that we want serious errors to be returned as escape messages.

Next, the program initializes the Job identification data structure associated with format JIDF0100. In looking at sourcemember QWCATTR, we can see that the name of the provided data structure is QWCF0100. An important aspect tokeep in mind is how we initialize this structure. Imbedded within format JIDF0100 is a reserved field (QWCERVED06)that must be set to x'00's. When using API include files, never reference a reserved field by name. IBM reserves the rightto start using any reserved field in a future release and, at that time, to change the reserved field's name to somethingmore meaningful. This type of change by IBM would cause a compile failure if you had a statement in your applicationprogram such as 'QWCERVED06 = *loval;' and you needed to compile the application on that future release, even forsome totally unrelated reason. You can avoid this exposure by initializing the entire structure to the required value andthen setting the specific fields to indicate the function you want performed. In our case, we initialize QWCF0100 to x'00'sand then set the other subfields (Job name QWCJN02, Job user name QWCUN, etc.) to indicate we want the call stackfor the current job and thread.

MC Press Online



30/31

At this point, the program calls the QWVRCSTK API. One structure being passed, QWCF0100, was discussed in theprevious paragraph and identifies the job and thread we want call stack information about. The second structure,QWVK0100, is the IBM-provided data structure defining the fixed location fields of format CSTK0100, Bytes returned(QWVBRTN) through Information status (QWVIS).

Many i5/OS APIs return a receiver variable that contains only fixed-length fields and a fixed number of fields. TheRetrieve Member Description API, QUSRMBRD, with format MBRD0100, introduced in "Understanding API Data Types,"is such an API. Other APIs, such as QWVRCSTK, can return both a fixed amount of data (data structure QWVK0100)and a variable amount of data. In the case of QWVRCSTK, this variable amount of data associated with formatCSTK0100 is defined by the data structure QWVCSTKE and the subfields Entry length (QWVEL) through Activationgroup number long (QWVAGNL). If you review Format_CSTK0100, you will see that the fields of QWVCSTKE aredocumented in the Offset section as not being at a fixed location within the Receiver variable and that the number ofreturned occurrences of QWVCSTKE is dependent on the number of call stack entries found. This is an indication that

you will most likely find multiple data structures defined in the QSYSINC include file: one for the single occurrencestructure, one or more for the multiple occurrence structure. To further muddy the waters, QWVCSTKE also returns avariable amount of data with each occurrence. A procedure name, for instance, can be from 1 to 256 bytes in length or,in the case of an OPM program, there may be no procedure name at all.

So how do we figure out how large a Receiver variable needs to be so that we get all of the call stack information? Wedon't know how many call stack entries there might be, and we don't know how big each call stack entry might be. We

could just guess a large number of entries and multiply by the maximum size of an entry that might be returned to obtaina Receiver variable size, but there is a better way.

Most retrieve type APIs that return information to you include at least two fields in the fixed-size portion of the Receivervariable. These two fields are Bytes returned and Bytes available. Bytes returned tells you how many bytes of data the

API actually returned to the Receiver variable. Bytes available tells you how many bytes of data could have beenreturned if you'd had a sufficiently large Receiver variable.

What we're doing with the initial call to QWVRCSTK is passing in the data structure QWVK0100 so that we can get backthe Bytes available field QWVBAVL (along with some other very useful information). What we will do with QWVBAVL,and some of the other information found in QWVK0100, you'll see in the next article (or, if you're impatient, you can lookat the sample program and see for yourself what we'll be doing!).

MC Press Online



31/31

Meanwhile, if you have other API questions, send them to me at [email protected]. I'll see what I can do aboutanswering your burning questions in future columns.

MC Press Online

The API Corner Retrieving Information, Part I

Documents

Transcript of The API Corner Retrieving Information, Part I