TAA Tools
RTVMBRLST       RETRIEVE MEMBER LIST                   TAADBHX

The Retrieve  Member List command  uses the API  QUSLMBR to access  all
members  or generic  members in  a  file.   Only the  member  names are
returned.   The  command may  only be  executed in  a CL program  and a
typical command would be:

             DCL        &MBRLST *CHAR LEN(9000)
              .
             RTVMBRLST  FILE(xxx) MBR(ABC*) MBRLST(&MBRLST)

The command would return the  generic member names that begin  with ABC
from the specified  file.  The first member name  would be in positions
1-10, the second in 11-20, etc.

Up to  900 members may be returned in a  single command.  See the later
discussion about  how to retrieve  more than  900 members.   The  names
are returned in alphabetical order.

Optional return variables exist for:

       - The library name where the file is located
       - The number of members returned
       - The number of members available

If  no members  exist to  satisfy  the request,  the command  completes
normally.   The  first  member name  will be  blank and  the  number of
members returned will be 0.

Only  the  member  names  are  returned.    No  other  information   is
available.   If you  want more  information about the  member, see  the
later discussion on performance considerations.

Typical processing
------------------

Assume you want  to process the list of ABC  members in the source file
QCLSRC  and you  know the  number of  members returned will  not exceed
the 900 that can be returned on a single use of the command.

The following would be  typical code and is  in a format that  is ready
to   be  copied  into   a  CL   source  member.     First   use  CPYTAA
TAAARCMBR(RTVMBRLST)  to copy  the source  for this  documentation tool
to QATTINFO in TAATOOL.

             DCL        &MBRLST *CHAR LEN(9000)
             DCL        &MBR *CHAR LEN(10)
             DCL        &MX *DEC LEN(5 0)
             DCL        &MBRCNT *DEC LEN(5 0)
             DCL        &LOOPCNT *DEC LEN(5 0)
                        /********************************************/
                        /*                                          */
                        /*    Initialize for RTVMBRLST TAA Tool     */
                        /*                                          */
                        /********************************************/
             CHGVAR     &LOOPCNT 0
             RTVMBRLST  FILE(QCLSRC) MBR(ABC*) MBRLST(&MBRLST) +
                          MBRCNT(&MBRCNT)
             CHGVAR     &MX -9 /* Set for first bump */
                        /********************************************/
                        /*                                          */
 LOOP:                  /*    Process a member                      */
                        /*                                          */
                        /********************************************/
             IF         (&LOOPCNT *LT &MBRCNT) DO /* Process mbr */
             CHGVAR     &LOOPCNT (&LOOPCNT + 1)
             CHGVAR     &MX (&MX + 10)
             CHGVAR     &MBR %SST(&MBRLST &MX 10)
                        /********************************************/
                        /*                                          */
                        /*      Your processing                     */
                        /*                                          */
                        /********************************************/
             GOTO       LOOP
             ENDDO      /* Process a member */

Performance considerations
--------------------------

If only member names  are needed, RTVMBRLST is  a much faster  solution
than  using DSPFD  *MBRLIST to  produce an  outfile and  then read  the
data base file in a program.

If  additional information is  needed (such as  the the source  type or
the  number  of  members),  the  information  can  be  retrieved  using
RTVMBRD.   If  you  are retrieving  based  on a  generic  name and  the
number  of returned members  is not large,  RTVMBRD is a  good solution
for  accessing more  information.  If  the number  of members retrieved
is large, there are two solutions:

  **   RTVMBRLST2 tool.    This tool  is  similar to  RTVMBRLST  except
       that  in addition  to  the  member names,  a  data structure  is
       returned for each member with the following information:

           Member name
           Source type
           Member create date/time
           Last source change date/time
           Member text description

       RTVMBRLST2  returns  the information  on  up to  100  members on
       each use of the  command.  It is  possible to process more  than
       100  members   with  a  technique   similar  to  that   used  by
       RTVMBRLST.

  **   DSPFD  OUTFILE.  The  normal method  of processing members  in a
       file is  to  use the  OUTFILE  function supplied  by  DSPFD  and
       specify  a value  like  TYPE(*MBRLIST).   This  produces a  file
       that has  more information about each member  such as the number
       of  records in  the file.   The use of  TYPE(*MBR) provides even
       more information such  as the number  of deleted records in  the
       member.

RTVMBRLST can  be used with a  specific member name.   This function is
not efficient, but is supported to allow a common approach.

Files with more than 900 members
--------------------------------

If  a file  has more  than 900  members, you  can still  use RTVMBRLST.
Each use of  the command  will return up  to 900 members.   The  reason
for the restriction is  that CL restricts the size  of a *CHAR variable
to 9999 bytes.

Assume  you want all  members in  the file and  there may be  more than
900 members.    You  would  first specify  MBR(*ALL)  and  request  the
return variables  of both MBRCNT  (the number returned  on this use  of
the command) and MBRAVL (the number available to be returned).

During  the processing,  you would  keep a  count  of the  members that
have  been processed.   When the  members to be  processed is completed
based on  MBRCNT, you would  compare the  number processed against  the
MBRAVL count.   If there  are more to  be processed, you  would specify
MBR(*NEXT) and use RTVMBRLST again.

The  same  process  can  be repeated  until  all  members  in  the file
(system limit of 32K) have been processed.

