Query Job Status
The Query Job Status operation returns the status associated with an asynchronous job. This operation is supported using the BCPii interface and is the only mechanism to obtain information for asynchronous jobs.
HTTP method and URI
GET /api/jobs/{job-id}In this request, the URI variable {job-id} is the identifier of an asynchronous job associated with the API user, as returned in the response of the operation that initiated the job.
Response body contents
On successful completion, the response body is a JSON object with the following fields:
| Field name | Type | Description |
|---|---|---|
| status | String Enum | An indication of the current disposition of the job. The possible values are
as follows:
|
| job-status-code | Integer; Field provided only if status is "complete" or "canceled" | The job completion status code. This field is provided only if the
status field is set to "complete" or "canceled". This field provides the major status code describing the success or failure completion of the asynchronous action represented by the job. It is expressed in terms of an HTTP status code (i.e. the HTTP status code that would have been returned for the operation had it been performed synchronously). The values provided here and their meaning depend on the particular action that is being performed asynchronously. The description of these values is provided as part of the description for the operation that initiated the asynchronous job. |
| job-reason-code | Integer; Field provided only if status is "complete" or "canceled" | The job completion reason code. This field is provided only if the
status field is set to "complete" or "canceled" and only if the
job-status-code field indicates an error completion (status code other than
2XX). When present, this field provides a more detailed reason code describing the success or failure completion of the asynchronous action represented by the job. It is expressed in terms of the API reason code as are returned in standard error response bodies provided by the API. The values provided here and their meaning depend on the particular action that is being performed asynchronously. The description of these values is provided as part of the description or the operation that initiated the asynchronous job. |
| job-results | Object; Field provided only if status is "complete" or "canceled" | A nested object that provides results
for the job. This field is provided only if the status field is set to "complete" or "canceled" and the asynchronous operation is documented to provide job results. If the status field is set to some other value, or the asynchronous operation provides no result information (beyond the job status and reason codes) then this field is omitted. The structure of the nested object provided by this field and its meaning depends on the particular action that is being performed asynchronously. The description of this object's structure is provided as part of the description of the operation that initiated the asynchronous job. |
Description
The Query Job Status operation returns the status associated with an asynchronous job.
If the job designated by the URI is still running, the operation sets the status field in the response body to "running" and provides no other information about the job. If cancellation has been requested for the job designated by the URI but the cancellation action has not yet caused the job to end, the operation sets the status field in the response body to "cancel-pending" and provides no other information about the job. The client application may repeat the query at a later time, but should avoid frequent polling since that can lead to unproductive use of client and HMC resources. In order to eliminate the need to poll at all, the client application can (and should) use the asynchronous notifications facility provided by the API to receive notification that the job has ended through a JMS-based message or SSE-based event. See Job completion notification for details on the JMS notification mechanism , or Job completion notification for SSE.
If the job is complete, the operation sets the status field in the response body to "complete" and provides the other completion-related fields defined in the response body contents section above to report the results to the client application. If the job's normal execution sequence was interrupted by a cancel action, the operation sets the status field in the response body to "canceled" and provides the other related fields defined in the Response body contents to report the results to the client application. Once a job ends, job status is retained by the HMC for a minimum of 4 hours to allow the client application time to retrieve the results, but this status and results are not held indefinitely.
If the URI does not designate a job associated with the API user, HTTP status code 404 (Not Found) is returned to the client.
Authorization requirements
- The job URI must designate an asynchronous job associated with the API user or for the BCPii interface the requesting partition.
HTTP status and reason codes
On success, HTTP status code 200 (OK) is returned and the response body is provided as described in Response body contents.
The following HTTP status codes are returned for the indicated operation-specific errors, and the response body is a standard error response body providing the reason code indicated and associated error message.
| HTTP error status code | Reason code | Description |
|---|---|---|
| 400 (Bad Request) | Various | Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes. |
| 2 | For a job that was initiated using the BCPii interface the request does not contain or contains an invalid X-API-Target-Name header value. | |
| 404 (Not Found) | 1 | The URI does not designate an asynchronous job associated with the API user. |
Additional standard status and reason codes can be returned, as described in Invoking API operations.
Example HTTP interaction
GET /api/jobs/86e44546-107f-11e1-bde0-0010184c8334 HTTP/1.1
x-api-session: 2ltfe2c2q3ti2b2pwq1wfwuzifoi4rymqa8ktzjep7dbyrll0k200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 16 Nov 2011 18:19:35 GMT
content-type: application/json;charset=UTF-8
content-length: 63
{
"job-reason-code": 0,
"job-status-code": 200,
"status": "complete"
}