Beruflich Dokumente
Kultur Dokumente
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
MC Press Online
Receiver variable
Output
Char(*)
Input
Binary(4)
List information
Output
http://www.mcpressonline.com Powered by Joomla! Generated: 28 August, 2008, 23:51
MC Press Online
Char(80)
Input
Binary(4)
Sort information
Input
Char(*)
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!
MC Press Online
Input
Char(*)
10
Input
Binary(4)
11
Input
Array(*) of Binary(4)
12
Error code
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
I/O
Char(*)
13
Input
Char(*)
14
Input
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
Char(8)
15
Input
Char(*)
Threadsafe: No
http://www.mcpressonline.com
Powered by Joomla!
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*
D QGYTR07
4B 0
D*
Total Records
D QGYRRTN02
8B 0
D*
Records Returned
http://www.mcpressonline.com
Powered by Joomla!
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*
...
D QGYFBR01
37
40B 0
D*
http://www.mcpressonline.com
Powered by Joomla!
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!
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!
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!
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!
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!
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
d JobIDFmt
const options(*nopass)
d ASPCtl
65535
dGetNextEnt
pr
extpgm('QGYGTLE')
d RcvVar
options(*varsize)
http://www.mcpressonline.com
Powered by Joomla!
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!
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!
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!
MC Press Online
/free
if %parms < 2;
*inlr = *on;
return;
endif;
Setup();
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
RcvVarEPtr = %addr(RcvVar);
ChkSrvPgmMod();
RcvVarEPtr += QGYRL07;
endfor;
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
if OpnLstDone();
leave;
endif;
enddo;
if QGYIC07 = 'I';
// incomplete info?
dsply ('Unable to access all *SRVPGMs in ' + ObjLib) ' ' Wait;
else;
endif;
*inlr = *on;
http://www.mcpressonline.com
Powered by Joomla!
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!
MC Press Online
d QSrvPgmNam
20
const
d QUSEC
likeds(QUSEC)
d/copy qsysinc/qrpglesrc,qbnlspgm
dSrvPgmE
ds
likeds(QBNL010000)
based(SrvPgmEPtr)
dSrvPgmEPtr
/free
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
if (GenHdr.QUSIS = 'C');
if SrvPgmE.QBNBMN00 = ModNam;
'/' + SrvPgmE.QBNSN00);
Hits += 1;
leave;
endif;
SrvPgmEPtr += GenHdr.QUSSEE;
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
endfor;
else;
endif;
/end-free
pChkSrvPgmMod
*****************************************************************
pOpnLstDone
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
dOpnLstDone
pi
/free
return *on;
else;
select;
when ErrCde.Hdr.QUSBAVL = 0;
return *off;
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
return *on;
other;
SndErrMsg();
endsl;
endif;
/end-free
pOpnLstDone
*****************************************************************
http://www.mcpressonline.com
Powered by Joomla!
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!
MC Press Online
d QUSEC
likeds(QUSEC) options(*nopass)
d SpcDmn
10
const options(*nopass)
d SpcTfrSiz
d SpcSpcAln
const options(*nopass)
dGetUsrSpcPtr
pr
extpgm('QUSPTRUS')
d SpcName
20
const
d UsrSpcPtr
d QUSEC
likeds(QUSEC) options(*nopass)
/free
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
QUSBPRV = 0;
ErrCde.Hdr.QUSBPRV = %size(ErrCde);
ObjLib = SrchLib;
QGYNBRK = 0;
QGYOAC = *loval;
QGYFL04 = %size(QGYOAC);
SelCtl.Ctl = *loval;
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
SelCtl.Ctl.QGYSOOS = 0;
SelCtl.Ctl.QGYSO01 =
(%addr(SelCtl) - %addr(SelCtl.Status));
SelCtl.Ctl.QGYNBRS = 1;
SelCtl.Status = '*';
CrtUsrSpc( ModLstSpc :' ' :1 :x'00' :'*CHANGE' :' ' :'*YES' :QUSEC);
http://www.mcpressonline.com
Powered by Joomla!
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!
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
d CSEQual
20
const options(*nopass)
d DSPWaitTime
d CSEType
10
const options(*nopass)
d CCSID
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
dQualMsgF
ds
qualified
d MsgFile
10
d MsgFLib
10
inz('QSYS')
dMsgKey
/free
QualMsgF.MsgFile = 'QGUIMSG';
else;
QualMsgF.MsgFile = 'QCPFMSG';
endif;
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
:MsgKey :QUSEC);
else;
// No msg data
endif;
/end-free
pSndErrMsg
http://www.mcpressonline.com
Powered by Joomla!
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!