TAA Tools
RTVMBRLST2      RETRIEVE MEMBER LIST 2                 TAADBHY

The Retrieve Member List  2 command uses the API QUSLMBR  to access the
information for  all members or generic  members in a file.   A typical
series of commands would be:

             DCL        &MBRINF *CHAR LEN(9600)
              .
             RTVMBRLST2 FILE(xxx) MBR(ABC*) MBRINF(&MBRINF)

The  command would return  the member information  for the members that
begin with ABC from the specified file.

A 96  byte  data structure  is  returned for  each  member.   The  data
structure  for the  first member  would  be in  positions 1  - 96,  the
second in 97 - 192, etc.

The data structure for each member would appear as:

         1 - 10  Member name
        11 - 20  Source type
        21 - 33  Member create date/time as CYYMMDDHHMMSS
        34 - 46  Last source change date/time as CYYMMDDHHMMSS
        47 - 96  Member text

The  remaining part of  the data structure  will be blank  when no more
members exist.    Up  to  100  members may  be  returned  in  a  single
command.  See  the later discussion for  how to retrieve more  than 100
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

You may  specify a generic member name or *ALL  members in the file.  A
single member name may not be used.

If no  members exist  to  satisfy the  command, the  command  completes
normally.   The data structure  returned for the  first member will  be
blank and the number of members returned and available will be 0.

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 100 maximum.

The following would  be typical code  and is in  the correct format  to
be copied  into a CL  program.  First use  CPYTAA TAAARCMBR(RTVMBRLST2)
to the source for this documentation member to QATTINFO in TAATOOL.

             DCL        &MBRINF *CHAR LEN(9600)
             DCL        &WORK *CHAR LEN(96)
             DCL        &MX *DEC LEN(5 0)
             DCL        &MBRCNT *DEC LEN(5 0)
             DCL        &LOOPCNT *DEC LEN(5 0)
             DCL        &SRCMBR *CHAR LEN(10)
             DCL        &SRCTYP *CHAR LEN(10)
             DCL        &CRTDATE *CHAR LEN(13)
             DCL        &CHGDATE *CHAR LEN(13)
             DCL        &TEXT *CHAR LEN(50)
                        /********************************************/
                        /*                                          */
                        /*    Initialize for RTVMBRLST2 TAA Tool    */
                        /*                                          */
                        /********************************************/
             CHGVAR     &MX -95 /* Set for first bump */
             CHGVAR     &LOOPCNT 0
             RTVMBRLST2 FILE(QCLSRC) MBR(ABC*) MBRINF(&MBRINF) +
                          MBRCNT(&MBRCNT)
                        /********************************************/
                        /*                                          */
 LOOP:                  /*    Process a member                      */
                        /*                                          */
                        /********************************************/
             IF         (&LOOPCNT *LT &MBRCNT) DO /* Process a mbr */
             CHGVAR     &LOOPCNT (&LOOPCNT + 1)
             CHGVAR     &MX (&MX + 96)
                        /********************************************/
                        /*                                          */
                        /*    Extract the member info from the DS   */
                        /*                                          */
                        /********************************************/
             CHGVAR     &WORK %SST(&MBRINF &MX 96)
             CHGVAR     &SRCMBR %SST(&WORK 1 10)
             CHGVAR     &SRCTYP %SST(&WORK 11 10)
             CHGVAR     &CRTDATE %SST(&WORK 21 13)
             CHGVAR     &CHGDATE %SST(&WORK 34 13)
             CHGVAR     &TEXT %SST(&WORK 47 50)
                        /********************************************/
                        /*                                          */
                        /*             Your processing              */
                        /*                                          */
                        /********************************************/
                        /*                                          */
                        /*   At the end of member processing        */
                        /*    If LOOPCNT is LT MBRCNT, loop back    */
                        /*                                          */

                        /********************************************/
             IF         (&LOOPCNT *LT &MBRCNT) GOTO LOOP
             ENDDO      /* Process a member */
                        /********************************************/
                        /*                                          */
                        /*    All members have been processed       */
                        /*                                          */
                        /********************************************/

Performance implications
------------------------

  **   RTVMBRLST2 vs RTVMBRLST

       If  only  the member  names are  needed,  the RTVMBRLST  tool is
       easier to use and  provides up to 900  member names on each  use
       of the command.

       If  additional information  is needed  after  RTVMBRLST is  used
       (such  as  the   the  source  type  or  text  description),  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 to be  retrieved is large, RTVMBRLST2
       should be considered.   It will  return basic information  about
       each member,  but this  does not include  the number  of records
       in  the  member, the  number of  deleted  records, the  last use
       date, etc.   If the information  you need is  in the  RTVMBRLST2
       data structure, RTVMBRLST2 is a good performing solution.

  **   RTVMBRLST2  vs  DSPFD  outfile.     RTVMBRLST2  is  faster  than
       creating  an outfile  with DSPFD and  then processing  the file.
       If  the  information  you  need   is  in  the  RTVMBRLST2   data
       structure, RTVMBRLST2 is a better performing solution.

A single  member is  supported to allow  a common  approach.   A better
performing solution would be to use RTVMBRD.

Files with more than 100 members
--------------------------------

If  a file has  more than  100 members,  you can still  use RTVMBRLST2.
Each  use  of  the  command  will  return  information  for  up  to 100
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
100  members.    You  would first  specify  MBR(*ALL)  and  request the
return variable  of both  MBRCNT  (the number  returned in  the  MBRINF
return parameter) and MBRAVL (the number available to be returned).

