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.
To identify the job in the request, use either the combination of the job name and
job ID, or the job correlator, as follows:
<jobname>/<jobid> identifies the job for which the spool file
contents are requested.
<correlator> identifies the job for which the spool file contents are
requested. 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 obtained from the
"job-correlator" property in a returned 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 by
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.
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
and X-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. Both
X-IBM-Target-System-Password and X-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
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. Both
X-IBM-Target-System-Password and X-IBM-Target-System-User must be
provided together; otherwise, this header is ignored.
Query parameters
You can specify one or more of the following optional query parameters on this request.
mode
Use the mode parameter to specify conversion options for the returned data. The following values
are valid for mode:
text
The z/OS jobs REST interface converts records from the server code
page to the client code page 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 conversion and returns the
records with Content-Type: application/octet-stream.
record
The z/OS jobs REST interface performs no conversion 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.
When mode=text, the following query parameters can be used to further qualify the
request. These parameters cannot be used when mode is set to record or
binary; doing so results in an error.
fileEncoding
search
research
insensitive
maxreturnsize
These query parameters are described as follows.
fileEncoding=code-page
Specifies an alternative code page (EBCDIC) for the spool file on z/OS; the encoded text is
converted to the client's request encoding. If not specified, the default code page is IBM-1047.
search=<string>
The spool file is searched for the first record that contains the string, without respect to
case (by default). Optionally, insensitive=false can be specified for case-sensitive matching.
This parameter cannot be used with the research parameter.
research=<regular-expression>
The spool file is searched for the first record that matches the given extended regular
expression. For example, research=A|B finds A or B. By default, the search is
case-insensitive. To search for case-sensitive matches, specify the research parameter with the
query parameter insensitive=false.
This parameter cannot be used with the search
parameter.
insensitive=true|false
When 'true', searches (search and research) are case-insensitive. For case-sensitive searches,
specify 'false'. The default is 'true'.
maxreturnsize=<integer>
This parameter can 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 can be used to specify the range of records
to be searched, but it does not restrict the number of records returned (see maxreturnsize).
If no X-IBM-Record-Range request header is present, the search begins with the first
record. In all cases, an X-IBM-Record-Range=p,q response header is 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 is returned.
The parameter cannot be used if the mode query parameter specifies any option except
'text'.
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.
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, the server cannot determine the total content length of the data
before it completes 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:
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 that is 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
To identify the job in the request, use either the combination of the job name and
job ID, or the job correlator, as follows: 