Today, you'll learn about the QBNLPGMI API.
By Bruce Vining
This article is the fifth in a series that discusses how to find all *PGMs and *SRVPGMs that have a specific *MODULE bound into them. Today, we're adding support to the MODUSAGE program for *MODULEs that are bound into *PGMs.
Before reading this article, you may find it beneficial to review the previous articles:
•· "Module, Module, Who's Got My Module?"
•· "Finding Modules in a *SRVPGM"
•· "Finding All *SRVPGMs on the System"
•· "Take Advantage of Open List APIs"
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.
The latest level of code for MODUSAGE, with new and changed source bolded, is shown below:
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
dChkPgmMod 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'); // good info 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.');
endif;
// Create the QGYOLOBJ *PGM list
OpnListObj( RcvVar :%size(RcvVar) :QGYLI :50 :QGYOSI :ObjLibNam
:'*PGM' :QGYOAC :SelCtl :0 :0 :QUSEC);
Hits = 0;
dow (QGYIC07 = 'C') or (QGYIC07 = 'P'); // good info returned?
RcvVarEPtr = %addr(RcvVar);
for Count = 1 to QGYRRTN02;
ChkPgmMod();
RcvVarEPtr += QGYRL07;
endfor;
if OpnLstDone();
leave;
endif;
enddo;
if QGYIC07 = 'I'; // incomplete info?
dsply ('Unable to access all *PGMs in ' + ObjLib) ' ' Wait;
else;
dsply (%char(Hits) + ' *PGM 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
*****************************************************************
pChkPgmMod b
dChkPgmMod pi
dGetPgmInfo pr extpgm('QBNLPGMI')
d QUsrSpcNam 20 const
d Format 8 const
d QPgmNam 20 const
d QUSEC likeds(QUSEC)
d/copy qsysinc/qrpglesrc,qbnlpgmi
dPgmE ds likeds(QBNL0100)
d based(PgmEPtr)
dPgmEPtr s *
/free
// Get the list of bound *MODULEs for current *PGM
GetPgmInfo( ModLstSpc :'PGML0100'
:(RcvVarE.QGYON00 + RcvVarE.QGYOL03) :ErrCde);
select;
when ErrCde.Hdr.QUSBAVL = 0;
when ErrCde.Hdr.QUSEI = 'CPF5CF5'; // Not an ILE *PGM
return;
other;
SndErrMsg();
endsl;
if (GenHdr.QUSIS = 'C');
PgmEPtr = ModLstSpcPtr + GenHdr.QUSOLD;
for NbrMods = 1 to GenHdr.QUSNBRLE;
if PgmE.QBNBMN = ModNam;
dsply ('*PGM: ' + %trimr(PgmE.QBNPGMLN) +
'/' + PgmE.QBNPGMN00);
Hits += 1;
leave;
endif;
PgmEPtr += GenHdr.QUSSEE;
endfor;
else;
dsply ('Unable to access *PGMs.');
endif;
/end-free
pChkPgmMod 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
As you can see, we didn't have to change very much of MODUSAGE in order to start searching *PGMs in addition to *SRVPGMs.
In the main procedure of MODUSAGE, we made one minor change to the existing support for *SRVPGMs: removing the Wait parameter from the DSPLY of the number of *SRVPGMs found containing the module. This was done so that you don't need to use the Enter key to start the *PGM analysis.
The major change in the main procedure was duplicating the logic associated with *SRVPGMs and then making three changes to this logic:
•· The seventh parameter passed to the QGYOLOBJ API now calls for *PGM objects to be returned rather than *SRVPGMs.
•· We reset the value of the Hits variable to 0 so we could provide a count of the number of *PGMs found with the module bound in.
•· Each returned list entry now calls the procedure Check Program Module, ChkPgmMod, rather than Check Service Program Module, ChkSrvPgmMod.
In addition, there's a minor change made to the text of the DSPLYed messages.
The other change made to MODUSAGE was in adding the new procedure ChkPgmMod in order to analyze the *PGMs returned by the QGYOLOBJ API. As we did in the main procedure, we essentially duplicated the *SRVPGM logic of ChkSrvPgmMod and then customized the code for a *PGM environment.
The "routine" customization involved...
•· Prototyping the List ILE Program Information (QBNLPGMI) API rather than List Service Program Information
•· Copying in the QSYSINC-provided definitions for QBNLPGMI rather than those for QBNLSPGM
•· Defining a Program Entry structure, PgmE, to represent the module information returned by the QBNLPGMI API. PgmE is defined likeds(QBNL0100) and based on the pointer variable PgmEPtr.
•· Calling the QBNLPGMI API (prototyped as GetPgmInfo), requesting the list of modules (format PGML0100) bound into the current *PGM list entry returned by QGYOLOBJ. As the parameters for QBNLPGMI are essentially the same as those for QBNLSPGM, we won't be reviewing these parameters. If you are interested in such a review, the API documentation can be found here.
•· Changing the subfield names used within the FOR loop from the SrvPgmE data structure to the names used within the PgmE data structure
•· Incrementing the pointer variable PgmEPtr rather than the pointer variable SrvPgmEPtr
The only "non-routine" change in the logic used to process *PGMs is in the SELECT group that immediately follows the call to the QBNLPGMI API.
When calling the QBNLPGMI API, we are using the ErrCde error code structure rather than the QUSEC error code structure. To refresh your memory, ErrCde is the data structure that has a non-zero Bytes provided field, telling the API to return error-related information in the error code structure rather than as an escape message. As was the case where we used ErrCde when calling the Get List Entries API in the previous article, we're again using ErrCde as we anticipate that errors, which we will handle, may be returned by the API.
The "error" is related to the *PGM that we pass to QBNLPGMI. The List ILE Program Information API only supports ILE *PGMs, while the Open List of Objects API returns any and all *PGMs that meet the selection criteria. As the QGYOLOBJ selection criteria does not provide for any distinction between OPM and ILE *PGM objects, we will be receiving list entries for all *PGM types (ILE, OPM, EPM, etc.) and, in turn, calling QBNLPGMI, asking for *MODULE information on these *PGMs. QBNLPGMI will return the error "CPF5CF5 - &1 in library &2 not bound program" if a non-ILE program is passed to it.
So after calling the QBNLPGMI API, we have a SELECT group that...
•· Determines whether no error was encountered by the API (ErrCde.Hdr.QUSBAVL = 0) and, if so, allows the program flow to continue to the subsequent list processing of ChkPgmMod
•· If an error is found, determines if the error is CPF5CF5 and, if so, RETURN to the main procedure so that the next *PGM list entry can be processed
•· For any other error situation, sends the error message from QBNLPGMI as an escape message using the SndErrMsg procedure
As was the case when handling the "error" with Get List Entries in the previous article, we can avoid having the CPF5CF5 error returned to us by QBNLPGMI. One approach would be to use the Retrieve Program Information (QCLRPGMI) API, which is documented here. This API returns, among many other attributes of a *PGM, the type of program so that we can determine whether the program returned by QGYOLOBJ is OPM or ILE. We could then conditionally call QBNLPGMI based on this information. As implemented, MODUSAGE simply calls QBNLPGMI and handles the error as opposed to calling QCLRPGMI and then calling QBNLPGMI. Either approach, plus others that exist, will work.
This concludes our introduction to List and Open List APIs. We now have a program that can return all occurrences of a bound *MODULE, within either *PGMs or *SRVPGMs, on a system. This program can be quite useful when making changes to a *MODULE and needing to determine what *PGMs and *SRVPGMs may need to be recreated. More importantly, we also have a model that can be used to effectively utilize other List and Open List APIs on the system. And there are many of these types of APIs!
Before we move off this topic, though, there will be one additional article that reviews some of the further options available to you. In the next article, we'll provide a command interface to MODUSAGE that includes library qualification of the *MODULE name as well as some application house-cleaning in the case of unexpected errors being encountered. But most importantly, we'll demonstrate how to potentially reduce the wall clock time required for MODUSAGE to run. On this last point, we'll look specifically at how to concurrently create a list of *PGMs and a list of *SRVPGMs and how to perform some of the setup functions. Currently, these functions are all being done serially. Performing these functions in parallel may allow us to shorten the perceived run time of MODUSAGE.
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
|
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