The following  is sample  code showing  this technique  and  is in  the
correct format to be copied to a CL source member.

             DCL        &MBR *CHAR LEN(10)
             DCL        &MBRLST *CHAR LEN(9000)
             DCL        &MBRCNT *DEC LEN(5 0)
             DCL        &MBRAVL *DEC LEN(5 0)
             DCL        &MX *DEC LEN(5 0)
             DCL        &PCSCNT *DEC LEN(5 0)
             DCL        &LOOPCNT *DEC LEN(5 0)
             DCL        &WRKMBR *CHAR LEN(10)
             CHGVAR     &PCSCNT 0
                        /********************************************/
                        /*                                          */
 LOOP:                  /*    Initialize for RTVMBRLST TAA Tool     */
                        /*                                          */
                        /********************************************/
             CHGVAR     &MX -9
             RTVMBRLST  FILE(xxx) MBR(*ALL) MBRLST(&MBRLST) +
                          MBRCNT(&MBRCNT) MBRAVL(&MBRAVL)
             CHGVAR     &LOOPCNT 0
                        /********************************************/
                        /*                                          */
 LOOP2:                 /*    Process if loop count is LT than the  */
                        /*      number of members in the MBRLST     */
                        /*      return variable.                    */
                        /*                                          */
                        /********************************************/
             IF         (&LOOPCNT *LT &MBRCNT) DO /* Process mbr */
             CHGVAR     &PCSCNT (&PCSCNT + 1)
             CHGVAR     &LOOPCNT (&LOOPCNT + 1)
             CHGVAR     &MX (&MX + 10)
             CHGVAR     &WRKMBR %SST(&MBRLST &MX 10)
                        /********************************************/
                        /*                                          */
                        /*            Your processing               */
                        /*                                          */
                        /********************************************/

                        /********************************************/
                        /*                                          */
                        /*    If the number of members processed    */
                        /*      is not the number available,        */
                        /*      loop back if LT 900 or              */
                        /*      use RTVMBRLST again with *NEXT.     */
                        /*                                          */
                        /********************************************/
             IF         (&PCSCNT *LT &MBRAVL) DO /* Not done yet */
             IF         (&LOOPCNT *LT 900) DO /* LT 900 *
             GOTO       LOOP2
             ENDDO      /* LT 900 */
             CHGVAR     &MBR '*NEXT'
             CHGVAR     &LOOPCNT 0
             GOTO       LOOP
             ENDDO      /* Not done yet */
             ENDDO      /* Process the mbr */
                        /********************************************/
                        /*                                          */
                        /*    All members have been processed       */
                        /*                                          */
                        /********************************************/

Command parameters                                    *CMD
------------------

   FILE          The  qualified file  name of  the file.   The  library
                 value  defaults to *LIBL.   *CURLIB may  also be used.
                 A  source  file  would  normally  be  named,  but  the
                 command will operate on any data base file.

   MBR           A member  name, generic  member name,  or *ALL may  be
                 specified.

                 The  special value *NEXT  may be  used when  more than
                 900  members need to  be processed.   The use of *NEXT
                 may  only  follow  a  request  for   *ALL  or  generic
                 members  where the  MBRAVL count  is greater  than the
                 MBRCNT  count returned.  See  the previous example for
                 how this would be used.

                 A specific member name may  be used, but the  function
                 is not efficient.   It is supported to  allow a common
                 approach.

   MBRLST        A  required  return  variable  that  will contain  the
                 list  of  members.    The  return  variable  must   be
                 specified as *CHAR  LEN(9000).  Up to 900  members may
                 be returned  with the first member  in positions 1-10,
                 the  second in 11-20, etc.   The names are returned in
                 alphabetical order.    If less  than 900  members  are
                 returned,  the  remaining  positions in  the  variable
                 will be blank.

   RTNLIB        An  optional  return variable  that  will  contain the
                 library  where the  file  was  found.    If  *LIBL  or
                 *CURLIB was specified  for the library of  the file to
                 be  processed, the RTNLIB  parameter may  be of value.
                 If used,  the return  variable  must be  specified  as
                 *CHAR LEN(10).

   MBRCNT        An  optional return  variable  that will  contain  the
                 number   of  members   that  exist   in   the  &MBRLST
                 parameter.    If  used, the  return  variable  must be
                 specified as *DEC  LEN(5 0).   The number may be  less
                 than the  number of members available,  but will never
                 exceed 900.

   MBRAVL        An  optional  return variable  that  will  contain the
                 number of  members available  that match  the  generic
                 or *ALL  request.   This value is  helpful if  you may
                 have  more  than  900 members  to  be  processed.   If
                 used, the return  variable must be  specified as  *DEC
                 LEN(5 0).

Restrictions
------------

Up to 900 members may  be returned on a single use of the  command.  It
is  possible to process  files containing  more than 900  members using
the MBR(*NEXT) function.

Because  the command  returns variables,  it may only  be used  in a CL
program.

Prerequisites
-------------

The following TAA Tools must be on your system:

     CHKGENERC       Check generic
     CRTUSRSPC       Create user space
     SNDESCMSG       Send escape 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
   ------        ----    ---------      ----------    ----------

   RTVMBRLST     *CMD                   TAADBHX       QATTCMD
   TAADBHXC      *PGM       CLP         TAADBHXC      QATTCL
					

Added to TAA Productivity tools August 1, 1996


Home Page Up to Top