Sie sind auf Seite 1von 37

MC Press Online

The API Corner: Finding All *SRVPGMs on the System


Contributed by Bruce Vining Wednesday, 20 August 2008 Last Updated Monday, 18 August 2008

Do you know how to use the Open List of Objects (QGYOLOBJ) API?

By Bruce Vining

This article is the third in a series that discusses how to find all *PGMs and *SRVPGMs that have a specific *MODULE bound into them. Before reading this article, you may find it beneficial to review the two prior articles, "Module, Module, Who's Got My Module?" and "Finding Modules in a *SRVPGM." While the stated intent is to find all uses of a given module, the actual purpose of this series of articles is to introduce the concepts and proper use of two types of system APIs: List and Open List.

Do you know how to use the Open List of Objects (QGYOLOBJ) API?

This article is the third in a series that discusses how to find all *PGMs and *SRVPGMs that have a specific *MODULE bound into them. Before reading this article, you may find it beneficial to review the two prior articles, "Module, Module, Who's Got My Module?" and "Finding Modules in a *SRVPGM." While the stated intent is to find all uses of a given module, the actual purpose of this series of articles is to introduce the concepts and proper use of two types of system APIs: List and Open List.

When we left off in the previous article, we had determined that we could not use the List Service Program Information (QBNLSPGM) API by itself. The limitation that all module information associated with each call of the API had to fit within 16MB of list space was simply too limiting when trying to analyze libraries or sets of libraries. Today, we'll look at the Open List of Objects (QGYOLOBJ) API, which we will use as a front-end to the QBNLSPGM API. The QGYOLOBJ API documentation can be found here, and the parameter list is shown below. Open List of Objects (QGYOLOBJ) API

Required Parameter Group:


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

MC Press Online

Receiver variable

Output

Char(*)

Length of receiver variable

Input

Binary(4)

List information

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

MC Press Online

Char(80)

Number of records to return

Input

Binary(4)

Sort information

Input

Char(*)

Object and library name

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

MC Press Online

Char(20)

Object type

Input

Char(10)

Authority control

Input

Char(*)

Selection control

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

Input

Char(*)

10

Number of keyed fields to return

Input

Binary(4)

11

Key of fields to return

Input

Array(*) of Binary(4)

12

Error code

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

I/O

Char(*)

Optional Parameter Group 1:

13

Job identification information

Input

Char(*)

14

Format of job identification information

Input

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

Char(8)

Optional Parameter Group 2:

15

Auxiliary storage pool (ASP) control

Input

Char(*)

Default Public Authority: *USE

Threadsafe: No

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

