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. 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.
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
Usage considerations
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}