Retrieve the contents of a job spool file

You can use this operation to retrieve the contents of a job spool file on z/OS. Also, you can use this service to retrieve the JCL that was used to submit the job.

HTTP method and URI path

GET /zosmf/restjobs/jobs/<jobname>/<jobid>/files/<nnn>/records
GET /zosmf/restjobs/jobs/<correlator>/files/<nnn>/records
GET /zosmf/restjobs/jobs/<jobname>/<jobid>/files/JCL/records
GET /zosmf/restjobs/jobs/<correlator>/files/JCL/records

where:

/zosmf/restjobs/jobs/ identifies the z/OS® jobs REST interface.
<jobname>/<jobid> identifies the job to be used for the request. Use either the job name and job ID combination or the job correlator to identify the job.
<correlator> identifies the job to be used for the request. Use either the job name and job ID combination or the job correlator to identify the job.
To use a job correlator on this request, specify the full job correlator for the job: The 31-byte system portion, a semicolon, and the user portion (up to 32 bytes). The correlator can be one that you have obtained from the "job-correlator" property in a returned JSON job document. Alternatively, you can specify the complete URL as provided in the "url" property of a JSON job document.
/files<nnn>/records indicates that the request is to retrieve the contents of a job spool file for the specified job. The <nnn> parameter is the ID for the spool file from which the contents are to be retrieved.
/files/JCL/records indicates that the request is to retrieve the JCL for the specified job.

Custom headers

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

X-IBM-Record-Range

Use this header to retrieve a range of records from a spool 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 spool file are retrieved.
SSS,NNN: where SSS identifies the start record and NNN identifies the number of records to be retrieved.

For an example of how this custom header is used, see Examples.

Query parameters

You can specify translation for the returned data through the mode parameter. The following values are valid for mode:

text: The z/OS jobs REST interface translates records from the server codepage to the client codepage and returns the records with Content-Type: plain/text. Trailing spaces are removed and newline characters are used as record separators. This value is the default if you omit the mode parameter.
binary: The z/OS jobs REST interface performs no translation and returns the records with Content-Type: application/octet-stream.
record: The z/OS jobs REST interface performs no translation and returns the records with Content-Type: application/octet-stream. The z/OS jobs REST interface prefixes each record with a 4-byte (big endian) length.

Specifying the mode parameter with any other value, or no value, results in the default: mode=text.

Required authorizations

See Required authorizations.

In addition, your user ID requires READ access to the JESSPOOL profile for the spool data set. If no profile exists, only the user who created the spool data set can access, modify, or delete it. For information about spool data set security considerations, see z/OS JES Application Programming.

Usage considerations

See Usage considerations for the z/OSMF REST services.

In addition, observe the following considerations for this request:

The response does not include the Content-Length header. Because the server streams the data rather than buffering it in memory, it is usually not possible for the server to determine the total content length of the data before completing the transfer. For similar reasons, the response does not include the Content-Range header, either.
This request can be directed to a secondary JES subsystem. To do so, use the following URL format:
```
https://host:port/zosmf/restjobs/jobs/-JESB/jobname/jobid/filesJCL/records
```
where JESB is the name of the secondary JES subsystem. A request to a secondary JES subsystem must include the job name and job id, rather than a job correlator.

Expected response

On completion, the z/OS jobs REST interface returns an HTTP response with content type defined by the mode query parameter.

For errors, z/OS jobs REST interface returns an appropriate HTTP status code and error information as a JSON error report document. See Error report document.

Examples

In the following example, the GET method is used to retrieve the contents of spool file 1 for the job TESTJOBJ, job ID JOB00023:

GET /zosmf/restjobs/jobs/TESTJOBJ/JOB00023/files/1/records HTTP/1.1
Host: zosmf1.yourco.com

A sample response is shown in Figure 1.

Figure 1. Example: Returned spool file content

HTTP/1.1 200 OK

Date: Thu, 17 Jan 2013 05:39:28 +0000GMT
Content-Type: text/plain
Connection: close

                  J E S 2 J O B L O G -- S Y S T E M E I M G  -- N O D E  D C E I M G W V 
                                                                                                  
15.49.11 JOB00239 ---- MONDAY,    14 JAN 2013 ----                                                
15.49.11 JOB00239  IRR010I  USERID IBMUSER  IS ASSIGNED TO THIS JOB.                              
15.49.11 JOB00239  ICH70001I IBMUSER  LAST ACCESS AT 15:48:25 ON MONDAY, JANUARY 14, 2013         
15.49.11 JOB00239  $HASP373 INSTALL  STARTED - INIT 2    - CLASS A - SYS EIMG                     
15.49.11 JOB00239  IEF403I INSTALL - STARTED - TIME=15.49.11                                      
15.49.16 JOB00239  IEF404I INSTALL - ENDED - TIME=15.49.16                                        
15.49.16 JOB00239  $HASP395 INSTALL  ENDED                                                        
------ JES2 JOB STATISTICS ------                                                                 
  14 JAN 2013 JOB EXECUTION DATE                                                                  
           71 CARDS READ                                                                          
          287 SYSOUT PRINT RECORDS                                                                
            0 SYSOUT PUNCH RECORDS                                                                
           13 SYSOUT SPOOL KBYTES                                                                 
         0.08 MINUTES EXECUTION TIME

In the following example, the GET method is used to retrieve a range of records (the first 250) using the X-IBM-Record-Range custom header:

GET /zosmf/restjobs/jobs/TESTJOBJ/JOB00023/files/8/records HTTP/1.1
X-IBM-Record-Range: 0-249

A sample response is shown in Figure 2.

Figure 2. Example: Returned spool file content (a range of records)

HTTP/1.1 200 OK

Date: Thu, 17 Jan 2013 05:39:28 +0000GMT
Content-Type: text/plain
Connection: close

...(the first 250 records)

In the following example, the GET method is used to retrieve the JCL for the job TESTJOBJ, job ID JOB00060:

GET /zosmf/restjobs/jobs/TESTJOBJ/JOB00060/files/JCL/records HTTP/1.1

A sample response is shown in Figure 3.

Figure 3. Example: Returned job content (the job JCL)

HTTP/1.1 200 OK

//TESTJOBJ JOB (),MSGCLASS=H
// EXEC PGM=IEFBR14