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 This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll see what I can do about answering your burning questions in future columns.