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
- /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
- 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 andEEE
identifies the end record to be retrieved. Both values are relative offsets (0-based). WhenEEE
is set to 0, records through the end of the spool file are retrieved. - SSS,NNN
- where
SSS
identifies the start record andNNN
identifies the number of records to be retrieved.
For an example of how this custom header is used, see Examples.
Query parameters
- 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
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.
- 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
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
GET /zosmf/restjobs/jobs/TESTJOBJ/JOB00023/files/1/records HTTP/1.1
Host: zosmf1.yourco.com
GET /zosmf/restjobs/jobs/TESTJOBJ/JOB00023/files/8/records HTTP/1.1
X-IBM-Record-Range: 0-249
GET /zosmf/restjobs/jobs/TESTJOBJ/JOB00060/files/JCL/records HTTP/1.1