ZDSLIST Function: z/OS

Returns a list of data set names.

Category:	External Files
z/OS specifics:	info-item

Syntax

Syntax

zdslist(category, data set filter, volume filter, <option>);

Required Arguments

The following arguments are usually required. They can also be optional, depending on their category.

category

The following values are supported:

CATLG: returns cataloged data set names.

HSM: returns migrated data set names.

VSAM: returns VSAM cluster and index names.

NVSAM: returns non-VSAM data set names.

ALL: returns aliases from the master catalog.

VOLS: returns the names of data sets that are resident on the specified volumes.

USSDIR: returns UFS filenames and directories.

data set filter

A data set filter can be any of the following:

a fully qualified data set name.
a wildcard.
a list of data set names. Fully qualified data set names and wildcards can be mixed.
partitioned directory names.
a partitioned directory name with a member name attached within parentheses.
a GDG name, which can be an index, a fully expanded name, or with a generation number attached.
a UFS file or directory name. Wildcards are permitted.

The following list contains information about data set filters for each category of data set:

CATLG category

Specifying a data set filter of null, ‘*’ or ‘**’ with CATLG returns the names of all of your data sets. To retrieve all entries from the catalog, specify a data set filter of ‘*ALL’ with CATLG. The MEM option is not permitted with this filter.

If the data set filter refers to a partitioned data set, and the MEM option is specified, then ZDSLIST will return the data set name and a list of members enclosed in ellipses. For example:

data set name{member1, member2…}

A request for a specific member, such as ‘userID.sas.testsrc(absspec)’, returns that data set name and member, if it is found. Other members from the PDS are not returned, even if the MEM option is specified.

Use of this request structure with a wildcard can be a useful search tool to find PDSs that contain a specific member. For example, the filter ‘userID.*.testsrc(absspec)’ returns all testsrc data sets that contain absspec:

userID.sas.testsrc(absspec),userID.backup.testsrc(absspec)

A data set filter that contains a GDG group without qualification will cause ZDSLIST to return all of the expanded GDG names for that group. A GDG name with a qualification such as -1 will return the expanded name that is relevant to that level.

Note: Tape files are not processed.

ZDSLIST skips over spurious characters that are present at the beginning or end of a data set filter. It attempts to bypass some errors such as a data set being in use. However, if the filter contains an error, such as a data set name that is longer than 44 characters, then the whole filter is regarded as being in error.

The location of wildcards in data set filters is crucial. The following table contains examples of wildcards in data set filters. Note the location of the wildcards and the differences in the information that is returned.

Wildcards in Data Set Filters

Data Set Filter	Returned Information
`‘userID.sas.*’`	userID.sas.cntl,userID.sas.load.userID.sas.testsrc...
`‘userID.*.cntl’`	userID.backup.cntl,userID.sas.cntl, userID.sas900.cntl…
`‘userID.s.c’`	userID.sas.cntl,userID.sas900.cntl, userID.superc.clist…
`‘userID.s.c’`	userID.sas.doc,userID.sas.dsc…
`‘userID.s.c’`	userID.sas.cntl,userID.supers.cvg,userID.wxss.cdata…
`‘userID.s.’`	userID.sas.cntl,userID.sas.doc, userID.sas.dsc,userID.sas.load,userID.sas.testsrc,userID.sas900.cntl, userID.superc.clist,userID.supers.cvg…
`‘userID.sas.c*’`	userID.sas.cntl
`‘userID.sas.c’`	userID.sas.cntl,userID.sas900.cntl
`‘userID.sas.d*c’`	userID.sas.doc,userID.sas.dsc

The data set filter name might contain a prefix such as

‘MVS:userID.sas.testsrc,MVS:.io’

that returns the data set name ‘userID.sas.testsrc’ and all of the data set names that begin with userID.io. It will also return member names for any data set that is partitioned if the MEM option is specified.

