Retrieve Job Queue Information (QSPRJOBQ) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Qualified job queue name | Input | Char(20) |
| 5 | Error Code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Retrieve Job Queue Information (QSPRJOBQ) API retrieves information associated with a specified job queue.
The QSYS2.JOB_QUEUE_INFO view can be used as an alternative to this API. See JOB_QUEUE_INFO view for more information.
Authorities and Locks
- Job Queue Library Authority
- The caller needs *EXECUTE authority to the job queue library.
- Job Queue Authority
- The caller needs one of the following:
- *READ authority to the job queue.
- Job control special authority (*JOBCTL) if the job queue is operator controlled (OPRCTL(*YES)).
- Spool control special authority (*SPLCTL).
- Job Queue Lock
- This API gets an *EXCLRD lock on the job queue.
- Subsystem Description Lock
- This API gets an *EXCLRD lock on the subsystem description.
This API does not check the caller's authority to the subsystem description or subsystem description library when retrieving the subsystem description information.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable that is to receive the information requested.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable provided by the receiver variable parameter. The amount of data returned is truncated if it is too small. A length of less than 8 is not valid.
- Format name
- INPUT; CHAR(8)
The content and format of the queue information being returned. The valid format names are:
JOBQ0100 Basic job queue information. See JOBQ0100 Format to view the information returned for this format. JOBQ0200 Detailed job queue information. See JOBQ0200 Format to view the information returned for this format.
- Qualified job queue name
- INPUT; CHAR(20)
The name of the job queue for which information is returned. The first 10 characters contain the queue name, and the second 10 characters contain the name of the library in which the queue resides.
The following special values are supported for the library name:
*LIBL The library list used to locate the job queue. *CURLIB The current library for the job is used to locate the job queue.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
JOBQ0100 Format
The following table shows the information returned for the JOBQ0100 format. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | Job queue name |
| 18 | 12 | CHAR(10) | Job queue library name |
| 28 | 1C | CHAR(10) | Operator controlled |
| 38 | 26 | CHAR(10) | Authority to check |
| 48 | 30 | BINARY(4) | Number of jobs |
| 52 | 34 | CHAR(10) | Job queue status |
| 62 | 3E | CHAR(10) | Subsystem name |
| 72 | 48 | CHAR(50) | Text description |
| 122 | 7A | CHAR(10) | Subsystem library name |
| 132 | 84 | BINARY(4) | Sequence number |
| 136 | 88 | BINARY(4) | Maximum active |
| 140 | 8C | BINARY(4) | Current active |
JOBQ0200 Format
The following table shows the information returned for the JOBQ0200 format. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | Job queue name |
| 18 | 12 | CHAR(10) | Job queue library name |
| 28 | 1C | CHAR(10) | Operator controlled |
| 38 | 26 | CHAR(10) | Authority to check |
| 48 | 30 | BINARY(4) | Number of jobs |
| 52 | 34 | CHAR(10) | Job queue status |
| 62 | 3E | CHAR(10) | Subsystem name |
| 72 | 48 | CHAR(10) | Subsystem library name |
| 82 | 52 | CHAR(50) | Text description |
| 132 | 84 | BINARY(4) | Sequence Number |
| 136 | 88 | BINARY(4) | Maximum active |
| 140 | 8C | BINARY(4) | Current active |
| 144 | 90 | BINARY(4) | Maximum active jobs with priority 1 |
| 148 | 94 | BINARY(4) | Maximum active jobs with priority 2 |
| 152 | 98 | BINARY(4) | Maximum active jobs with priority 3 |
| 156 | 9C | BINARY(4) | Maximum active jobs with priority 4 |
| 160 | A0 | BINARY(4) | Maximum active jobs with priority 5 |
| 164 | A4 | BINARY(4) | Maximum active jobs with priority 6 |
| 168 | A8 | BINARY(4) | Maximum active jobs with priority 7 |
| 172 | AC | BINARY(4) | Maximum active jobs with priority 8 |
| 176 | B0 | BINARY(4) | Maximum active jobs with priority 9 |
| 180 | B4 | BINARY(4) | Active jobs with priority 0 |
| 184 | B8 | BINARY(4) | Active jobs with priority 1 |
| 188 | BC | BINARY(4) | Active jobs with priority 2 |
| 192 | C0 | BINARY(4) | Active jobs with priority 3 |
| 196 | C4 | BINARY(4) | Active jobs with priority 4 |
| 200 | C8 | BINARY(4) | Active jobs with priority 5 |
| 204 | CC | BINARY(4) | Active jobs with priority 6 |
| 208 | D0 | BINARY(4) | Active jobs with priority 7 |
| 212 | D4 | BINARY(4) | Active jobs with priority 8 |
| 216 | D8 | BINARY(4) | Active jobs with priority 9 |
| 220 | DC | BINARY(4) | Released jobs on queue with priority 0 |
| 224 | E0 | BINARY(4) | Released jobs on queue with priority 1 |
| 228 | E4 | BINARY(4) | Released jobs on queue with priority 2 |
| 232 | E8 | BINARY(4) | Released jobs on queue with priority 3 |
| 236 | EC | BINARY(4) | Released jobs on queue with priority 4 |
| 240 | F0 | BINARY(4) | Released jobs on queue with priority 5 |
| 244 | F4 | BINARY(4) | Released jobs on queue with priority 6 |
| 248 | F8 | BINARY(4) | Released jobs on queue with priority 7 |
| 252 | FC | BINARY(4) | Released jobs on queue with priority 8 |
| 256 | 100 | BINARY(4) | Released jobs on queue with priority 9 |
| 260 | 104 | BINARY(4) | Scheduled jobs on queue with priority 0 |
| 264 | 108 | BINARY(4) | Scheduled jobs on queue with priority 1 |
| 268 | 10C | BINARY(4) | Scheduled jobs on queue with priority 2 |
| 272 | 110 | BINARY(4) | Scheduled jobs on queue with priority 3 |
| 276 | 114 | BINARY(4) | Scheduled jobs on queue with priority 4 |
| 280 | 118 | BINARY(4) | Scheduled jobs on queue with priority 5 |
| 284 | 11C | BINARY(4) | Scheduled jobs on queue with priority 6 |
| 288 | 120 | BINARY(4) | Scheduled jobs on queue with priority 7 |
| 292 | 124 | BINARY(4) | Scheduled jobs on queue with priority 8 |
| 296 | 128 | BINARY(4) | Scheduled jobs on queue with priority 9 |
| 300 | 12C | BINARY(4) | Held jobs on queue with priority 0 |
| 304 | 130 | BINARY(4) | Held jobs on queue with priority 1 |
| 308 | 134 | BINARY(4) | Held jobs on queue with priority 2 |
| 312 | 138 | BINARY(4) | Held jobs on queue with priority 3 |
| 316 | 13C | BINARY(4) | Held jobs on queue with priority 4 |
| 320 | 140 | BINARY(4) | Held jobs on queue with priority 5 |
| 324 | 144 | BINARY(4) | Held jobs on queue with priority 6 |
| 328 | 148 | BINARY(4) | Held jobs on queue with priority 7 |
| 332 | 14C | BINARY(4) | Held jobs on queue with priority 8 |
| 336 | 150 | BINARY(4) | Held jobs on queue with priority 9 |
Field Descriptions
Active jobs with priority 0 through 9. The number of jobs that are active for each priority level (0 through 9). If the subsystem name and subsystem library name are blank, then this field is 0.
Authority to check. Whether the user must be the owner of the queue in order to control the queue by holding or releasing the queue. The possible values are:
| *OWNER | Only the owner of the job queue can control the queue. |
| *DTAAUT | Any user with *READ, *ADD, or *DELETE authority to the job queue can control the queue. |
Bytes available. Total format data length.
Bytes returned. Length of the data returned.
Current active. The current number of jobs that are active that came through this job queue entry.
Held jobs on queue with priority 0 through 9. The number of jobs currently sitting on the job queue in *HELD status for each priority level (0 through 9).
Job queue library name. The name of the library that contains the job queue.
Job queue name. The name of the job queue.
Job queue status. The status of the job queue. The status may be one of the following values:
| RELEASED | The queue is released. |
| HELD | The queue is held. |
Maximum active. The maximum number of jobs that can be active at the same time through this job queue entry. A -1 in this field indicates that the value is *NOMAX.
Maximum active jobs with priority 1 through 9. The maximum number of jobs that can be active at the same time for each priority level (1 through 9). A -1 in this field indicates that the value is *NOMAX. If the subsystem name and subsystem library name are blank, then this field is 0.
Number of jobs. The number of jobs in the queue.
Operator controlled. Whether a user who has job control authority is allowed to control this job queue and manage the jobs on the queue.
| *YES | Users with job control authority can control the queue and manage the jobs on the queue. |
| *NO | This queue and its jobs cannot be controlled by users with job control authority unless they also have other special authority. |
Released jobs on queue with priority 0 through 9. The number of jobs currently sitting on the job queue in *RELEASED status for each priority level (0 through 9).
Scheduled jobs on queue with priority 0 through 9. The number of jobs currently sitting on the job queue in *SCHEDULED status for each priority level (0 through 9).
Sequence number. The job queue entry sequence number. The subsystem uses this number to determine the order in which job queues are processed. Jobs from the queue with the lowest sequence number are processed first.
Subsystem name. The name of the subsystem that can receive jobs from this job queue. If there is no name, then this queue is not associated with an active subsystem, and no job can be processed.
Subsystem library name. The library in which the subsystem description resides. If there is no name, then this queue is not associated with with an active subsystem and no job can be processed.
Text description. Text that briefly describes the job queue.
| *BLANK | There is no text description of the job queue. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF1608 E | Subsystem description &1 not found. |
| CPF2207 E | Not authorized to use object &1 in library &3 type *&2. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3307 E | Job queue &1 in &2 not found. |
| CPF3330 E | Necessary resource not available. |
| CPF8121 E | &8 damage on job queue &4 in library &9. |
| CPF8122 E | &8 damage on library &4. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R2