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>

where:

/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 data set is searched for the first record that contains the string, without respect to case (by default).; Optionally, insensitive=false may be specified for case sensitive matching.; This parameter may not be specified with the research= parameter.
research=<regular-expression>: The data set is searched for the first record that matches the given extended regular expression.; This parameter may not be specified with the search= parameter.; Implementation note: the regcomp() C Library function with the REG_EXTENDED flag is used.
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=.; The value given is the maximum number of records to return.; The default, if not specified, is 100.

For the search and research queries, records are returned starting with the first matching record. The X-IBM-Record-Range request header may be used to specify the range of records to be searched, but it will not restrict the number of records returned (see maxreturnsize).

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

You can include the following standard HTTP header with this request:

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-pos

The 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

You can include the following custom HTTP header with this request:

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

Query parameters

None.

Required authorizations

See Required authorizations.

Usage considerations

See Usage considerations for the z/OSMF REST services.

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

In the following example, the GET method is used to retrieve the contents of the file inetd.conf in the /etc directory.

GET /zosmf/restfiles/fs/etc/inetd.conf HTTP/1.1

Example response

For a successful request, the HTTP response contains the following:

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

A sample response body is shown in Figure 1.

Figure 1. Example: Response body for a GET request to the UNIX file /etc/inetd.conf

###                                                                     00000100
# Used to replace /etc/inetd.conf on 2nd level z/OS system              00000101
# so we can telnet/rlogin directly to OMVS using PuTTY consoles.        00000102
###                                                                     00000110
# Internet server configuration database                                00000200
#                                                                       00000300
# (C) COPYRIGHT International Business Machines Corp. 1985, 2001        00000400
# All Rights Reserved                                                   00000500
# Licensed Materials - Property of IBM                                  00000600
#                                                                       00000700
# US Government Users Restricted Rights - Use, duplication or           00000800
# disclosure restricted by GSA ADP Schedule Contract with IBM Corp.     00000900
#                                                                       00001000
# /etc/inetd.conf                                                       00001100
#                                                                       00001200
#          Internet server configuration database                       00001300
#                                                                       00001400
#  $01=PYQ0049,  HOT7705, 010130, PDJP: Correct paths and remove        00001500
#        unsupported services (FIN APAR OW45915                         00001600
#                                                                       00001700
# Services can be added and deleted by deleting or inserting a          00001800
# comment character (ie. #) at the beginning of a line                  00001900
#                                                                       00002000
#====================================================================== 00002100
# service | socket | protocol | wait/ | user | server  | server program 00002200
# name    | type   |          | nowait|      | program |   arguments    00002300
#====================================================================== 00002400
#                                                                       00002500
otelnet  stream tcp nowait OMVSKERN /usr/sbin/otelnetd otelnetd -l      00002600
#sh      stream tcp nowait OMVSKERN /usr/sbin/sshd sshd -i                      
shell    stream tcp nowait OMVSKERN /usr/sbin/orshd orshd -LV           00002700
login    stream tcp nowait OMVSKERN /usr/sbin/rlogind rlogind -m        00002800
exec     stream tcp nowait OMVSKERN /usr/sbin/orexecd orexecd -LV       00002900