VSAM, NVSAM, and HSM categories: These categories can be considered subsets of CATLG, but they have more restrictive guidelines. Only VSAM data sets are returned for the VSAM category, and non-VSAM data sets are returned for the NVSAM category. The HSM category indicates that only migrated data sets are returned, based on a volume serial number value of MIGRAT. A volume filter with a category value of HSM is ignored.

ALL category: A category of ALL is set to CATLG. If the data set filter is null (or “*”, or “**”), then it is set to * and processed as a CATLG alias request. Otherwise, if the data set filter is not null, then the request will be treated as a normal CATLG request.

VOLS category: A null data set filter is supported for the VOLS category. However, you must provide a volume filter, either as a specific volume, a list of volumes, a wildcard, or a passed variable from ZVOLLIST.

If a data set filter is specified, then processing is the same as it is for CATLG, and only matching data sets from the nominated volumes are returned.

If there is not a data set filter, then all DSCB-1 and DSCB-8 entries from the VTOCs of nominated volumes are returned. Entries are returned in indexed order (if VTOC is indexed) or in physical sequential order.

A specific volume filter must specify volume serial numbers or wildcards. If volumes for a device name are required, then first call ZVOLLIST and pass the output variable to ZDSLIST. The maximum number of volumes that can be processed is 671. A warning message is issued if this number is exceeded, and processing occurs for the volumes that are stored in the array, up to the limited number of volumes.

A volume filter can be specified as a system symbol (defined in SYS1.PARMLIB, member IEASYMxx). The filter is substituted with the real volume (for example, M1ASP1 for &CPPM1). Only fully qualified filters are substituted in this way. A wildcard such as &CPPM* will not be substituted. Only a single volume serial number can be returned for a system symbol.

USSDIR category

USSDIR retrieves UFS filenames according to the data set filter specification. If the filename that is retrieved is not a directory, then a retrieval from the subdirectories is not attempted. Otherwise, a first-level retrieval is performed.

Wildcards are supported as part of the filter name. You can specify up to ten path components, and up to two wildcards in each of the path components. The wildcards can be in a variety of formats. For example,

/u/userID/ab*/d*f/*hi/j**/*n*/**r/stu/vw*/*za/test*

might return

/u/userID/abc/def/ghi/jkl/mno/pqr/stu/vwx/yza/test1file

Note: An “Invalid Physical Name” message is issued if you specify more than the maximum number of wildcards and paths.

For the home directory /u/userID, each of the following filters returns the path of the home directory:

*/userID
**/userID
*
**

A filter of ~userI* or .userI* produces a request of /u/userID/userI*.

Note: A volume filter specification is ignored.

A specification that extends beyond the home directory will retrieve entries in the following order:

filenames
directories (plus first-level entries from each of them if ENT is specified)

For example,

