LMMLIST—list a library's members

The LMMLIST service, when used with the LIST or SAVE option, creates a list of the first occurrence of all the members in an ISPF library, a concatenated set of ISPF libraries, or an MVS™ partitioned data set associated with the given data ID.

When you invoke LMMLIST for the first time with the LIST option, the MEMBER variable determines the starting position within the member list. To position at the beginning, set the MEMBER variable to blanks. If the requested member is not found, the next member in the member list is returned. The member list is sorted by member name. Repeated invocation of LMMLIST provides access to each member name in the member list.

Use LMMLIST with the SAVE option to write a list of member names to a data set. If a MEMBER variable is nonblank, the member name you specify will be the first member in the list.

You must complete the LMINIT and LMOPEN services before using LMMLIST. Use the LMMLIST FREE option to release the list storage space when it is not needed.

Note: Member lists generated by LMMLIST cannot be displayed by LMMDISP, and member lists generated by LMMDISP cannot be used with LMMLIST. Member lists should be freed when switching between LMMLIST and LMMDISP with the same data ID.

Command invocation format


>>-ISPEXEC--LMMLIST--DATAID(data-id)--+--------------------+---->
                                      |         .-LIST-.   |   
                                      '-OPTION(-+-FREE-+-)-'   
                                                '-SAVE-'       

>--+--------------------+--+------------------+----------------->
   '-MEMBER(member-var)-'  |        .-NO--.   |   
                           '-STATS(-+-YES-+-)-'   

>--+--------------+--+-------------------------+--+------+-----><
   '-GROUP(group)-'  '-PATTERN(member-pattern)-'  '-LONG-'

Call invocation format


                                           .-'LISTbbbb'-.   
>>-CALL--ISPLINK--('LMMLISTb'--,data-id--,-+-'b'--------+------->
                                           +-'FREEbbbb'-+   
                                           '-'SAVEbbbb'-'   

                       .-'NObbbbbb'-.                
>--,-+-member-var-+--,-+-'b'--------+--,-+-group-+-------------->
     '-'b'--------'    '-'YESbbbbb'-'    '-'b'---'   

>--,-+-member-pattern-+--,-+-'LONG--'-+-);---------------------><
     '-'b'------------'    '-'b'------'


>>-CALL--ISPEXEC--(buf-len,--buffer);--------------------------><

Parameters

data-id

The data ID associated with the ISPF library, concatenated group of ISPF libraries, or MVS partitioned data set for which the member list is to be created. The data ID has been generated by the LMINIT service. The maximum length of this parameter is 8 characters.

LIST|FREE|SAVE

These options determine the action performed by the LMMLIST service.

LIST

The first time that you invoke the LMMLIST service with the LIST option, it creates a member list for use by a dialog.

If member-var is initialized to blanks, the first name in the member list is returned. If member-var is set to a member name for a starting position within the member list, that member name is returned in member-var. If the member is not found, the next member in the member list is returned. If you request statistics information for the member, the statistics are returned.

Later invocations of LMMLIST with the LIST option return succeeding member names and their statistics, if requested, until the end of the list is reached, as indicated by return code. At this point, the dialog should invoke LMMLIST with the FREE option.

FREE

The FREE option specifies that the storage acquired to create the member list is to be freed. Each creation of a member list should be matched by an invocation of LMMLIST with the FREE option.

SAVE

The SAVE option writes all member names in a list specified by the data ID to a data set. The name of the data set is determined by the presence and value of the GROUP parameter.

member-var

The name of the variable into which the name of the member used for positioning in the member list is specified, or the name of the next member in the list is to be stored. The maximum length of this parameter is 8 characters.

When you invoke LMMLIST for the first time, member-var is used for selecting a starting position within the member list. If the member is found, that member name is returned in member-var. If the requested member is not found, the next member in the member list is returned. To start at the beginning of the list, set member-var to blanks.

The member-var parameter serves the same purpose for the SAVE option as it does for the LIST option. When LMMLIST is used with OPTION (SAVE), a list of member names is written to a data set. If member-var is nonblank, the member name you specify is the first member in the list.

YES|NO

The STATS parameter can only be used with the LIST and SAVE options. The default is STATS(NO). If you specify STATS(YES) the LMMLIST service provides member statistics with the member names. This parameter is fully described under LMMFIND—find a library member.

group

This 8-character value specifies the group name of the data set that the LMMLIST service writes the member names list with the SAVE option. The entire data set name is <prefix>.<group>.MEMBERS. If you do not specify a group name the LMMLIST service writes to the ISPF LIST data set.

Note: LMMLIST service allocates the output data set with a DISP=OLD for the SAVE option.

member-pattern

The character string that is used to specify which members are to be returned. See the topic on naming ISPF libraries and data sets in the z/OS ISPF User's Guide Vol I for a more complete description of patterns and pattern matching.

LONG

When SAVE is selected to save the member list to a data set, LONG formats all dates in yyyy/mm/dd format for the member. Additionally, for PDS datasets not containing load libraries, the untranslated member name is written after the member name.

buf-len

A fullword fixed binary integer containing the length of the buffer parameter.

buffer

A buffer containing the name of the service and its parameters in the same form as they would appear in an ISPEXEC invocation for a command invocation.

