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
|