The QGYOLOBJ API gives us the ability to generate a list of object names and a customizable set of object attributes (though we won't be using this particular capability), based on various selection criteria. An open list type API, such as QGYOLOBJ, has several advantages over a list type API, such as QBNLSPGM.

One advantage is pure size. A list API--if we ignore API continuation handles, which I introduced in the previous article-is limited to returning information that will fit within 16MB, but an open list API can return lists of information that are gigabytes in size. In the case of how we will be using this API, each *SRVPGM list entry will use 36 bytes, and with just a "little" 1GB list, we can then safely work with up to 27 million or so *SRVPGMs per call of MODUSAGE. As we would also support each of these *SRVPGMs then having over 4,000 modules bound to it (based on our review of QBNLSPGM in the last article), I believe this design should be sufficiently robust to adequately support most i environments.

Another advantage is in the area of perceived processing time. With a list API, the API does not return control to the application until the entire list has been stored in the *USRSPC. With open list APIs, you can request that the API return to the application as soon as x list entries are available for processing. The API will then continue building the reminder of the list (entries x+1, x+2, and so on) in a separate background server job. When the application is done processing the initial x entries, it can then request the next set of entries, and (hopefully) these list entries will be immediately available for delivery to the application. This attribute can allow us to show initial results to the user much more quickly than a list API when a large number of entries will exist in the list. Generally speaking, you can think of an open list as being similar to building a subfile one page at a time while a list API requires that the entire subfile be loaded prior to displaying the first page of the subfile.

Before we go much further, I want to mention two open list considerations that may save you from some unnecessary frustration. First, prior to V5R3, the open list APIs were installed as part of option 12, Host Servers, of the operating system. If you are on an earlier release and have not previously installed option 12, do so now. Second, the support for gigabyte-size lists was an internal operating system enhancement made with V5R3. If you are on a previous release, it's time to upgrade to a current release. The APIs we use will work on releases prior to V5R3, but rather than getting the millions of list entries you might get on a current release, you may get an error message related to the list being too large.

With that brief introduction to open list APIs (there is, for those interested, more information available here), let's look at
http://www.mcpressonline.com Powered by Joomla! Generated: 28 August, 2008, 23:51

MC Press Online

QGYOLOBJ in detail.

The first parameter, Receiver variable, is where the QGYOLOBJ API will return the initial set of list entries to the application (your first subfile page if you will). The second parameter, Length of receiver variable, tells the API how much storage has been allocated for the Receiver variable parameter. This works the same as and has the same considerations as using a Receiver variable with a retrieve type API; that is, make sure the Length of receiver variable value is correctly set.

The third parameter, List information, is an output from the API and provides the application with information about the list and the contents of the Receiver variable. You can think of this parameter as being the equivalent of the generic header used by list APIs. The format of the List information is documented here, and the key parts of the QSYSINC provided include QGY, defining the List information structure, shown below.

DQGYLI

DS

D*

Qgy List Info

D QGYTR07

4B 0

D*

Total Records

D QGYRRTN02

8B 0

D*

Records Returned

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

D QGYRH07

12

D*

Request Handle

D QGYRL07

13

16B 0

D*

Record Length

D QGYIC07

17

17

D*

Info Complete

...

D QGYLSI01

31

31

D*

List Status Indicator

...

D QGYFBR01

37

40B 0

D*

First Buffer Record

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

Within the List Information data structure QGYLI are several subfields that you might recognize as having equivalent subfields in the list generic header of QBNLSPGM.

• Records Returned (QGYRRTN02) provides a function similar to QUSNBRLE of the generic header: how many records were returned for processing

•

Record Length (QGYRL07) is similar to QUSSEE of the generic header: what the size is of each list entry

• variable

Information Complete (QGYIC07) is similar to QUSIS: what the status is of the information in the Receiver

When looking at list-related subfields, the only field that is really missing from the list generic header is an equivalent to QUSOLD: the offset to the list data. This field is not necessary in QGYLI as the first list entry always starts at the first byte of the Receiver variable.

There are, however, "new" fields of interest within the QGYLI data structure:

• Total Records (QGYTR07) tells us how many total records are currently available in the list, which should not be confused with QGYRRTN02, the number of records currently returned in the Receiver variable.

• Request Handle (QGYRH07) uniquely identifies the list and is used with subsequent API calls when we want to perform operations such as accessing the next set of list entries in a list or closing the list. This unique identifier is necessary because an application can have multiple lists open concurrently.

• List Status Indicator (QGYLSI01) tells us the status of the list as it's being built in a background server job (for instance, if the list is complete, QGYTR07, Total records, is a final number).

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

• First Buffer Record (QGYFBR01) identifies the relative record number, within the total list, of the first list entry currently in the Receiver variable. This, when added to QGYRRTN02 (the number of records returned in the Receiver variable), allows us to calculate the relative record number with which to start the next set of list entries to be returned to the application so that we can sequentially read the list entries. Note that you don't have to access list entries sequentially, but that is by far the most common approach.

The fourth parameter, Number of records to return, tells the API up to how many list entries should be returned in the Receiver variable. There are two special values that can also be used. The special value -1 indicates that the entire list should be built synchronously prior to returning from the API. The special value 0 indicates that the entire list is to be built asynchronously and that no records are to be returned from this call to the API. This option enables the API to return control to the application as soon as it has verified that there are no severe errors in our request. We will not be using the special value of 0 initially, but this option does introduce some interesting performance considerations. If the application has significant processing that could be done prior to receiving any open list entries, such as opening files or creating objects (for instance, our *USRSPC for QBNLSPGM), then the application can request that the entire open list be built asynchronously, and the application can be performing this "other" processing concurrent to the list being built.

The fifth parameter, Sort information, allows you to have the list entries returned in a sorted order. MODUSAGE does not use this capability. As a consideration when using open list APIs, be aware that asking for a sorted list essentially turns off the capability of an open list API to return to you a subset of the list while building the remainder of the list in a background job. As the API cannot sort the entries prior to creating the entire list (the last entry processed may end up being the first entry returned in the sorted list), the application will not be able to access any list entries until the entire list is available. The application doesn't have to be written in any special way for this situation; the API simply won't return any list entries to the application until the entire list has been built (and sorted).

The sixth parameter, Object and library name, tells the API what object(s) we want included in the list. Special values that can be used include *ALL for the object name. When calling QGYOLOBJ, MODUSAGE will use this *ALL special value, along with the provided SrchLib parameter to indicate what libraries should be searched for *SRVPGMs.

The seventh parameter, Object type, is simply the type of object we want included in the generated list. MODUSAGE will use the value *SRVPGM.

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

The ninth parameter, Selection control, allows us to filter the returned list based on the status of the object: damaged objects, locked objects, not authorized to objects, etc. MODUSAGE will request that all objects be returned as we have no need for the type of information that can be impacted by the various status values.

QGYOLOBJ also supports several other parameters. We won't be using these parameters today and will not be discussing them. You should feel free, though, to review the API documentation and determine what functions these other parameters provide. MODUSAGE Updated

With that introduction to QGYOLOBJ, here is an updated version of MODUSAGE, one which combines the power of QGYOLOBJ and QBNLSPGM to search, if you want, every *SRVPGM on the system in one pass. To aid your review of the program, I have bolded the new and changed lines.

Note that if you do search every *SRVPGM on the system, it might take a while. And if you're thinking of submitting the call to MODUSAGE to a *JOBQ, keep in mind that we are using the RPG DSPLY operation code to show the qualified *SRVPGM names that have the specified module bound to them. DSPLY, when run from batch, goes to the QSYSOPR message queue, so you may want to make sure you are on very good terms with the system operator or, probably wiser, change MODUSAGE to output the selected *SRVPGM names to a file rather than a message queue. The system operator, in addition to seeing the DSPLY output, will also need to respond to any DSPLYs sent with the Wait parameter.

Also note that a very important change was made in the ChkSrvPgmMod procedure in terms of the third parameter used when calling the QBNLSPGM (prototyped as GetSrvPgmInfo) API. It would be fairly easy to overlook this small, but critical, change in what *SRVPGMs are to be included within the generated list.

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

h dftactgrp(*no)

dModUsage

pr

d ModNam

10

const

d SrchLib

10

const

dModUsage

pi

d ModNam

10

const

d SrchLib

10

const

d/copy qsysinc/qrpglesrc,qgyolobj

d/copy qsysinc/qrpglesrc,qgy

d/copy qsysinc/qrpglesrc,qusec

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

d/copy qsysinc/qrpglesrc,qusgen

dChkSrvPgmMod

pr

dOpnLstDone

pr

dSndErrMsg

pr

dSetup

pr

dOpnListObj

pr

extpgm('QGYOLOBJ')

d RcvVar

options(*varsize)

d LenRcvVar

10i 0 const

d ListInfo

80

d NbrRcdRqs

10i 0 const

d SortInfo

const likeds(QGYOSI)

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

d QualObjNam

20

const

d ObjType

10

const

d AuthCtl

const likeds(QGYOAC)

d SelCtl

const likeds(SelCtl)

d NbrKeys

10i 0 const

d KeysToRtn

10i 0 const

d QUSEC

likeds(QUSEC)

d JobID

65535

const options(*nopass :*varsize)

d JobIDFmt

const options(*nopass)

d ASPCtl

65535

const options(*nopass :*varsize)

dGetNextEnt

pr

extpgm('QGYGTLE')

d RcvVar

options(*varsize)

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

d LenRcvVar

10i 0 const

d RqsHandle

const

d ListInfo

80

d NbrRcdRqs

10i 0 const

d StrRcd

10i 0 const

d QUSEC

likeds(QUSEC)

dCloseList

pr

extpgm('QGYCLST')

d RqsHandle

const

d QUSEC

likeds(QUSEC)

dGenHdr

ds

likeds(QUSH0100)

based(ModLstSpcPtr)

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

dRcvVarE

ds

based(RcvVarEPtr)

likeds(QGYORV01)

dSelCtl

ds

qualified

d Ctl

likeds(QGYOSC)

d Status

dObjLibNam

ds

10

inz('*ALL')

d ObjLib

10

dErrCde

ds

qualified

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

d Hdr

likeds(QUSEC)

d MsgDta

128

dRcvVar

4096

dRcvVarEPtr

dModLstSpcPtr

dCount

10i 0

dNbrMods

10i 0

dHits

10i 0

dWait

dModLstSpc

'MODLUSRSPCQTEMP'

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

/free

// check that the required parameters were passed

if %parms < 2;

dsply 'There are two required parameters:';

dsply '1. The module you are searching for';

dsply '2. The library to be searched in';

dsply 'The program did not run.' ' ' Wait;

*inlr = *on;

return;

endif;

Setup();

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

// Create the QGYOLOBJ *SRVPGM list

OpnListObj( RcvVar :%size(RcvVar) :QGYLI :50 :QGYOSI :ObjLibNam

:'*SRVPGM' :QGYOAC :SelCtl :0 :0 :QUSEC);

dow (QGYIC07 = 'C') or (QGYIC07 = 'P'); // information returned?

RcvVarEPtr = %addr(RcvVar);

for Count = 1 to QGYRRTN02;

ChkSrvPgmMod();

RcvVarEPtr += QGYRL07;

endfor;

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

if OpnLstDone();

leave;

endif;

enddo;

if QGYIC07 = 'I';

// incomplete info?

dsply ('Unable to access all *SRVPGMs in ' + ObjLib) ' ' Wait;

else;

dsply (%char(Hits) + ' *SRVPGM instances of ' +

%trimr(ModNam) + ' found.') ' ' Wait;

endif;

*inlr = *on;

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

return;

/end-free

*****************************************************************

pChkSrvPgmMod

dChkSrvPgmMod

pi

dGetSrvPgmInfo

pr

extpgm('QBNLSPGM')

d QUsrSpcNam

20

const

d Format

const

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

d QSrvPgmNam

20

const

d QUSEC

likeds(QUSEC)

d/copy qsysinc/qrpglesrc,qbnlspgm

dSrvPgmE

ds

likeds(QBNL010000)

based(SrvPgmEPtr)

dSrvPgmEPtr

/free

// Get the list of bound *MODULEs for current *SRVPGM

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

GetSrvPgmInfo( ModLstSpc :'SPGL0100'

:(RcvVarE.QGYON00 + RcvVarE.QGYOL03) :QUSEC);

if (GenHdr.QUSIS = 'C');

SrvPgmEPtr = ModLstSpcPtr + GenHdr.QUSOLD;

for NbrMods = 1 to GenHdr.QUSNBRLE;

if SrvPgmE.QBNBMN00 = ModNam;

dsply ('*SRVPGM: ' + %trimr(SrvPgmE.QBNSLIBN) +

'/' + SrvPgmE.QBNSN00);

Hits += 1;

leave;

endif;

SrvPgmEPtr += GenHdr.QUSSEE;

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

endfor;

else;

dsply ('Unable to access *SRVPGMs.');

endif;

/end-free

pChkSrvPgmMod

*****************************************************************

pOpnLstDone

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

dOpnLstDone

pi

/free

if ((QGYFBR01 + QGYRRTN02) > QGYTR07) and (QGYLSI01 = '2');

CloseList( QGYRH07 :QUSEC);

// close the open list

return *on;

else;

GetNextEnt( RcvVar :%size(RcvVar) :QGYRH07 :QGYLI :50

:QGYFBR01 + QGYRRTN02 :ErrCde);

select;

when ErrCde.Hdr.QUSBAVL = 0;

return *off;

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

when ErrCde.Hdr.QUSEI = 'GUI0006';

CloseList( QGYRH07 :QUSEC);

return *on;

other;

SndErrMsg();

endsl;

endif;

/end-free

pOpnLstDone

*****************************************************************

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

pSetUp

dSetUp

pi

dCrtUsrSpc

pr

extpgm('QUSCRTUS')

d SpcName

20

const

d SpcAttr

10

const

d SpcSiz

10i 0 const

d SpcVal

const

d SpcAut

10

const

d SpcTxt

50

const

d SpcRpl

10

const options(*nopass)

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

d QUSEC

likeds(QUSEC) options(*nopass)

d SpcDmn

10

const options(*nopass)

d SpcTfrSiz

10i 0 const options(*nopass)

d SpcSpcAln

const options(*nopass)

dGetUsrSpcPtr

pr

extpgm('QUSPTRUS')

d SpcName

20

const

d UsrSpcPtr

d QUSEC

likeds(QUSEC) options(*nopass)

/free

// set Error code bytes provided to send exceptions

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

QUSBPRV = 0;

// set Error code bytes provided to not send exceptions

ErrCde.Hdr.QUSBPRV = %size(ErrCde);

// Set the library to search for *SRVPGMs

ObjLib = SrchLib;

// Prime the input fields for the QGYOLOBJ API

QGYNBRK = 0;

// no need to sort API output

QGYOAC = *loval;

// init authority control struct

QGYFL04 = %size(QGYOAC);

// no authority controls needed

SelCtl.Ctl = *loval;

// init selection structure

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

SelCtl.Ctl.QGYFL05 = %size(SelCtl); // room for one status value

SelCtl.Ctl.QGYSOOS = 0;

// select based on status

SelCtl.Ctl.QGYSO01 =

// displacement to first status

(%addr(SelCtl) - %addr(SelCtl.Status));

SelCtl.Ctl.QGYNBRS = 1;

// one status value supplied

SelCtl.Status = '*';

// return all entries

// Create *USRSPC for module listing

CrtUsrSpc( ModLstSpc :' ' :1 :x'00' :'*CHANGE' :' ' :'*YES' :QUSEC);

// Get pointer to *USRSPC for module listing

GetUsrSpcPtr( ModLstSpc :ModLstSpcPtr :QUSEC);

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

/end-free

pSetUp

****************************************************************

pSndErrMsg

dSndErrMsg

pi

dSndMsg

pr

extpgm('QSYS/QMHSNDPM')

d MsgID

const

d QualMsgF

20

const

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

d MsgDta

65535

const options(*varsize)

d LenMsgDta

10i 0 const

d MsgType

10

const

d CallStackEntry

65535

const options(*varsize)

d CallStackCntr

10i 0 const

d MsgKey

d QUSEC

likeds(QUSEC)

d LenCSE

10i 0 const options(*nopass)

d CSEQual

20

const options(*nopass)

d DSPWaitTime

10i 0 const options(*nopass)

d CSEType

10

const options(*nopass)

d CCSID

10i 0 const options(*nopass)

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

dQualMsgF

ds

qualified

d MsgFile

10

d MsgFLib

10

inz('QSYS')

dMsgKey

/free

if %subst(ErrCde.Hdr.QUSEI :1 :3) = 'GUI';

QualMsgF.MsgFile = 'QGUIMSG';

else;

QualMsgF.MsgFile = 'QCPFMSG';

endif;

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

if ErrCde.Hdr.QUSBAVL > 16;

// Msg data provided

SndMsg( ErrCde.Hdr.QUSEI :QualMsgF :ErrCde.MsgDta

:(ErrCde.Hdr.QUSBAVL - 16) :'*ESCAPE' :'*PGMBDY' :1

:MsgKey :QUSEC);

else;

// No msg data

SndMsg( ErrCde.Hdr.QUSEI :QualMsgF :' ' :0

:'*ESCAPE' :'*PGMBDY' :1 :MsgKey :QUSEC);

endif;

/end-free

pSndErrMsg

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 23:51

MC Press Online

To compile MODUSAGE, use the command CRTBNDRPG MODUSAGE. To test MODUSAGE in order to find all *SRVPGMs in all user libraries that module MYMOD is bound to, use CALL MODUSAGE (MYMOD *ALLUSR).

As you might expect, we have run out of room in this issue of MC RPG Developer. There is enough of the program shown here, though, for you to use for testing, and you should certainly feel free to examine the program in order to determine how it works. We'll go over the details of the changes in the next column and hopefully confirm your review. As a warning, you will find references to two APIs--Get List Entries (QGYGTLE) documented here and Close List (QGYCLST) documented here--that we haven't discussed yet. We will be reviewing these two APIs in the next column.

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:51

Das könnte Ihnen auch gefallen