/u/userID/*

returns

/u/userID/file1,/u/userID/file2,/u/userID/dir1{ent1,ent2,ent3}

Note: Entries of “.” and “..” are omitted from the returned information.

The value of the filesystem option is ignored. If, in general, this option defaults to MVS, then USSDIR requests would rarely be allowed without always prefixing data set filter names with HFS:. Specifying USSDIR implies that you are requesting information about UFS files. A specific prefix within the data set filter is honored. For example, ‘MVS:userID.sas’ results in an error for the USSDIR category.

A specification of /u/userID/w*.* returns only the filenames and directories that begin with a ‘w’ and have a suffix, such as

/u/userID/wxfiles.wxmvs

volume filter: returns all volume serial numbers for the specified category if a NULL volume filter is specified. A volume serial number can be a six-character value (for example, SDS001), or a wildcard (for example, SDS*). If a wildcard is specified, then all volume serial numbers beginning with SDS for the specified category are returned. The volume filter might be a list such as SDS001, SMS*, APP0*. The first character of the filter cannot be a blank space. If it is, then the filter is assumed to be NULL. The variable name returned from ZVOLLIST can be inserted in this parameter list.

option

The following values are supported for the option argument:

MEM \| NOMEM	indicates whether a member name list is returned with a PDS or a PDSE name. NOMEM is the default.
ENT \| NOENT	indicates whether a first-level entry name list is returned for a directory name. This value is only for USSDIR processing. NOENT is the default.

Details

Invoking ZDSLIST

Use the following method to invoke the ZDSLIST function:

length xdsn $20480;
xdsn=zdllist(category, data set filter, volume filter, option);

Note: If the declared size of the user-defined output variable is too small to contain the amount of generated data, then ZDSLIST allocates a larger buffer. ZDSLIST continues allocating a larger buffer until the data requests are satisfied or until memory availability is exhausted. Messages about the allocation of a larger buffer are posted to the SAS log.

Error Messages

An error in a filter specification will terminate the task. A warning message, such as one for files that do not exist within a multiple filter, will issue the appropriate warning for those filenames before processing the remaining entries in the filter.

Example

length xdsn $32000;
length catgry dfilter vfilter optparm $256;
catgry = ‘CATLG’;
dfilter = ‘userID.sas.cntl’;
vfilter = ‘’;
optparm = ‘’;
xdsn=zdslist(catgry, dfilter, vfilter, optparm);
dfilter = ‘.sas.cntl, .sas.load’;
xdsn=zdslist(catgry, dfilter, vfilter, optparm);
vfilter = ‘sds*, sms*’;
xdsn=zdslist(catgry, dfilter, vfilter, optparm);
xdsn=zdslist(catgry, dfilter, vfilter, ‘mem’);
xdsn=zdslist(catgry, ‘userID.sas.cntl(absspec)’, vfilter);
xdsn=zdslist(catgry, ‘userID.*.cntl(absspec)’, vfilter);
     /* identifies which data set contains the member */
dfilter = ‘userID.copy.gdgtst1(+0)’;   /* GDG  */
xdsn=zdslist(catgry, dfilter);
catgry = ’USSDIR’;
dfilter = ‘/u/sa*dr*/wx*d2a/test*fil*’;
xdsn=zdslist(catgry,dfilter,’’,’’);
xdsn=zdslist(catgry, ‘/u/userID/ftptst*’, ‘’, ‘ent’);

The output format of the ZDSLIST function contains a list of data set names that are separated by commas. Partitioned data sets can be followed by a member list that is contained in ellipses. The start of the output variable contains the constant ZDSLIST or, in the case of overflow buffers, the constant ZDSSTOR.

The following table contains specific examples of ZDSLIST function requests and their corresponding output formats for MVS data sets:

MVS Data Sets

Request	Output format
Multiple fully qualified data sets	userID.bmplib.list,userID.bkm.print,userID.brodcast
Sequential data set and PDS with MEM	userID.bkm.print,userID.sas.cntl{mem1,mem2,mem3}
PDS with specific member (MEM or NOMEM) such as `userID.sas.cntl(absspec)`	userID.sas.cntl(absspec)
PDS with specific member and sequential data set	userID.sas.cntl(absspec),userID.brodcast
Wildcard PDS with specific member such as `userID.*.testsrc(dbfwhere)`	userID.dbi,testsrc,userID.egauto.testsrc,userID.sas.testsrc, userID.sas.testsrc(dbfwhere),userID.z64vsam.testsrc
GDG indexes such as `userID.vxcopy.gdg*`	userID.vxcopy.gdgtest,userID.vxcopy.gdtgtst1, userID.vxcopy.gdgtst2
GDG index such as `userID.vxcopy.gdgtst1`	userID.vxcopy.gdgtst1,userID.vxcopy.gdgtst1.g0001v00, userID.vxcopy.gdgtst1.g0002v00,……… userID.vxcopy.gdgtst1.g0005v00
GDG index and data sets such as `userID.vxcopy.gdgtst1.*`	userID.vxcopy.gdgtst1, userID.vxcopy.gdgtst1.g0001v00, userID.vxcopy.gdgtst1.g0002v00,……… userID.vxcopy.gdgtst1.g0005v00
GDG index such as `userID.vxcopy.gdgtst1*`	userID.vxcopy.gdgtst1
GDG data sets such as `userID.vxcopy.gdgtst1(+0),userID.vxcopy.gdgtst1(-1)`	userID.vxcopy.gdgtst1.g0005v00,userID.vxcopy.gdgtst1,g0004v00
PDS with NOMEM option (or default)	userID.sas.cntl
Multiple PDS data sets with NOMEM	userID.sas.cntl,userID,sas.load,userID,sas,src
PDS data sets with MEM	userID.sas.cntl{mem1,mem2,mem3}, userID.sas.load{mem1,mem2,mem3}, userID.sas.src{mem1.mem2,mem3}
PDS data set and sequential data set with NOMEM	userID.sas.cntl,userID.bmplib.list
Fully qualified data set	userID.bmplib.list

