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
|