Return codes

These return codes are possible:

0

One of these:

LIST option - Normal completion. The member list is available and the next member in the list is returned in the member-var parameter.
FREE option - Normal completion. The member list is freed successfully.
SAVE option - Normal completion. The member list is successfully written to a data set.

4

Empty member list.

8

One of these:

LIST option - End of member list.
FREE option - Member list does not exist.
SAVE option - For a data ID, the LMMLIST service has been invoked with the SAVE option after being invoked with LIST option, but before being invoked with the FREE option.

10

No data set is associated with the given data ID; that is, LMINIT has not been completed.

12

One of these:

The data set is not open or is not partitioned.
A parameter value is invalid.
Member list was created using LMMDISP.

16

A truncation or translation error occurred in accessing dialog variables.

20

Severe error; unable to continue.

Examples

Here are some examples of the LMMLIST service:

Example 1:

This example invokes the LMMLIST service with the LIST option to create a member list of the data set associated with the data ID in variable DDVAR and to return the first member namein the list in variable MEMVAR.

Command invocation

In this example, the LMMLIST service LIST option creates a member list of the data set associated with the data ID in variable DDVAR and returns the first member name in the list to variable MEMVAR.

SET &MEMVAR =
ISPEXEC LMMLIST DATAID(&DDVAR) OPTION(LIST)         +
                MEMBER(MEMVAR)

Call invocation

MEMVAR = ' ';
CALL ISPLINK ('LMMLIST ',DDVAR,'LIST    ','MEMVAR ' );
OR

Set the program variable BUFFER to contain:

MEMVAR= ' ';
BUFFER = 'LMMLIST DATAID(&DDVAR) OPTION(LIST)
                 MEMBER(MEMVAR)';

Set the program variable BUFLEN to the length of the variable BUFFER. Issue the command:

CALL ISPEXEC (BUFLEN, BUFFER);

Example 2:

In this example, the LMMLIST service SAVE option creates a member list, writes it to the ISPF LIST data set, using the data ID stored in IDVAR.

Command invocation

ISPEXEC LMMLIST DATAID(&IDVAR) STATS(YES) OPTION(SAVE)

Call invocation

CALL ISPLINK ('LMMLIST ',IDVAR,'SAVE    ','        ','YES     ');
OR

Set the program variable BUFFER to contain:

BUFFER = 'LMMLIST DATAID(&IDVAR) STATS(YES) OPTION(SAVE)';

Set the program variable BUFLEN to the length of the variable BUFFER. Issue the command:

CALL ISPEXEC (BUFLEN, BUFFER);

Example 3:

This example is an ISPF edit macro, which invokes the LMMLIST service to loop through all of the members of the data set being edited. This macro starts with the ISREDIT MACRO statement, which takes a parameter of a macro name. The data ID and member name are retrieved using the ISREDIT DATAID and ISREDIT MEMBER statements respectively. LMOPEN opens the data set so that LMMLIST can use it. The member name variable is blanked, so that the LMMLIST service starts at the first member in the data set. LMMLIST is called within a loop, which stops when LMMLIST returns a non-zero return code, either because all members have already been listed, or because an error occurred. If the LMMLIST service returns successfully, the EDIT service is called with the member name and the edit macro which was an input parameter. After the loop completes, the member list is freed with the OPTIONS(FREE) parameter of the LMMLIST service, and the data set is closed with the LMCLOSE service. This example is shipped with ISPF as 'ISP.SISPSAMP(ISRMBRS)'.

/*REXX****************************************************************/
/*   ISPF edit macro to process all members of partitioned data set, */
/*   running a second, user-specified, ISPF edit macro against each  */
/*   member.                                                         */
/*                                                                   */
/*   To run:                                                         */
/*    Enter "ISRMBRS macname" on the command line, where macname is  */
/*    the macro you want run against each member.                    */
/*********************************************************************/

'ISREDIT MACRO (NESTMAC)'

/*********************************************************************/
/* Get dataid for data set and issue LMOPEN                          */
/*********************************************************************/
'ISREDIT (DATA1) = DATAID'
'ISREDIT (CURMEM) = MEMBER'
Address ispexec 'LMOPEN DATAID('data1') OPTION(INPUT)'
member = ' '
lmrc = 0

/*********************************************************************/
/* Loop through all members in the PDS, issuing the EDIT service for */
/* each.  The macro specified on the ISRMBRS invocation is passed as */
/* an initial macro on the EDIT service call.                        */
/*********************************************************************/
Do While lmrc = 0
  Address ispexec 'LMMLIST DATAID('data1') OPTION(LIST),
                  MEMBER(MEMBER) STATS(NO)'
  lmrc = rc
  If lmrc = 0 & member /= curmem Then
    do
      Say 'Processing member' member
      Address ispexec 'EDIT DATAID('data1') MEMBER('member')
                      MACRO('nestmac')'
    end
End

/*********************************************************************/
/* Free the member list and close the dataid for the PDS.            */
/*********************************************************************/
Address ispexec 'LMMLIST DATAID('data1') OPTION(FREE)'
Address ispexec 'LMCLOSE DATAID('data1')'

Exit 0