The following table contains specific examples of ZDSLIST function requests and their corresponding output formats for UFS data sets:

UFS Data Sets

Request	Output format
Special characters	/ / . /u/userID .. /u ./ /u/userID ../ /u ~ /u/userID ~/ /u/userID ~userID /u/userID /u /u
`/u/userID & NOENT`	Returns only the directory. /u/userID
`/u/userID & ENT`	Returns files and then directories. It does not return entries. /u/userID,/u/userID/aaa,/u/userID/bbb,/u/userID/ccc
`/u/userID/* & NOENT`	Returns files and then directories. It does not return entries. /u/userID/aaa,/u/userID/bbb,/u/userID/ccc
`/u/userID/* & ENT`	Returns files, directories, and entries. /u/userID/aaa,/u/userID/bbb, /u/userID/ccc{ent1,ent2,ent3}
`~/wxcat1*`	Returns files and then directories. It does not return entries. /u/userID/wxcat1.a.b,/u/userID/wxcat1.c, /u/userID/wxcat1_dir1
`~/w.`	/u/userID//wxcat1.a.b,/u/userID/wxcat1.c, /u/userID/wxfiles.d
`~/w*`	/u/userID/wxcat1.a.b, /u/userID/wxcat1.c,/u/userID/wxfiles.d, /u/userID/wxcat1_dir1
`~/*.dbf`	/u/userID/aaa.dbf,/u/userID/bbb.dbf
`/u/userID/fileext,~/fileext,./fileext` (Duplicates omitted)	/u/userID/fileext
`/u/userID/wxcat1_dir,~/wxcat_dir2,~userID/wxcat1_dir3 & NOENT`	/u/userID/wxcat1_dir,/u/userID/wxcat1_dir2, /u/userID/wxcat1_dir3
`/u/userID/wxcat1_dir,~/wxcat_dir2,~userID/wxcat1_dir3 & ENT`	/u/userID/wxcat1_dir,/u/userID/wxcat1_dir/file1, /u/userID/wxcat1_dir2,/u/userID/wxcat1_dir2/file1, /u/userID/wxcat1_dir3,/u/userID/wxcat1_dir3/file1, /u/userID/wxcat1_dir3/file2
`/u/userID/ftptst8` (dir & NOENT)	/u/userID/ftptst8
`/u/userID/ftptst8` (dir & ENT)	/u/userID/ftptst8,/u/userID/ftptst8/ent1, /u/userID/ftptst8/ent2
`/u/userID/ftptst*` (directories & NOENT)	/u/userID/ftptst1, /u/userID/ftptst4, /u/userID/ftptst8
`/u/userID/ftptst*` (directories & ENT)	/u/userID/ftptst1{ent1,ent2,ent3}, /u/userID/ftptst4, /u/userID/ftptst8{ent1,ent2}