Obtain the status of a job

You can use this operation to obtain the status of a batch job on z/OS®.

HTTP method and URI path

GET /zosmf/restjobs/jobs/<jobname>/<jobid>?[step-data=Y|N]         
GET /zosmf/restjobs/jobs/<correlator>?[step-data=Y|N]

where:

/zosmf/restjobs/jobs/ identifies the z/OS jobs REST interface.
<jobname>/<jobid> identifies the job for which status is requested. Use either the job name and job ID combination or the job correlator to identify the job.
<correlator> identifies the job for which status is requested. 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.
[step-data] is an optional parameter that indicates whether the service will return information about each step in the job that has completed, such as the step name, step number, and completion code. To return the step data for completed steps, set the value for this parameter to Y. Otherwise, omit the parameter or set its value to N (default). Note that if a step is run multiple times, duplicate data for that step might be included in the response.

Custom headers

None.

Query parameters

None.

Required authorizations

See Required authorizations.

Usage considerations

See Usage considerations for the z/OSMF REST services.

In addition, note that 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

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 a JSON job document. For the contents, see Job document.

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.

Example request

The following request obtains the status for the job BLSJPRMI, job ID STC00052:

GET /zosmf/restjobs/jobs/BLSJPRMI/STC00052 HTTP/1.1
Host: zosmf1.yourco.com

Example responses

A sample response is shown in Figure 1.

Figure 1. Example: Returned job status

HTTP/1.1 200 OK
Date: Thu, 09 Dec 2014 05:39:28 +0000GMT
Content-Type: application/json
Connection: close

{
  "jobid":"STC00052",
  "jobname":"BLSJPRMI",
  "subsystem":"JES2",
  "owner":"IBMUSER",
  "status":"OUTPUT",
  "type":"STC",
  "class":"STC",
  "retcode":"CC 0000",
  "url":"https:\/\/host:port\/zosmf\/restjobs\/jobs\/S0000052SY1.....CE35BDE8.......%3A",
  "files-url":"https:\/\/host:port\/zosmf\/restjobs\/jobs\/S0000052SY1.....CE35BDE8.......%3A\/files",
  "job-correlator":"S0000052SY1.....CE35BDE8.......:",
  "phase":20,
  "phase-name":"Job is on the hard copy queue"
}

A sample response for an active step is shown in Figure 2.

Figure 2. Example: Returned status for an active step

HTTP/1.1 200 OK
Date: Thu, 09 Dec 2014 05:39:28 +0000GMT
Content-Type: application/json
Connection: close

{
  "retcode": "null",
  "jobname": "BLSJPRMI",
  "status": "ACTIVE",
  "job-correlator": "S0000052SY1.....CE35BDE8.......:",
  "class": "STC",
  "type": "STC",
  "jobid": "STC00052",
  "url": "https:\/\/pev182.pok.ibm.com:443\/zosmf\/restjobs\/jobs\/S0000052SY1.....CE35BDE8.......%3A",
  "phase-name": "Job is on the hard copy queue",
  "step-data": [
    {
      "smfid": "SP21",
      "active": true,
      "step-number": 1,
      "proc-step-name": "STARTING",
      "step-name": "IEFPROC ",
      "program-name": "BLSQPRMI"
    }
  ],
  "owner": "IBMUSER",
  "subsystem": "JES2",
  "files-url": "https:\/\/pev182.pok.ibm.com:443\/zosmf\/restjobs\/jobs\/S0000052SY1.....CE35BDE8.......%3A\/files",
  "phase": 20
}