During  the processing,  you would  keep a  count of  the members  that
have  been processed.  After  100 members have been  processed, if this
value is less than  the MBRAVL value, you  would specify *NEXT for  the
MBR parameter and request the RTVMBRLST2 command again.

When *NEXT is  used, the RTVMBRLST2  command starts to fill  the return
variable at the first member following the last one specified.

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

The  following  is sample  code showing  this technique  and is  in the
correct format to be  copied to a CL  source member.  First use  CPYTAA
TAAARCMBR(RTVMBRLST2) to  the source  for this documentation  member to
QATTINFO in TAATOOL.

             DCL        &MBRINF *CHAR LEN(9600)
             DCL        &MBRCNT *DEC LEN(5 0)
             DCL        &MBRAVL *DEC LEN(5 0)
             DCL        &PCSCNT *DEC LEN(5 0)
             DCL        &LOOPCNT *DEC LEN(5 0)
             DCL        &MBR *CHAR LEN(10)
             DCL        &MX *DEC LEN(5 0)
             DCL        &WORK *CHAR LEN(96)
             DCL        &SRCMBR *CHAR LEN(10)
             DCL        &SRCTYP *CHAR LEN(10)
             DCL        &CRTDATE *CHAR LEN(13)
             DCL        &CHGDATE *CHAR LEN(13)
             DCL        &TEXT *CHAR LEN(50)
                        /********************************************/
                        /*                                          */
                        /*    Initialize before the loop            */
                        /*                                          */
                        /********************************************/
             CHGVAR     &PCSCNT 0
             CHGVAR     &MBR '*ALL'
                        /********************************************/
                        /*                                          */
 LOOP:                  /*    Initialize for RTVMBRLST2 TAA Tool    */
                        /*                                          */
                        /********************************************/
             CHGVAR     &MX -95
             RTVMBRLST2 FILE(xxx) MBR(&MBR) MBRINF(&MBRINF) +
                          MBRCNT(&MBRCNT) MBRAVL(&MBRAVL)
                        /********************************************/
                        /*                                          */

 LOOP2:                 /*    Process if loop count is LT than the  */
                        /*      number of members in the MBRINF     */
                        /*      return variable.                    */
                        /*                                          */
                        /********************************************/
             IF         (&LOOPCNT *LT &MBRCNT) DO /* Process mbr */
                        /* Bump the counts and the index        */
             CHGVAR     &PCSCNT (&PCSCNT + 1)
             CHGVAR     &LOOPCNT (&LOOPCNT + 1)
             CHGVAR     &MX (&MX + 96)
                        /********************************************/
                        /*                                          */
                        /*    Extract the member info from the DS   */
                        /*                                          */
                        /********************************************/
             CHGVAR     &WORK %SST(&MBRINF &MX 96)
             CHGVAR     &SRCMBR %SST(&WORK 1 10)
             CHGVAR     &SRCTYP %SST(&WORK 11 10)
             CHGVAR     &CRTDATE %SST(&WORK 21 13)
             CHGVAR     &CHGDATE %SST(&WORK 34 13)
             CHGVAR     &TEXT %SST(&WORK 47 50)
                        /********************************************/
                        /*                                          */
                        /*             Your processing              */
                        /*                                          */
                        /********************************************/
                        /*                                          */
                        /*   At the end of member processing        */
                        /*    If 100 members have not been          */
                        /*      processed, loop back for next mbr   */
                        /*                                          */
                        /********************************************/
             IF         (&LOOPCNT *LT 100) GOTO LOOP2
                        /********************************************/
                        /*                                          */
                        /*    If the number of members processed    */
                        /*      is not the number available,        */
                        /*      use RTVMBRLST2 again with *NEXT.    */
                        /*                                          */
                        /********************************************/
             IF         (&PCSCNT *LT &MBRAVL) DO /* Not done yet */
             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,  a  generic member  name,  or  *ALL may  be
                 specified.

                 The special value  *NEXT may  be used  when more  than
                 100 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  single  member  is  supported  to  allow  a  common
                 approach.     A  better  solution   would  be  to  use
                 RTVMBRD.

   MBRINF        A required return  variable that  will contain a  data
                 structure  of information  for  each returned  member.
                 The  return   variable  must  be  specified  as  *CHAR
                 LEN(9600).  Up to  100 members may  be returned.   The
                 names are  returned in  alphabetical order.   If  less
                 than   100   members  are   returned,   the  remaining
                 positions in the variable will be blank.

                 Positions  1-10  contain  the member  name,  11-20 the
                 source type,  21-33  the  member create  date  in  the
                 format  CYYMMDDHHMMSS, 34-46  the  last source  change
                 date  in  the  format  CYYMMDDHHMMSS,  and  47-96  the
                 member text description.

   RTNLIB        An optional  return  variable that  will  contain  the
                 library where  the file was  found.  If  the qualified
                 part  of  the  FILE  parameter  is  *LIBL or  *CURLIB,
                 RTNLIB  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  &MBRINF
                 parameter.    If  used, the  return  variable  must be
                 specified as  *DEC LEN(5 0).   This  may be less  than
                 the number of members available.

   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 100  members  to  be processed.    If
                 used,  the return variable  must be  specified as *DEC
                 LEN(5 0).

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

The information for up to  100 members may be  returned on each use  of
the command.   It  is possible  to process files  containing more  than
100 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
   ------        ----    ---------      ----------    ----------

   RTVMBRLST2    *CMD                   TAADBHY       QATTCMD
   TAADBHYC      *PGM       CLP         TAADBHYC      QATTCL
					

Added to TAA Productivity tools August 1, 1996


Home Page Up to Top