List the jobs for an owner, prefix, or job ID
You can use this operation to list the jobs for an owner, prefix, or job ID.
HTTP method and URI path
GET /zosmf/restjobs/jobs[?<parms>]
- /zosmf/restjobs/jobs/ identifies the z/OS® jobs REST interface.
- <parms> are optional parameters that you can use to qualify the request. For a list of the supported parameters, see Query parameters.
Custom headers
None.
Query parameters
- owner
- User ID of the job owner whose jobs are being queried; the default is the z/OS user ID. Folded to uppercase; cannot exceed eight characters.
- prefix
- Job name prefix; defaults is *. Folded to uppercase; cannot exceed eight characters.
- jobid
- Job ID. Folded to uppercase; cannot exceed eight characters. This query parameter is mutually exclusive with user-correlator.
- max-jobs
- Maximum number of jobs returned. The value must be between 1 and 1000, inclusive. If this parameter is not specified, or is specified incorrectly, the default value of 1000 is used.
- user-correlator
- The user portion of the job correlator. This value is 1 – 32 characters
in length, where the first character must be uppercase alphabetic
(A-Z) or special ($, #, @). The remaining characters (up to 31) can
be any combination of uppercase alphabetic, numeric (0-9), or special.
Blank characters are not supported.
This query parameter is mutually exclusive with jobid.
This value is processed by the JES2 subsystem only; the JES3 subsystem does not process the correlator and, instead, indicates zero job matches. For a system with JES3 as the primary subsystem, and one or more JES2 secondary subsystems, the primary JES3 subsystem does not process the correlator, however, the JES2 secondary subsystems can process the correlator.
- Query parameters are optional; you can specify one or more query parameters, as needed.
- You use a question mark (?) to separate the first query parameter from the resource.
- To specify multiple query parameters in combination, use an ampersand (&).
- Wildcard characters are permitted in the owner and prefix query parameter values. Use an asterisk (*) for multiple characters, and a question mark (?) for a single character.
Required authorizations
Usage considerations
See Usage considerations for the z/OSMF REST services.
- The ordering of the jobs returned is not predictable.
- If the maximum number of jobs is returned, no indication is provided for whether more jobs remain to be retrieved.
- This request can be directed to a secondary JES subsystem. To
do so, use the following request format: where JESB is the name of the secondary JES subsystem in these examples.
https://host:port/zosmf/restjobs/jobs/-JESB https://host:port/zosmf/restjobs/jobs/-JESB?owner=owner
- To list the jobs for a job ID on a secondary JES subsystem, you
must specify the job id, rather than a job correlator. For example:
https://host:port/zosmf/restjobs/jobs/-JESB?jobid=jobid
Expected response
On completion, the z/OS jobs REST interface returns an HTTP response with an array of matching jobs, each as 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
GET /zosmf/restjobs/jobs?owner=IBMUSER&prefix=TESTJOB* HTTP/1.1
Host: zosmf1.yourco.com
Example response
HTTP/1.1 200 OK
Date: Fri, 17 Jan 2014 05:39:28 +0000GMT
Content-Type: application/json
Connection: close
[
{”jobid”:”JOB00023”,”jobname”:”TESTJOB2”,”subsystem”:null,”owner”:”IBMUSER”,
”status”:”OUTPUT”,”type”:”JOB”,”class”:”A”,”retcode”:”CC 0000”,
"url":"https:\/\/host:port\/zosmf\/restjobs\/jobs\/TESTJOB2\/JOB00023",
"files-url":"https:\/\/host:port\/zosmf\/restjobs\/jobs\/TESTJOB2\/JOB00023\/files"},
{”jobid”:”JOB00024”,”jobname”:”TESTJOB3”,”subsystem”:null,”owner”:”IBMUSER”,
”status”:”OUTPUT”,”type”:”JOB”,”class”:”A”,”retcode”:”ABEND S000”,
"url":"https:\/\/host:port\/zosmf\/restjobs\/jobs\/TESTJOB3\/JOB00024",
"files-url":"https:\/\/host:port\/zosmf\/restjobs\/jobs\/TESTJOB3\/JOB00024\/files"}
]