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>)]

where:

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

Based on the object to be read, you can specify one of the following parameter combinations:

/<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).; 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 the initial request to the resource, you can omit this header.

Note:

If this header is used with very large data sets then performance may be impacted since the data set may have to be read twice by the system. This header is ignored if X-IBM-Record-Range is specified (see below). The ETag response header may be returned containing a hash string. See X-IBM-Return-Etag for details on whether this header will be present. End of change

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

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

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).; When EEE is set to 0, records through the end of the data set are retrieved.; When SSS is omitted (i.e. -EEE), the final EEE records of the data set are retrieved.
SSS,NNN: Where SSS identifies the start record and NNN identifies the number of records to be retrieved.; NNN must be greater than zero.
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.; If X-IBM-Record-Range header is present on the request, then header X-IBM-Return-Etag=true may not be specified.; If no records are found in the range specified, an exception is returned.

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.

EXCL: 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/EXCL ENQ will be held on the data set, including the member name if this is a request for a PDS member.

A successful response will include an X-IBM-Session-Ref response header that can be added as a request header to subsequent requests to specify affinity to the TSO address space holding this ENQ.

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: xxxxxx

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

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

In the following example, the GET method is used to retrieve the contents of the member SMFPRM00 in data set SYS1.PARMLIB.

GET /zosmf/restfiles/ds/SYS1.PARMLIB(SMFPRM00) 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.

A sample response header is shown in Figure 1.

Figure 1. Example: Returned contents of the SMFPRM00 member of sys1.parmlib

200 OK
Etag:  B5C6454F783590AA8EC15BD88E29EA63
Content-Type:  text/plain; charset=UTF-8
Content-Language:  en-US
Content-Length:  1944
Date:  Fri, 07 Nov 2014 02:13:07 GMT
Connection: close

A sample response body is shown in Figure 2.

Figure 2. Example: Returned contents of the SMFPRM00 member of sys1.parmlib

  ACTIVE                       /*ACTIVE SMF RECORDING*/              00010000 
  DSNAME(SYS1.&SMFDSN1,SYS1.&SMFDSN2,    /*SMF ON 3390        */     00020000 
   SYS1.&SMFDSN3)                    /*FT: SYSAQ3, TS: SYSAQ4 */     00030000 
  NOPROMPT                     /*PROMPT THE OPERATOR FOR OPTIONS*/   00040000 
  REC(PERM)                    /*TYPE 17 PERM RECORDS ONLY*/         00050000 
  MAXDORM(3000)               /* WRITE AN IDLE BUFFER AFTER 30 MIN*/ 00060000 
  MEMLIMIT(256M)              /* 256M FOR 64 BIT APPS             */ 00061005 
  STATUS(003000)              /* WRITE SMF STATS AFTER HALF HOUR*/   00070000 
  JWT(0700)                   /* INVOKE EXIT IEFUTL AFTER  7HR 00M*/ 00080002 
  SID(&SYSNAME),              /* SYSTEM ID FOR 3084 - SINGLE IMAGE*/ 00090000 
  LISTDSN                     /* LIST DATA SET STATUS AT IPL*/       00100000 
  INTVAL(30)                  /* INTVAL OPTION SP430 */              00110000 
  SYNCVAL(00)                 /* SYNCVAL OPTION SP430  */            00120000 
  SYS(NOTYPE(19,40,92),                                              00130001 
   EXITS(IEFU83,IEFU84,IEFACTRT,IEFUJV,IEFUJI,                       00140000 
             IEFUSI,IEFUTL,IEFU29),INTERVAL(010000),DETAIL)          00150000 
                                                                     00160000 
  /* WRITE ALL RECORDS AS THE SYSTEM DEFAULT, TAKE ALL KNOWN         00170000 
     EXITS, NOTE: JES EXITS CONTROLED BY JES , THERE IS NO           00180000 
     DEFAULT INTERVAL RECORDS WRITTEN AND ONLY SUMMARY T32           00190000 
     RECORDS AS A DEFAULT FOR TSO */                                 00200000 
                                                                     00210000 
  SUBSYS(STC,NOTYPE(19,40,92),                                       00220001 
   EXITS(IEFU29,IEFU83,IEFU84,IEFUTL),                               00230000 
   INTERVAL(SMF,SYNC),DETAIL)           /*SP430*/                    00240000 
                                                                     00250000 
  /* WRITE ALL RECORDS AS BY  SYSTEM DEFAULT, TAKE ONLY THREE        00260000 
     EXITS, NOTE: IEFU29 EXECUTES IN THE MASTER ASID WHICH IS A      00270000 
     STC ADDRESS SPACE SO IEFU29 MUST BE ON FOR STC. USE ALL OTHER   00280000 
     SYS PARAMETERS AS A DEFAULT  */                                 00290000

Example request

In the following example, the GET method is used to retrieve the contents of a sequential data set.

GET /zosmf/restfiles/ds/JIAHJ.REST.SRVMP HTTP/1.1

Example response

A sample response body is shown in Figure 3.

Figure 3. Example: Retrieve the contents of a sequential data set

Response

200 OK
X-Powered-By:  Servlet/3.0
Content-Type:  text/plain; charset=UTF-8
Content-Length:  2131
Etag: 47029CDDCD91E2887E1FAAD6FCD75ECB
Content-Language:  en-US
Date:  Wed, 25 Nov 2015 02:27:15 GMT

Response Body

//JH2FPROC EXEC PGM=IKJEFT01,DYNAMNBR=200
//****************************************************************/
//* TSO LOGON PROC FOR Z/OS DATA SET AND FILE REST INTERFACE  */
//*                             */
//* PROPRIETARY STATEMENT:                   */
//*                             */
//*     LICENSED MATERIALS - PROPERTY OF IBM        */
//*     5610-A01                      */
//*     COPYRIGHT IBM CORP. 2014            */
//*     STATUS = HSMA210                  */
//****************************************************************/
//CEEOPTS  DD *
DYNDUMP(*USERID.PRIVATE)
//SYSEXEC  DDDISP=SHR,DSN=ISP.SISPEXEC
//    DD DISP=SHR,DSN=SYS1.SBPXEXEC
//SYSPROC  DD DISP=SHR,DSN=ISP.SISPCLIB
//    DD DISP=SHR,DSN=SYS1.SBPXEXEC
//ISPLLIB  DD DISP=SHR,DSN=JIAHJ.REST.LMOD
//ISPPLIB  DD DISP=SHR,DSN=ISP.SISPPENU
//ISPTLIB  DD RECFM=FB,LRECL=80,SPACE=(TRK,(1,0,1))
//    DD DISP=SHR,DSN=ISP.SISPTENU
//ISPSLIB  DD DISP=SHR,DSN=ISP.SISPSENU
//ISPMLIB  DD DISP=SHR,DSN=ISP.SISPMENU
//ISPPROF DD DISP=NEW,UNIT=SYSDA,SPACE=(TRK,(15,15,5)),
//    DCB=(RECFM=FB,LRECL=80,BLKSIZE=3120)
//IZUSRVMP DD DISP=SHR,DSN=JIAHJ.REST.PARMLIB(IZUSRVMP)
//SYSOUT   DD SYSOUT=H
//CEEDUMP  DD SYSOUT=H
//SYSUDUMP DD SYSOUT=H
//