Retrieve Job Status (QWCRJBST) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Job identifier | Input | Char(*) |
| 4 | Format of job identifier | Input | Char(8) |
| 5 | Error Code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Retrieve Job Status (QWCRJBST) API returns status and job identification information about the job that is identified by the job identifier parameter. The QWCRJBST API retrieves this information faster than other APIs. It should be considered for use in performance critical applications where the returned information is required.
Authorities and Locks
None.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.
- Length of receiver variable
- INPUT BINARY(4)
The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.
- Job identifier
- INPUT CHAR(*)
The identifier of the job for which the information is to be retrieved. The job can be identified in one of three ways: job number only, internal job number, or fully qualified job name. The next parameter specifies which format of job identifier is being used.
- Format of job identifier
- INPUT CHAR(8)
The format of the job identifier being provided. The format names that can be used are as follows:
JOBS0100 The job identifier is a 6-character job number. It is possible that more than one job may have the same job number. This API returns the requested information for only the first job that has the specified job number. No indication is returned to show if more than one job has the same job number. JOBS0200 The job identifier is a 16-character internal job number. The internal job number is obtained through the List Job (QUSLJOB) API or as output to this API. JOBS0300 The job identifier is a 26-character fully qualified job name.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of Returned Information
The information returned from this API has the following format:
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Binary(4) | Bytes returned |
| 4 | 4 | Binary(4) | Bytes available |
| 8 | 8 | CHAR(10) | Job status |
| 18 | 12 | CHAR(16) | Internal job identifier |
| 34 | 22 | CHAR(26) | Fully qualified job name |
Field Description
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned.
Fully qualified job name. The fully qualified job name consisting of three parts. The first 10 characters contain the job name. The next 10 characters contain the user name. The last 6 characters contain the job number.
Internal job identifier. A value sent to other APIs to speed the process of locating the job on the system. Only APIs described in this book use this identifier. The identifier is not valid following an initial program load (IPL). If you attempt to use it after an IPL, an exception occurs.
Job status. Possible values that can be returned for job status are as follows:
| *ACTIVE | The job has started, and it can use system
resources (processing unit, main storage, and so on). This does not guarantee
that the job is currently running, however. For example, an active job may be
in one of the following states where it cannot use system resources:
|
| *JOBQ | The job currently is on a job queue. The job may have been previously active and was placed back on the job queue because of the Transfer Job (TFRJOB) command or the Transfer Batch Job (TFRBCHJOB) command, or the job was never active because it was just submitted. |
| *OUTQ | The job has completed running and has spooled output that has not yet printed. |
| *ERROR | Either a job with the specified job identifier does not exist, or an error was encountered while attempting to determine its status. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C20 E | Error found by program &1. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3C51 E | Internal job identifier not valid. |
| CPF3C52 E | Internal job identifier no longer valid. |
| CPF3C53 E | Job &3/&2/&1 not found. |
| CPF3C54 E | Job &3/&2/&1 currently not available. |
| CPF3C55 E | Job &3/&2/&1 does not exist. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V3R6