Professional Documents
Culture Documents
It's time you learned how to use the List Service Program Information (QBNLSPGM) API.
By Bruce Vining
A recent article of mine in iApplication Designer, "V6R1 CL: The Story Continues," prompted the following note from reader David S.: "I enjoyed your article on V6R1 (6.1) CL. One of the enhancements you mentioned reminded me of a question I have had for some time... [about] CL and RPG modules. If I change and recompile a module (the module may be used in multiple programs), how do I find which programs need to be updated/re-created to include the new module? Does 6.1 CL/RPG help with this?"
It's time you learned how to use the List Service Program Information (QBNLSPGM) API.
A recent article of mine in iApplication Designer, "V6R1 CL: The Story Continues," prompted the following note from reader David S.: "I enjoyed your article on V6R1 (6.1) CL. One of the enhancements you mentioned reminded me of a question I have had for some time... [about] CL and RPG modules. If I change and recompile a module (the module may be used in multiple programs), how do I find which programs need to be updated/re-created to include the new module? Does 6.1 CL/RPG help with this?"
Unfortunately, 6.1 does not help in this specific area, but David's note did inspire me to provide a practical demonstration of how to use two types of APIs. The APIs are List and Open List, areas that we haven't talked about in this column yet. For the next several columns, we'll be developing an application that will find all of the places a module has been bound
http://www.mcpressonline.com Powered by Joomla! Generated: 28 August, 2008, 23:47
MC Press Online
As we need to start somewhere, we will start with the List Service Program Information (QBNLSPGM) API, which is documented here. The QBNLSPGM API returns information about *SRVPGMs, similar to what is returned by the Display Service Program (DSPSRVPGM) command. In particular, the API can return information concerning what *MODULEs are bound into the *SRVPGM. The API takes four parameters:
Input
Char(20)
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
Format name
Input
Char(8)
Input
Char(20)
Error code
I/O
Char(*)
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
Threadsafe: No
The first parameter, Qualified user space name, is the name of the *USRSPC the API is to return information into. We will, in the program, be creating this *USRSPC using the Create User Space (QUSCRTUS) API. The first 10 bytes of the qualified name is the name of the *USRSPC object. The second 10 bytes is the name of the library containing the *USRSPC or one of the special values *CURLIB and *LIBL.
The second parameter, Format name, describes the type of information we want returned. The QBNLSPGM API supports several formats corresponding to the types of information that are available--procedure name exports, data imports, copyrights, etc. Format SPGL0100 is used to access *MODULE-related information. The format of the information returned with SPGL0100 can be found in the API documentation. The key piece of information we will be working with today is the bound module name located at decimal offset 20 of format SPGL0100. The QSYSINC/QRPGLESRC definition for format SPGL0100 is found in source member QBNLSPGM, and the first few fields of the format are shown below.
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
DQBNL010000
DS
D*
D QBNSN00
10
D*
Srvpgm Name
D QBNSLIBN
11
20
D*
D QBNBMN00
21
30
D*
D QBNBMLN00
31
40
D*
D QBNSFILN00
41
50
D*
D QBNSFLN00
51
60
D*
D QBNSFILM00
61
70
D*
Within the QSYSINC-provided data structure QBNL010000 are the fields QBNBMN00 (the Bound Module Name) and QBNSN00 (the service program name), two fields that are clearly of interest to us. Also in the data structure is a wealth of
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
additional information about the module. We won't be using these additional fields, but, for instance, field QBNSFILM00 is the Source File Member name used to create the *MODULE. If necessary, we could use this source member information to confirm that module X was indeed created from source member X, determine if module Y was really X renamed, etc. Reviewing all of the information that is available to you, even if you don't believe you need it initially, may very well suggest additional features your application may need to provide.
If you don't have the QSYSINC library installed on your system, you can install it with RSTLICPGM, specifying option 13 of the operating system. The QBNLSPGM API returns one occurrence of the QBNL010000 data structure for each *MODULE found bound into a *SRVPGM.
The third parameter, Qualified service program name, is the name of the *SRVPGM we want information about. The first 10 bytes of the qualified name can be a specific *SRVPGM name, a generic *SRVPGM name such as A*, or the special value *ALL. The second 10 bytes of the qualified name can be the name of a specific library or one of the special values *ALL, *ALLUSR, *CURLIB, *LIBL, or *USRLIBL.
The fourth parameter, Error code, is the standard error code structure we have seen before.
With that information out of the way, let's now write a sample program that displays all occurrences of a specific module that is found within one or more *SRVPGMs. Here's the initial code (and I stress initial because this code needs several improvements, which we will make before concluding on this topic in a future column):
h dftactgrp(*no)
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
dModUsage
pr
d ModNam
10
const
d SrchLib
10
const
dModUsage
pi
d ModNam
10
const
d SrchLib
10
const
d/copy qsysinc/qrpglesrc,qusec
d/copy qsysinc/qrpglesrc,qusgen
dChkSrvPgmMod
pr
dSetup
pr
dGenHdr
ds
likeds(QUSH0100)
based(ModLstSpcPtr)
dObjLibNam
ds
10
inz('*ALL')
d ObjLib
10
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
dModLstSpcPtr
dCount
10i 0
dNbrMods
10i 0
dHits
10i 0
dWait
dModLstSpc
'MODLUSRSPCQTEMP'
/free
if %parms < 2;
*inlr = *on;
return;
endif;
Setup();
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
ChkSrvPgmMod();
*inlr = *on;
return;
/end-free
*****************************************************************
pChkSrvPgmMod
dChkSrvPgmMod
pi
dGetSrvPgmInfo
pr
extpgm('QBNLSPGM')
d QUsrSpcNam
20
const
d Format
const
d QSrvPgmNam
20
const
d QUSEC
likeds(QUSEC)
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
d/copy qsysinc/qrpglesrc,qbnlspgm
dSrvPgmE
ds
likeds(QBNL010000)
based(SrvPgmEPtr)
dSrvPgmEPtr
/free
if (GenHdr.QUSIS = 'C');
if SrvPgmE.QBNBMN00 = ModNam;
'/' + SrvPgmE.QBNSN00);
Hits += 1;
endif;
SrvPgmEPtr += GenHdr.QUSSEE;
http://www.mcpressonline.com Powered by Joomla! Generated: 28 August, 2008, 23:47
MC Press Online
endfor;
else;
endif;
/end-free
pChkSrvPgmMod
*****************************************************************
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
http://www.mcpressonline.com
10
const
Powered by Joomla! Generated: 28 August, 2008, 23:47
MC Press Online
d SpcTxt
50
const
d SpcRpl
10
const options(*nopass)
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
QUSBPRV = 0;
ObjLib = SrchLib;
http://www.mcpressonline.com
Powered by Joomla!
MC Press Online
CrtUsrSpc( ModLstSpc :' ' :1 :x'00' :'*CHANGE' :' ' :'*YES' :QUSEC);
/end-free
pSetUp
This program, MODUSAGE, takes two parameters. The first parameter is the name of the module we are looking for. The second parameter is the name of the library or one of the special values *ALL, *ALLUSR, *CURLIB, *LIBL, and *USRLIBL to search for *SRVPGMs. Given these two input parameters, the program then examines each *SRVPGM found in the specified library (or libraries in the case of a special value) and displays the qualified name of any *SRVPGM found that contains the specified *MODULE.
To compile MODUSAGE, use the command CRTBNDRPG MODUSAGE. To test MODUSAGE, in order to find all *SRVPGMs in library MYLIB that module MYMOD is bound to, use CALL MODUSAGE (MYMOD MYLIB).
As to how the program works, that will have to wait until our next column as we have run out of room in this issue of RPG Developer. There is, though, enough of the program shown above for you to use it for testing, and certainly feel free to examine the program in order to determine how it works. Hopefully, in the next column we'll confirm your understanding!
http://www.mcpressonline.com Powered by Joomla! Generated: 28 August, 2008, 23:47
MC Press Online
And, yes, some of the style may appear a bit strange, but you will in time see why as we add more function to MODUSAGE.
One word of caution: While MODUSAGE accepts special values such as *LIBL, you may, for now, want to limit your testing to specific libraries (or at least to special values that do not include QSYS--for instance, *ALLUSR or *USRLIBL). Otherwise, you may end up with error message CPF3CAA--List is too large for user space MODLUSRSPC. This is one of the considerations that we will be addressing with a future enhancement to MODUSAGE.
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!