LISTM

Syntax:

LISTM(dsname[,volser][,maxcount][,option][,stem])

Arguments:

dsname

is the 1 to 64 character data set name that identifies the PDS or PDSE. The valid formats for dsname are:

datasetname

and

datasetname(memberpattern)

If the data set name is fully qualified, the dsname argument must be enclosed in single quotes. If it is not enclosed in single quotes, the userid (as determined by IRXUID) will be appended to the front. For more information see "Specifying Data Set Names".

If memberpattern does not contain any wild card characters, information retrieval begins with the member name given, or at the next highest member name, if the specified member does not exist. For more information on member pattern matching see "Using Pattern Matching".

Note: If memberpattern is not coded, it is the same as specifying datasetname(*).

volser

is the 1 to 6 character volume serial number identifying the volume upon which the data set resides. If the data set is not cataloged, you must specify this argument. If the data set is cataloged, you do not need to specify volser; a catalog search will find the correct volume for you.

maxcount

specifies the maximum number of members for which you want information retrieved. If this argument is not coded, information for all members satisfying the dsname argument is returned.

option

indicates the type of processing desired. The valid options are:

'N'

return member names only. This is the default. The member names are returned as a component of the function's value. Neither stem variables nor stack entries are created.

'S'

return directory entries. If the user field of an entry contains ISPF statistics, it is returned in a printable format. The information is returned in either stem variables or the REXX data stack.

'U'

return directory entries. The user field of an entry is returned in raw binary format (which may not be printable). The information is returned in either stem variables or the REXX data stack.

stem

the name of the stem array into which LISTM is to place directory information. If you desire a true REXX stem, you must code a period suffix. For example, "abc." will yield variables of the form abc.1, abc.2. abc.n.

If stem is not coded (and option "S" or "U" is used), directory entries are queued to the REXX data stack.

Notes:

1. No zeroth variable is created. The number of stem elements created is returned as a component of the function's value (see "Returned Information" below).
2. The stem argument applies only to options "S" and "U". For option "N", the stem argument is ignored.

Module Name:

Service Description:

Notes:

1. LISTM must allocate the data set (DISP=SHR) prior to reading its directory. If another user has exclusive use of the data set, LISTM's dynamic allocation request will fail. An error indication is given.
2. LISTM must open and read the data set's directory. If the user does not have sufficient authority, the request will fail. An error indication is given.
3. Listing very large directories in their entirety can:
   • take a significant amount of time, and
   • cause out-of-storage abends.

   If you must process all of the members of a large directory, you may want to increase your region size, and/or use a member pattern and maxcount to process blocks of member entries.

4. If you are using an application-specific locking protocol you must incorporate your use of LISTM into that protocol.
5. When ISPF statistics are requested, LISTM examines the user field of each directory entry to determine if valid statistics are present. If the validation check fails, no conversion is performed, and ISPF statistics are omitted from the member's record. No error indication is given.
6. If a member's directory entry does not contain a user field, and option "S" or "U" is specified, the output record will not contain user field information. No error indication is given.
7. Certain versions of ISPF support directory entries with 4-digit years. LISTM recognizes these entries, and will correctly report dates beyond 1999. Refer to IBM's documentation for more information on ISPF's 4-digit year support.

Performance Considerations:

1. The "N" option provides the best performance and uses the least amount of storage. If you do not require TTR or user field information, you should use this option. Refer to the topic "Parsing Returned Values" for more information.
2. If you are using the BPAM functions to read listed members, you may want to consider using the "S" or "U" options of LISTM in conjunction with the TTR form of FINDM. The TTR form of FINDM locates a member without performing a search. You must ensure that the members to be processed are not re-written -- by your task or another -- prior to calling FINDM. Re-writing a member changes its TTR.
3. A prefix member pattern (e.g., "abc*"), in most cases, performs better than a suffix pattern (e.g., "*abc").

Returned Information:

Return Code	Option N	Option S or U
Zero	rc membercount memberlist	rc membercount
Not Zero	rc reason dsname message	rc reason dsname message

The components of the returned string are as follows:

rc

the return code.

membercount

the number of members listed.

memberlist

a blank-delimited list of member names.

reason

the reason code (in printable hexadecimal characters) of the failing service.

dsname

the name of the data set.

message

a textual message giving the name of the failing service and a description of the error. The message contains embedded blanks.

If you CALL the LISTM function, the returned string is contained in the RESULT special variable. The RC variable is unchanged (unless you assign the return code to it). A return code of zero always indicates success.

If option "S" or "U" is specified, and the return code is zero, LISTM returns zero or more records of directory information. If the stem argument also is specified, the records are placed into a stem array. Otherwise, the records are returned in the REXX data stack. A member's directory entry is represented by exactly one record.

When the "S" option is used, the records of directory information are structured as follows:

Word	Data Item	Description
1.	name	The name of the member.
2.	ttr	The address of the member in TTR (Track and record) format. The address is 6 printable hexadecimal digits.
3.	c	The alias bit of the "C" byte of the directory entry. A value of "1" indicates that the entry is an alias entry. A value of "0" indicates that the entry is a primary entry.
4.	vv	ISPF version number.
5.	mm	ISPF modification level.
6.	cdate	ISPF creation date in CCYY.DDD format (Julian date with 4-digit year).
7.	mdate	ISPF modification date in CCYY.DDD format (Julian date with 4-digit year).
8.	mtime	SPF modification time in HH:MM:SS format.
9.	cl	ISPF current lines.
10.	il	ISPF initial lines.
11.	ml	ISPF modified lines.
12.	muserid	ISPF last modification user ID.

If an entry does not contain a user field, or if the user field does not appear to contain ISPF statistics, only the name, ttr, and c fields will be returned. No placeholders are supplied for the missing ISPF statistics.

If the "U" option is used, the records contain the following fields:

Word	Data Item	Description
1.	name	The name of the member.
2.	ttr	The address of the member in TTR (Track and record) format. The address is 6 printable hexadecimal digits.
3.	c	The alias bit of the "C" byte of the directory entry. A value of "1" indicates that the entry is an alias entry. A value of "0" indicates that the entry is a primary entry.
	userfield	The user field of the entry in raw binary format. This field may contain embedded blanks.

If an entry does not contain a user field, only the name, ttr, and c fields will be returned. No placeholder is supplied for the missing user field.

Notes:

1. LISTM performs a REXX DROP on the stem (if specified) prior creating the ddname records.
2. Member records are returned in the order in which they are read.
3. Depending on the nature of an error, a partial result -- in the form of stem variables or stack entries -- is possible.

Examples:

1. List all member names for a PDS. The data set name is fully qualified:

   parse value listm("'user01.pli'") with rc memcnt mlist
   if rc = 0 then do i=1 to memcnt
     parse var mlist mem mlist; say mem; end
   else do
     parse var memcnt reason dsn message
     say 'LISTM error:' message
   end
   

2. List the ISPF statistics for all members that start with "R" and end with "05":

   parse value,
         listm("user.exec(r*05)",,,'s'),
         with rc memcount
   do i=1 to memcount
     parse pull line; say line
   end
   

3. Retrieve directory entries with unformatted user fields into stem "de.". We only want the entries of members with 5-character names:

   parse value,
         listm("user.data(?????)",,,'u','de.'),
         with rc de.0
   do i=1 to de.0; say de.i; end