TAA Tools
SCNLIBL         SCAN LIBRARY LIST                      TAAJBDG

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
					

Added to TAA Productivity tools June 15, 2001


Home Page Up to Top