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:
|
1 |
Receiver variable |
Output |
Char(*) |
|
2 |
Length of receiver variable |
Input |
Binary(4) |
|
3 |
List information |
Output |
Char(80) |
|
4 |
Number of records to return |
Input |
Binary(4) |
|
5 |
Sort information |
Input |
Char(*) |
|
6 |
Object and library name |
Input |
Char(20) |
|
7 |
Object type |
Input |
Char(10) |
|
8 |
Authority control |
Input |
Char(*) |
|
9 |
Selection control |
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 |
I/O |
Char(*) |
Optional Parameter Group 1:
|
13 |
Job identification information |
Input |
Char(*) |
|
14 |
Format of job identification information |
Input |
Char(8) |
Optional Parameter Group 2:
|
15 |
Auxiliary storage pool (ASP) control |
Input |
Char(*) |
Default Public Authority: *USE
Threadsafe: No
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 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 1 4B 0
D* Total Records
D QGYRRTN02 5 8B 0
D* Records Returned
D QGYRH07 9 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
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
•· Information Complete (QGYIC07) is similar to QUSIS: what the status is of the information in the Receiver variable
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).
•· 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.
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.
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
d/copy qsysinc/qrpglesrc,qusgen
dChkSrvPgmMod pr
dOpnLstDone pr n
dSndErrMsg pr
dSetup pr
dOpnListObj pr extpgm('QGYOLOBJ')
d RcvVar 1 options(*varsize)
d LenRcvVar 10i 0 const
d ListInfo 80
d NbrRcdRqs 10i 0 const
d SortInfo const likeds(QGYOSI)
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 8 const options(*nopass)
d ASPCtl 65535 const options(*nopass :*varsize)
dGetNextEnt pr extpgm('QGYGTLE')
d RcvVar 1 options(*varsize)
d LenRcvVar 10i 0 const
d RqsHandle 4 const
d ListInfo 80
d NbrRcdRqs 10i 0 const
d StrRcd 10i 0 const
d QUSEC likeds(QUSEC)
dCloseList pr extpgm('QGYCLST')
d RqsHandle 4 const
d QUSEC likeds(QUSEC)
dGenHdr ds likeds(QUSH0100)
d based(ModLstSpcPtr)
dRcvVarE ds based(RcvVarEPtr)
d likeds(QGYORV01)
dSelCtl ds qualified
d Ctl likeds(QGYOSC)
d Status 1
dObjLibNam ds
d 10 inz('*ALL')
d ObjLib 10
dErrCde ds qualified
d Hdr likeds(QUSEC)
d MsgDta 128
dRcvVar s 4096
dRcvVarEPtr s *
dModLstSpcPtr s *
dCount s 10i 0
dNbrMods s 10i 0
dHits s 10i 0
dWait s 1
dModLstSpc c 'MODLUSRSPCQTEMP'
/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();
// 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;
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;
return;
/end-free
*****************************************************************
pChkSrvPgmMod b
dChkSrvPgmMod pi
dGetSrvPgmInfo pr extpgm('QBNLSPGM')
d QUsrSpcNam 20 const
d Format 8 const
d QSrvPgmNam 20 const
d QUSEC likeds(QUSEC)
d/copy qsysinc/qrpglesrc,qbnlspgm
dSrvPgmE ds likeds(QBNL010000)
d based(SrvPgmEPtr)
dSrvPgmEPtr s *
/free
// Get the list of bound *MODULEs for current *SRVPGM
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;
endfor;
else;
dsply ('Unable to access *SRVPGMs.');
endif;
/end-free
pChkSrvPgmMod e
*****************************************************************
pOpnLstDone b
dOpnLstDone pi n
/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;
when ErrCde.Hdr.QUSEI = 'GUI0006';
CloseList( QGYRH07 :QUSEC);
return *on;
other;
SndErrMsg();
endsl;
endif;
/end-free
pOpnLstDone e
*****************************************************************
pSetUp b
dSetUp pi
dCrtUsrSpc pr extpgm('QUSCRTUS')
d SpcName 20 const
d SpcAttr 10 const
d SpcSiz 10i 0 const
d SpcVal 1 const
d SpcAut 10 const
d SpcTxt 50 const
d SpcRpl 10 const options(*nopass)
d QUSEC likeds(QUSEC) options(*nopass)
d SpcDmn 10 const options(*nopass)
d SpcTfrSiz 10i 0 const options(*nopass)
d SpcSpcAln 1 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
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
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);
/end-free
pSetUp e
****************************************************************
pSndErrMsg b
dSndErrMsg pi
dSndMsg pr extpgm('QSYS/QMHSNDPM')
d MsgID 7 const
d QualMsgF 20 const
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 4
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)
dQualMsgF ds qualified
d MsgFile 10
d MsgFLib 10 inz('QSYS')
dMsgKey s 4
/free
if %subst(ErrCde.Hdr.QUSEI :1 :3) = 'GUI';
QualMsgF.MsgFile = 'QGUIMSG';
else;
QualMsgF.MsgFile = 'QCPFMSG';
endif;
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 e
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
Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at
MC Press books written by Bruce Vining available now on the MC Press Bookstore.
 |
||
 |
|
IBM System i APIs at Work Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale
|
More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.
TRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now! Request Now.
Forms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.
Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:
Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.
IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn:
LATEST COMMENTS
MC Press Online