Retrieve the contents of a z/OS data set or member
You can use this operation to retrieve the contents of a sequential data set, or a member of a partitioned data set (PDS or PDSE). To retrieve the contents of an uncataloged data set, include the volume serial on the request.
HTTP method and URI path
GET /zosmf/restfiles/ds/[-(<volser>)/]<dataset-name>[(<member-name>)]
- /zosmf/restfiles specifies the z/OS® data set and file REST interface
- /ds indicates a data set request
- -(<volser>) represents a volume serial. For an uncataloged data set, include this parameter to identify the volume to be searched for data sets or members that match the specified <data-set-name> or <member-name>. The length of the volume serial cannot exceed six characters. You cannot use wildcard characters for this parameter. Indirect volume serials are not supported.
- <datase-name> identifies the data set to be read. This parameter is required and must consist of a fully qualified data set name. The length of the data set name that you specify on the request cannot exceed 44 characters.
- <member-name> identifies the name of the PDS or PDSE member to be read. Include this parameter for a member read request.
- /<data-set-name>: To retrieve data from a sequential data set.
- /<data-set-name>(<member-name>): To retrieve data from a member of a PDS or PDSE.
- /-(<volser>)/<data-set-name>: To retrieve data from an uncataloged sequential data set.
- /-(<volser>)/<data-set-name>(<member-name>): To retrieve data from a member of an uncataloged PDS or PDSE.
Optional Query Parameters
- search=<string>
- The data set is searched for the first record that contains the string, without respect to case (by default).
- research=<regular-expression>
- The data set is searched for the first record that matches the given extended regular expression.
- insensitive=true|false
- The default is 'true'. When 'true', searches (search and research) are case insensitive. For case sensitive searches, specify 'false'.
- maxreturnsize=<integer>
- This parameter may be specified only with search= or research=.
If no X-IBM-Record-Range request header is present, the search will begin with the first record. In all cases, an X-IBM-Record-Range=p,q response header will be returned where p is the first matching record and q is the number of records returned.
If no matching records are found, the response header X-IBM-Record-Range=0,0 will be returned.
The parameter may not be used if a request header X-IBM-Data-Type specifies any option except 'text'.
Standard headers
- If-None-Match
- This header is optional; use it to specify the ETag token to be used to correlate this request
with a previous request. If the data on the z/OS host has not changed since the ETag token was
generated, z/OSMF returns a status of
HTTP 304 Not Modified
.For the initial request to the resource, you can omit this header.
Custom headers
- X-IBM-Data-Type
- This header is optional; use it to indicate whether data conversion
is to be performed on the returned data, as follows:
- When set to
text
, data conversion is performed. The data transfer process converts each record from EBCDIC to the charset specified on the "Content-Type" header of the request. If no charset is specified, the default is ISO8859-1. A newline (NL) character from the response charset is inserted between logical records. For data sets with fixed-length records, trailing blanks are removed.A value
"text;fileEncoding=<codepage>"
can be used to select an alternate EBCDIC code page. The default code page is IBM-1047.Note: An alternate file encoding cannot be specified with the "research" query parameter. - When set to
binary
, no data conversion is performed. The data transfer process returns each record as-is, without translation. No delimiters are added between records. The response Content-Type is "application/octet-stream". -
When set to
record
, no data conversion is performed. Each logical record is preceded by the 4-byte big endian record length of the record that follows. This length does not include the prefix length. For example: a zero-length record is 4 bytes of zeros with nothing following.
If you omit this header, the default is
text
; the response is converted. - When set to
- X-IBM-Return-Etag
-
This header is optional; set it to 'true' to force the response to include an "Etag" header, regardless of the size of the response data. If this header is not present or set to something other than 'true', then the default is to only send an Etag in the response for data sets smaller than a system determined length, which is at least 8MB. If X-IBM-Record-Range is present, then this header may not be specified with the value "true" and an Etag will never be returned.
If this header is enabled for very large data sets, then performance is impacted since the data set must be read twice by the system.
- X-IBM-Migrated-Recall
-
This header is optional; use it to specify how a migrated data set is handled. By default, a migrated data set is recalled synchronously. The following values may be specified too:
- wait
- This is the default value. If the data set is migrated, wait for it to be recalled before processing the request.
- nowait
- If the data set is migrated, request it to be recalled, but do not wait.
- error
- If the data set is migrated, do not attempt to recall the data set.
- X-IBM-Record-Range
-
Use this header to retrieve a range of records from a data set. You can specify this range using either of the following formats:
- SSS-EEE
- Where SSS identifies the start record and EEE identifies the end record to be retrieved. Both values are relative offsets (0-based).
- SSS,NNN
- Where SSS identifies the start record and NNN identifies the number of records to be retrieved.
- Usage notes:
- If X-IBM-Record-Range is specified, then an ETag header will not be returned and the If-None-Match request header is ignored.
- X-IBM-Obtain-ENQ
-
This header is optional; set it to one of the following values to request that a system ENQ be obtained and held after the completion of this request. If not specified, then no ENQs will be held after the completion of this request.
- EXCLU
- a SYSDSN/Exclusive ENQ will be held on the data set
- SHRW
- a SYSDSN/SHR ENQ will be held on the data set, and a SPFEDIT/EXCLU ENQ will be held on the data set, including the member name if this is a request for a PDS member.
- X-IBM-Session-Ref
-
This header is optional; include it with the value returned from a previous X-IBM-Session-Ref response header to indicate that your request should be executed in the TSO address space that was previously reserved with a X-IBM-Obtain-ENQ request header. This address space will not be used for other requests and if not used at least once every 10 minutes it will be terminated.
The following URL request may be used to "ping" the reserved address space to keep it alive:
GET https://zosmf1.yourco.com/zosmf/restfiles/ping HTTP/1.1
X-IBM-Session-Ref: xxxxxxThe X-IBM-Obtain-ENQ and X-IBM-Session-Ref headers are mutually exclusive.
- X-IBM-Release-ENQ
-
This header is optional; it may be specified with a value ''true'' to request that the ENQ held by the associated TSO address space be released.
This header must be specified along with a valid X-IBM-Session-Ref header.
- X-IBM-Target-System-User
- This header indicates the z/OS user ID that allows the user to access the target system. If the
X-IBM-Target-System
header is not supplied, this header is ignored. BothX-IBM-Target-System-Password
andX-IBM-Target-System-User
must be provided together; otherwise, this header is ignored.If this header is not provided in the current request, the current request uses the authenticated user credentials to access the target system if either of the following conditions are true:- The
X-IBM-Target-System-User
header was provided in a previous request - The service described in Authenticate with a secondary z/OSMF instance was issued in a previous request.
- The
- X-IBM-Target-System-Password
- This header indicates the password that is associated with the z/OS user ID. If the
X-IBM-Target-System
header is not supplied, this header is ignored. BothX-IBM-Target-System-Password
andX-IBM-Target-System-User
must be provided together; otherwise, this header is ignored.
Required authorizations
Usage considerations
Expected response
On completion, the service returns an HTTP response, which includes a status code indicating
whether your request completed. Status code 200
indicates success.
Status code 304
indicates unchanged content when a conditional get
is performed (such as when using the If-None-Match header with an
ETag from a previous response). A status code of 4nn
or
5nn
indicates that an error has occurred. For more
details, see Error handling.
For errors, the HTTP response includes error information as a JSON error report document. See Error report document.
Example request
GET /zosmf/restfiles/ds/SYS1.PARMLIB(SMFPRM00) HTTP/1.1
Example response
- Status code indicating that the request completed (status code
200
) - ETag that you can use on subsequent requests to test for changes to the resource
- Content-Length response header that specifies the amount of data that was returned (in bytes)
- A response body that contains the resource in plain text.
Example request
GET /zosmf/restfiles/ds/JIAHJ.REST.SRVMP HTTP/1.1