LISTC (List Catalog)

Syntax:

LISTC([level][,dsnqual][,catalog][,option][,stem])

Arguments:

level

is the 1 to 64 character name that identifies the data set or data sets for which you want catalog information. This argument must never contain single quotes. The userid is never appended to level.

You may use the asterisk (*) wild card character as long as you abide by the rules for the LISTC LEVEL parameter (i.e., the asterisk cannot be the last qualifier).

Note: If you do not specify level, the entire catalog will be listed. If the catalog is large, this operation may take some time.

dsnqual

is the 1 to 80 byte string containing LISTC command data set name qualifiers. Keywords must be separated by at least one blank. Do not use this argument to specify other LISTC keywords such as VOLUME or ALL. This string is not checked by the interface. Any errors are detected by IDCAMS itself.

catalog

is the catalog containing the entry for the data set(s) to be listed. If a password is required use the form catalog/password. The catalog name must be fully qualified, without quotes. Userid is never appended to the catalog name.

option

one of the following may be specified:

'N'

list only names. This is the default.

'V'

list names and volume information.

stem

the name of a stem array into which you want LISTC function output directed. If you desire a true REXX stem, code a period suffix (e.g., "abc." will yield variables abc.1, abc.2. abc.n). If stem is not coded, LISTC function output is directed to the REXX data stack.

Note: 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).

Module Name:

Service Description:

Notes:

1. The LISTC function constructs a LISTCAT command of the form:

   LISTCAT  [LEVEL(level)]  [dsnqual]
            [CATALOG(cat/pw)] {VOLUME | NAME}
   

2. Refer to the Access Method Services publication for your system's level of DFP or DFSMS for more information on the LISTCAT command.
3. If you need to execute a LISTCAT command with the ENTRIES keyword, do not use the LISTC function. Use the LISTC command under ADDRESS IDCAMS.

Returned Information:

Data set information is formatted into records with fixed columns. If the stem argument is specified, the information is placed into a stem array. Otherwise, the information is returned in the REXX data stack. In both cases, each data set is represented by exactly one record.

If you specify the "N" option (or allow it to be defaulted) only one column of information is returned: the fully qualified data set name. If you specify the "V" option, the following columns of information are returned:

Word	Data Item	Description
1.	dsname	Fully qualified data set name (no quotes).
2.	volser	Volume serial number. If the data set spans volumes, only the first volser is reported.
3.	unit	Type of unit (e.g., "3390"). If the data set spans volumes, only the first unit is reported.
4.	type	Type of catalog entry (e.g., "NONVSAM").
5.	cdate	The date the data set was created.
6.	edate	Expiration date.
7.	storclass	SMS storage class.
8.	mgmtclass	SMS management class.
9.	dataclass	SMS data class.
10.	last back-up	The date of the most recent back-up.

If a data item is unavailable, the interface supplies a single question mark (?) as a placeholder. This ensures that the word position of all columns remains constant. By default, the records are ordered by dsname in ascending sequence.

The LISTC function returns any "IDC" messages produced the LISTCAT command. The messages are returned in a special array whose stem is $SWXIDCMS. The zeroth element ($SWXIDCMS.0) contains the number of messages produced by the command.

Notes:

1. Only "IDC" messages are returned in the $SWXIDCMS. stem array. The messages are not in "ready-to-print" format (i.e., there are no printer control characters).
2. The function performs a REXX DROP on the $SWXIDCMS. stem prior to executing the LISTCAT command.
3. The function performs a MARGINS command prior to executing the LISTCAT command. Because of this, the first IDC message in the $SWXIDCMS. stem array is the "FUNCTION COMPLETED" message for the MARGINS command.

Examples:

1. List all data sets with the SYS1 prefix:

   parse value listc("sys1") with rc dsncount
   if rc = 0 then
     do i = 1 to dsncount
       parse pull dsname; say dsname
     end
   

2. List all data sets in a user catalog. Retrieve volume information and sort it by volser:

   parse value listc(,,usercat,'v','lc.') with rc dc
   if rc = 0 then do
     if dc ] 1 then
       if stemsort('lc.',,dc,'(46,6,CH,A)') = 0 then
         do i=1 to dc; say lc.i; end
       else
         say 'sort failed'
     else
       say lc.1
   end
   else
     say 'listc failed'
   

   Note: Because it uses specific column positions for the sort, this program may require modification to run with future releases of DFP, DFSMS, and REXXTOOLS.
3. Retrieve the names of all aliases whose first and third qualifier is "A". Search the default catalog:

   parse value listc('a.*.a','alias') with rc dsnc
   if rc = 0 then
     do i = 1 to dsnc
       parse pull dsn; say dsn
     end