List the z/OS data sets on a system

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. Start of change

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. End of change

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.
,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.

Required authorizations

See Required authorizations.

Usage considerations

See Usage considerations for the z/OSMF REST services.

Example request

In the following example, the GET method is used to list all of the cataloged data sets that match the partial name IBMUSER.CONFIG.*.

GET /zosmf/restfiles/ds?dslevel=IBMUSER.CONFIG.* HTTP/1.1

Example response

A sample response is shown in Figure 1.

Figure 1. Example: list all of the data sets.

Response:

200 OK
x-powered-by:  Servlet/3.0
Content-Type:  application/json; charset=UTF-8
Content-Length:  201
Content-Language:  en-US
Date:  Mon, 23 Nov 2015 09:10:11 GMT

Response Body:

{"items":[
{"dsname":"IBMUSER.CONFIG.FS"},
{"dsname":"IBMUSER.CONFIG.FS.DATA"},
{"dsname":"IBMUSER.CONFIG.ORIG.FS"},
{"dsname":"IBMUSER.CONFIG.ORIG.FS.DATA"}
],"returnedRows":4,"JSONversion":1}

Example request

The GET method is used to list all of the cataloged data sets with specified base attributes.

GET /zosmf/restfiles/ds?dslevel=**&volser=PEVTS2  HTTP/1.1

Request Headers:

X-IBM-Attributes: 'base'

Example response

A sample response is shown in Example: List data sets with attributes on a specified volser with X-IBM-Attributes.

Figure 2. Example: List all of the cataloged data sets with specified base attributes.

Response:

200 OK
x-powered-by:  Servlet/3.0
Content-Type:  application/json; charset=UTF-8
Content-Length:  714
Content-Language: en-US
Date:  Mon, 23 Nov 2015 09:11:46 GMT

Response Body:

{"items":[
{"dsname":"IBMUSER.CONFIG.FS","catnm":"CATPAK.MASTER.CATALOG","dsorg":"VS",
"migr":"NO","mvol":"N","vol":"*VSAM*"},
{"dsname":"IBMUSER.CONFIG.FS.DATA","blksz":"?","catnm":"CATPAK.MASTER.CATALOG",
"cdate":"2011/08/14","dev":"3390","dsorg":"VS","edate":"***None***","extx":"1",
"lrecl":"?","migr":"NO","mvol":"N","ovf":"NO","rdate":"2015/07/28","recfm":"?",
"sizex":"14250","spacu":"CYLINDERS","used":"?","vol":"CIMSSR"},
{"dsname":"IBMUSER.CONFIG.ORIG.FS","catnm":"CATPAK.MASTER.CATALOG","dsorg":"VS",
"migr":"NO","mvol":"N","vol":"*VSAM*"},
{"dsname":"IBMUSER.CONFIG.ORIG.FS.DATA","catnm":"CATPAK.MASTER.CATALOG",
"dev":"3390","migr":"NO","mvol":"N","vol":"PEVTS2"}
],"returnedRows":4,"JSONversion":1}