# 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:

SWXLISTC

## Service Description:

The LISTC function is used to invoke the IDCAMS LISTCAT command. Using this function you can retrieve lists of data set names and associated catalog information. The LISTC function parses the LISTCAT command output and places the information in records (one per data set) with fixed columns. The records are returned in the REXX data stack (the default) or in a stem array.

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:

The LISTC function returns a string containing the IDCAMS return code and the number of records of information produced. These fields are separated by one blank. If you CALL the LISTC function, the returned value 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.

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

© Copyright 1998 by Open Software Technologies, Inc.