The Scan Library List command scans source to help identify any
changes that must be made due to the V5R1/V5R2 system change that
increased the number of libraries from 25 to 250. Different scans
are performed to help identify where you have used functions that may
need to be changed.
If you are not familiar with the change made in V5R1 and V5R2, see
the section on 'Increase in Library List'.
You must have *USE authority to the TAACVTLIBD authorization list to
use the special values of *ALL, *ALLUSR2, or *ALLNONQ.
A typical command to scan all source files on the system in libraries
except ABC that do not begin with Q would be:
SCNLIBL LIB(*ALLNONQ) OMITLIB(ABC)
Three different scans are performed by default. This allows you to
improve the subsequent performance of SCNLIBL. For example, on the
initial use, you could request to scan for all conditions, but if you
determine that only RTVJOBA is a consideration, subsequent use of
SCNLIBL can limit to scanning for RTVJOBA.
Note that the scan will only describe where the command use of the
keyword (or API format name) exists. You will need to change the
variable length and review the use of the variable in the program to
determine if other changes are needed.
There are some potential unusual situations which are not covered by
SCNLIBL. See the section on 'Other Uses of the Library List'.
1. RTVJOBA use of USRLIBL parameter
-----------------------------------
This will typically represent the majority of statements that need to
be considered for change.
The listing would contain one line for each statement found in a CL
source type that contained the USRLIBL keyword found on a RTVJOBA
command. If the length of the variable used as the parameter can be
determined, it is flagged if it is not 2750.
The flagging technique allows you to re-run the command after you
think you have corrected known conditions.
SCNLIBL operates by reading each CL source member and building up the
statement in a large variable. A command can be spread of over
multiple lines (up to 5000 bytes). The command is extracted and if
it is RTVJOBA, a scan is used for the USRLIBL parameter plus '('.
The variable name is extracted and an attempt is made to determine
the length of the variable as declared in the program.
CL source types include CL, CLP, CLP38, and CLLE.
Some sub tools such as RTVCLPVAR have restrictions.
2. RTVJOBD use of USRLIBL parameter
-----------------------------------
RTVJOBD is a TAA command. The INLLIBL parameter still exists to
return a length of 275 bytes (25 libraries). A new parameter
INLLIBL2 has been added for the expanded size of 2750 (250
libraries).
The scan will only search for the use of INLLIBL so you will not see
the statements where you have already made a change to INLLIBL2. If
you want to scan for INLLIBL2, see the SCNCMDKWD command.
The listing produced for RTVJOBD is similar to that used for the
RTVJOBA scan and is done in the same manner.
3. API use where the library list may be processed
--------------------------------------------------
A few APIs return the library list. The scan checks a list of format
names used by APIs. The following describes this and the format that
must be manually reviewed:
QUSRSPLA - Retrieve spooled file attributes - SPLA0200
QUSRJOBI - Retrieve job information - JOBI0700
QWCRTVCA - Retrieve current attributes - RTVC0200
QWDRJOBD - Retrieve job description - JOBD0100
Increase in Library List
------------------------
Note that the support for the user portion of the library list
differs between V5R1M0 and V5R2M0. The system portion of the
library list is still limited to 15 libraries (can be
retrieved on RTVJOBA).
In V5R1M0, the system provided for a larger number of libraries on
the user portion of the library list (250 versus 25 previously).
However, the default retained the restriction of 25.
Prior to V5R1, if ADDLIBLE was used to attempt to add the 26th
library to the library list, escape message CPF2118 was sent. Some
applications already monitor for this condition.
There are several system functions for retrieving the library list.
If more than 25 libraries exist, you may see an incompatibility in
your current applications.
For example, a job could add more than 25 libraries and then attempt
to retrieve the library list using RTVJOBA with a return length of
275 bytes (room for 25 libraries). This would cause a new escape
message CPF098A. The message will not occur if 25 or less libraries
exist on the library list.
In V5R1, to prevent jobs from getting into trouble until applications
were modified, the system shipped a data area QLILMTLIBL in QUSRSYS.
If the data area existed and ADDLIBLE was attempted to add the 26th
library, the normal escape message CPF2118 occurred. If the data
area did not exist, the escape message would not occur until an
attempt was made to add the 251st library.
Note that on V5R1 there was no way to say JOBA could have more than
25 libraries, but JOBB could not. All jobs had to be treated the
same.
In V5R2 the support for 250 libraries exists, but the approach to
limiting the list changed so that the default allows for 250
libraries. The QLILMTLIBL data area is no longer checked for.
Instead, the QLMTUSRLIB data area is now shipped in QGPL with a value
of '0' (meaning more than 25 are allowed). The system searches for
the first QLMTUSRLIB data area found on the library list to determine
whether to enforce the 25 library limit. If none is found, a 250
limit is assumed. You can create your own version of QLMTUSRLIB, but
it must be TYPE(*CHAR) LEN(1). A value of '1' enforces the 25 limit,
a value of '0' allows greater than 25.
Note that with V5R2:
** The default allows for 250 libraries.
** Each job can determine its own limit.
Changes you must consider:
** The first change to consider is that all use of the RTVJOBA
return variable for USRLIBL be specified as a length of 2750.
This may impact other coding within the program that is
working with the return variable.
** Job Description objects may also contain up to 250 libraries
in the INLLIBL parameter. The value of the QLMTUSRLIB data
area will not prevent a job description from being created
with more than 25 libraries (an error would occur if you
attempted to use the job description and a limit existed).
The system does not support a RTVJOBD command, but the TAA
Productivity Tools do. You may find a use of RTVJOBD that
will also require changes.
** There are a few other commands that support INLLIBL or
USRLIBL. See the section on 'Other Uses of the Library List'.
** Other TAA tools that work with the library list (such as
RTNLIBL) have been updated to allow for the increased size.
Because these commands accept only input variables, the
function is upward compatible (you may pass any length
variable up to 2750).
** The system supports APIs that allow access of the library
list. See the section on 'API Use where the library list may
be processed'.
Other uses of the Library List
------------------------------
RTVJOBA is the only system command that supports the USRLIBL
parameter.
The INLLIBL parameter is also supported by the following commands:
BCHJOB
CHGJOBD
CRTJOBD
SBMJOB
Typical use of these commands and the library list would not cause
any problems. They are upward compatible if you specify 25 or less
libraries even if a variable is used.
If you have more than 25 libraries on the library list and use SBMJOB
INLLIBL(*CURRENT), the system will provide the proper result.
In a rare situation, you may have done a RTVJOBA of the library list
and passed the value on SBMJOB (this could only be done by
concatenating a command string and executing using QCMDEXC). Once
you find the RTVJOBA use of USRLIBL, your review should have already
corrected for this (such as increasing the size of the command
parameter used in QCMDEXC).
If you want to further check your source, you could consider the use
of SCNSRC and the ARGUMENT values:
275
LIBL
This will produce 'noise', but may also describe some obscure
situations.
Considerations
--------------
When scanning for RTVJOBA or RTVJOBD:
** Only the source types CL, CLP, CLP38, and CLLE are checked.
** Valid CL source must exist or the results are unpredictable.
** Continuation records are supported. Either the command or
keyword can be split over two lines and neither have to be in
the first record.
** The maximum size source statement that can be processed (with
continuation lines) is approximately 5000 bytes.
** An attempt is made to determine the size of the variable
specified for the USRLIBL or INLLIBL parameters. If it is not
2750, it will be flagged.
When scanning for API use, only CL and HLL source types are
considered. The source statements are converted to upper case before
scanning for the API names.
SCNLIBL escape messages you can monitor for
-------------------------------------------
TAA9893 No source files exist in the named libraries
TAA9894 The source file named does not exist
Escape messages from based on functions will be re-sent.
Command parameters *CMD
------------------
LIB Specifies 1 to 300 libraries to be searched.
The special value *USRLIBL may be used to describe
the user libraries on the current library list. The
current library is also considered to be part of
*USRLIBL.
The special value *ALL may be used to mean all
libraries. You must have *USE authority to the
TAACVTLIBD authorization list to use *ALL.
The special value *ALLUSR2 may be used to mean all
normal user libraries. This includes all libraries
that do not begin with the letter Q plus the QGPL
library and excludes the S/36 libraries #LIBRARY,
#CGULIB, #COBLIB, #DFULIB, #RPGLIB, #SDALIB,
#SEULIB, and #DSULIB. You must have *USE authority
to the TAACVTLIBD authorization list to use
*ALLUSR2.
The special value *ALLNONQ may be used to mean all
libraries that begin with a letter other than Q.
You must have *USE authority to the TAACVTLIBD
authorization list to use *ALLNONQ.
SRCFILE The source file name to be scanned. The default is
*ALL for all source files in the libraries that are
selected. Using *ALL is recommended for the initial
use as CL types may be misplaced and not in the
normal source files expected.
If a name is entered (such as QCLSRC), only that
source file name is searched in the selected
libraries.
RTVJOBA A *YES/*NO parameter for whether to scan CL source
types for the use of RTVJOBA and the USRLIBL
parameter. *YES is the default. *NO may be
specified to bypass the scan.
RTVJOBD A *YES/*NO parameter for whether to scan CL source
types for the use of the TAA RTVJOBD command and the
INLLIBL parameter. *YES is the default. *NO may be
specified to bypass the scan.
APIUSE A *YES/*NO parameter for whether to scan CL and HLL
source types for the use of the API format names
that may be used to return a library list. See the
previous discussion for the API names searched for.
*YES is the default. *NO may be specified to bypass
the scan.
OMITLIB A list of up to 300 libraries to be omitted if *ALL,
*ALLNONQ, or *ALLUSR2 are specified for LIB.
OMITLIB(*NONE) must be specified if a specific
library or libraries are named for the LIB
parameter.
Restrictions
------------
See the Considerations section.
Prerequisites
-------------
The following TAA Tools must be on your system:
CHKALLOBJ Check *ALLOBJ special authority
CHKDUPLST Check duplicate list
CMPLSTPARM Compare list parameter
EXTLST2 Extract list 2
HLRMVMSG HLL Remove message
PRINT Print
RTVCLPVAR Retrieve CLP variable
RTVSYSVAL3 Retrieve system value 3
SCNSRC Scan source
SNDCOMPMSG Send completion message
SNDESCMSG Send escape message
SNDJLGMSG Send job log message
SNDSTSMSG Send status message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
SCNLIBL *CMD TAAJBDG QATTCMD
TAAJBDGC *PGM CLP TAAJBDGC QATTCL
TAAJBDGC11 *PGM CLP TAAJBDGC11 QATTCL
TAAJBDGC12 *PGM CLP TAAJBDGC12 QATTCL
TAAJBDGC13 *PGM CLP TAAJBDGC13 QATTCL
TAAJBDGC14 *PGM CLP TAAJBDGC14 QATTCL
TAAJBDGR12 *PGM RPG TAAJBDGR12 QATTRPG
Structure
---------
SCNLIBL Cmd
TAAJBDGC CL pgm - Does CVTLIBDBF for source files
TAAJBDGC11 CL pgm - Does DSPFD *MBRLIST for source
TAAJBDGC12 CL pgm - Checks *MBRLIST file for CL types
TAAJBDGR12 RPG pgm - Scans the source and prints
TAAJBDGC13 CL pgm - Does RTVCLPVAR for variable def
TAAJBDGC14 CL pgm - Scans for API names
|
