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>]
where:
  • /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

You can specify one or more of the following optional query parameters on this request:
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.

Observe the following conventions:
  • 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

See Required authorizations.

Usage considerations

See Usage considerations for the z/OSMF REST services.

In addition, observe the following considerations for this request:
  • 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: 
    https://host:port/zosmf/restjobs/jobs/-JESB
https://host:port/zosmf/restjobs/jobs/-JESB?owner=owner
    where JESB is the name of the secondary JES subsystem in these examples.

  • 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

In the following example, the GET method is used to list the jobs that are owned by IBMUSER and have a job name prefix beginning with TESTJOB:
GET /zosmf/restjobs/jobs?owner=IBMUSER&prefix=TESTJOB* HTTP/1.1
Host: zosmf1.yourco.com

Example response

A sample response is shown in Figure 1.
Figure 1. Example: Returned list of the jobs for a specific owner and job name prefix
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"}
]
Parent topic: z/OS jobs REST interface