You can use this operation to list the data sets on a z/OS
system. You can filter the returned list of data set names through
the specification of high-level qualifiers and wildcards.
HTTP method and URI path
GET /zosmf/restfiles/ds/?dslevel=<filter-criteria>[&start=dsname]
where:
/zosmf/restfiles specifies the z/OS data set and file REST interface
/ds indicates a data set request
?dslevel=<dataset-name-pattern>[&volser=<volser>&start=<dsname>] represents the query parameters used to qualify
the request, such as a data set name and, optionally, a volume serial (VOLSER).
Standard headers
None.
Custom headers
Include the following custom
HTTP header with this request:
X-IBM-Max-Items
This header value specifies the maximum
number of items to return. To request that all items be returned,
set this header to 0. If you omit this header, or specify an incorrect
value, up to 1000 items are returned by default.
X-IBM-Attributes
This header specifies whether the results are to include the data set base or volume attributes.
Query parameters
You can specify the following query parameter on this request:
dslevel
The search parameter that identifies the cataloged data sets to be listed. Either the dslevel or volser parameter must be specified and can be a fully qualified
data set name or a partial data set name with a filter to display a list of matches. A partial
data set name can include:
One or more high-level qualifiers or name segments
One or more wildcard symbols: percent sign (%), asterisk (*), or double asterisk (**)
A percent sign is a single character wildcard.
An asterisk is any number of characters within a qualifier.
A double asterisk is any number of characters within any number of lower-level qualifiers.
The parameter values must be URL-encoded, otherwise you may receive an error message. If you
use the percent sign (%) as a wildcard to filter the list of data sets returned, you must enter %25
to avoid receiving this error message: URLDecoder: Incomplete trailing escape (%)
pattern. For
example:
GET /zosmf/restfiles/ds?dslevel=sys%25d.*lib HTTP/1.1
Notes:
The length of the data set name that you specify on the request cannot
exceed 44 characters. The length limit includes wildcards, which are treated as one character each.
The wildcard %25 is treated as one character.
The system appends the following to any filter criteria that you specify:
.**
Lowercase characters are automatically folded to
uppercase.
volser
A parameter that identifies the volume serials to be
searched for data sets with names that match the specified dslevel parameter.
The volume serial is one to six characters. You cannot use wildcard characters for this parameter.
If you omit this parameter, the cataloged data set name is returned by default. If this parameter is specified, the data sets on the volume that
match the dslevel pattern are
returned.
start
An optional search parameter that specifies the first data set name to return in the response
document. The length of the data set name that you specify cannot exceed 44 characters, and cannot
contain wildcards. If the data set name is not found for the given search, then the next data set
matching the search will be returned.
X-IBM-Attributes
dsname
Requests that only data set names be returned. If you omit this header, it is set to "dsname".
base
Setting the X-IBM-Attribute to base returns all of the basic attributes for the
data set being queried. These attributes are commonly found in the ISPF List Data set
panel. The base key is mutually exclusive with volser, and dsname.
vol
Setting the X-IBM-Attribute to vol returns the volume where the data set
resides. If the dataset is a multi-volume dataset,
use the base option to list all the volumes.
,total
The suffix ,total, can be added to request that the "totalRows" property is
returned if more data sets than the maximum requested are available.