Retrieve the contents of a z/OS UNIX file
You can use this operation to retrieve the contents of a z/OS® UNIX System Services file.
HTTP method and URI path
GET /zosmf/restfiles/fs/<filepath-name>
- /zosmf/restfiles specifies the z/OS data set and file REST interface
- /fs indicates a UNIX file request
- <filepath-name> identifies the UNIX file to be read. This parameter is required and must consist of a fully qualified path and file name.
Optional Query Parameters
- search=<string>
- The file is searched for the first line that contains the string, without respect to case (by default).
- research=<regular-expression>
- The file is searched for the first line 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=.
For the search and research queries, records are returned starting with the first matching line.
The maximum line length supported for text searches in 64K. The X-IBM-Record-Range request header
may be used to specify the range of lines to be searched, but it will not restrict the number of
lines returned (see maxreturnsize).
If no X-IBM-Record-Range request header is present,
the search will begin with the first line. In all cases, an X-IBM-Record-Range=p,q response header
will be returned where p is the first matching line and q is the number of lines
returned.
If no matching lines 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 an initial request to the resource, you can omit this header.
- Range
-
This header is optional; use this header to retrieve a range of bytes from a file. This header is supported only when X-IBM-Data-Type=binary. Specify this range using the following:
bytes=first-byte-pos "-" last-byte-posThe first-byte-pos value is the byte-offset of the first byte in a range. The last-byte-pos value is the byte-offset of the last byte in the range. The byte positions specified are inclusive. Byte offsets start at zero. When last-byte-pos is not specified or is zero, the range extends to the end of the file. When the first-byte-pos is not specified, a tail range is returned. Comma separated ranges are not supported. For an initial request to the resource, you can omit this header.
Usage notes: If the range cannot be satisfied, i.e. zero bytes are returned, then a status code of 416 is set.
Examples (assuming a file with 10000 bytes):
bytes=0-499 retrieves the first 500 bytes
bytes=500-999 retrieves the second 500 bytes
bytes=500- retrieves the final 9500 bytes
bytes=-500 retrieves the final 500 bytes - X-IBM-Record-Range
- Use this header to retrieve a range of records (lines delimited by '\n') from a file. 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). When EEE is set to 0, records through the end of the file are retrieved. When SSS is omitted (i.e. -EEE), the final EEE records of the file are retrieved.
- 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 with Range an error is reported. If zero bytes are returned due to the range specified, status code 500 is returned.
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 line of data as-is, without translation.
If you omit this header, the default is
text
; the response is converted. - When set to
- X-IBM-Target-System = <string>
- This header indicates the target system name (nick name) for this request, where the system name
(nick name) is defined in the local system Systems table. The target host system must support
single-sign-on by using either an LTPA token or a valid
X-IBM-Target-System-User
andX-IBM-Target-System-Password
is provided for the target system. If the target system is the local system, this header is ignored and has no effect. - 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.
Query parameters
None.
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 an unchanged file when a conditional get is performed (such as when
using the If-None-Match header with an ETag from a previous response). Status code 206
indicates that a part of the file has been returned as
a result of a Range header on the request. Accompanying this status code will be a Content-Range
header in the form sss-eee/nnnnnn where sss-eee is the byte range that was actually returned and
nnnnnn is the length of the file. This status is returned only for the standard range header, not
the custom X-IBM-Record-Range header. Status code 416
indicates that zero bytes
have been returned due to the Range header on the request. This status is returned only for the
standard range header, not the custom X-IBM-Record-Range header. 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/fs/etc/inetd.conf 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.
200 OK
X-Powered-By: Servlet/3.0
Content-Type: text/plain; charset=UTF-8
Content-Length: 2673
Etag: AEA05EC01C7922ADD5103EBD95FFCC58
Content-Language: en-US
Date: Wed, 25 Nov 2015 03:07:10 GMT