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
- /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).
Include the following custom HTTP header with this request:
- 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.
- This header specifies whether the results are to include the data set base or volume attributes.
You can specify the following query parameter on this request:
- 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.
URLDecoder: Incomplete trailing escape (%) pattern.For example:
GET /zosmf/restfiles/ds?dslevel=sys%25d.*lib HTTP/1.1Notes:
- 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.
- 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.
- 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.
- Requests that only data set names be returned. If you omit this header, it is set to "dsname".
- Setting the X-IBM-Attribute to
basereturns all of the basic attributes for the data set being queried. These attributes are commonly found in the ISPF List Data set panel. The
basekey is mutually exclusive with volser, and dsname.
- Setting the X-IBM-Attribute to
volreturns the volume where the data set resides. If the dataset is a multi-volume dataset, use the
baseoption to list all the volumes.
- The suffix
,total, can be added to request that the "totalRows" property is returned if more data sets than the maximum requested are available.
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
A sample response is shown in Figure 1.
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
A sample response is shown in Figure 2.