Open List of Job Queues (QSPOLJBQ) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format of receiver variable | Input | Char(8) |
| 4 | List information | Output | Char(80) |
| 5 | Filter information | Input | Char(*) |
| 6 | Sort information | Input | Char(*) |
| 7 | Number of records to return | Input | Binary(4) |
| 8 | Error Code | I/O | Char(*) |
Threadsafe: Yes
Default Public Authority: *USE
The Open List of Job Queues (QSPOLJBQ) API generates a list of job queues on the system. The list can include all job queues on the system, all job queues for a specified library list, the allocated job queues for a specified active subsystem, or the defined job queues for a specified active subsystem (this would include both the allocated job queues and the job queues the subsystem could not allocate), or all the allocated job queues for all the active subsystems. The filtered list can then be sorted depending on the value of the sort parameter. When requesting job queue information for all job queues on the system or for a specific job queue within a library, if the signed-on user is not authorized to the library of the job queue, information for that job queue in not returned by this API. When requesting the job queue information for job queues defined to an active subsystem, all job queue information will be returned with out regard to the users authority to the subsystem. Upon successful completion of this API, a handle is returned in the list information parameter. You may use this handle on subsequent calls to the following APIs:
- Get List Entries (QGYGTLE)
- Find List Entry (QGYFNDE)
- Close List (QGYCLST)
Performance Impacts
Sorting on one or more values of job queue name, job queue library name, job queue status, subsystem name, subsystem library name, number of jobs on job queue, sequence number, maximum active, current active or description takes more processing power and time.
Authorities and Locks
- Job Queue Library Authority
- *EXECUTE
- 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 used to return the job queue information.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable.
- Format of receiver variable
- INPUT; CHAR(8)
The format of the job queue information being returned. You can specify the following:
OJBQ0100 Contains the basic information about the job queue. For more information about the OJBQ0100 format, see Format of Receiver Variable.
- List information
- OUTPUT; CHAR(80)
Information about the list created by this program. For a description of the layout of this parameter, see Open list information format.
- Filter information
- INPUT; CHAR(*)
The information in this parameter is used for filtering the list of job queue information. For more information about the filter information, see Filter Information.
- Sort information
- INPUT; CHAR(*)
Information on what fields within the record of information to sort. See Format of Sort Information for a description of the layout of this parameter. Note that when sorting is requested, the entire list has to be built and sorted before any records can be returned.
- Number of records to return
- INPUT; BINARY(4)
The number of records in the list to put into the receiver variable.
If -1 is specified for this parameter, the entire list is built synchronously.
If 0 is specified for this parameter, the entire list is built asynchronously in a server job.
If a positive number of records to return is specified, at least that many records are built synchronously and the remainder are built asynchronously in a server job.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Filter Information
The following table shows the format of the filter information parameter. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of filter information |
| 4 | 4 | CHAR(10) | Job queue name |
| 14 | E | CHAR(10) | Job queue library name |
| 24 | 18 | CHAR(10) | Active subsystem name |
| 34 | 22 | CHAR(*) | Reserved |
Format of Sort Information
For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of keys to sort on |
| Offsets vary. These fields repeat for each sort key field. | BINARY(4) | Sort key field starting position | |
| BINARY(4) | Sort key field length | ||
| BINARY(2) | Sort key field data type | ||
| CHAR(1) | Sort order | ||
| CHAR(1) | Reserved | ||
Note: If the last three fields (sort key field data type, sort order, and the reserved field) are not used, then they must be set to hexadecimal zeros. This causes all the data to be treated as character data, and it is sorted in ascending order.
Field Descriptions
Active subsystem name. The active subsystem name whose job queue information is to be returned. A simple active subsystem name or one of the following special values may be specified.
| simple name | A simple name of an active subsystem. The job queue name field must be set to special value *ALLOCATED or *DEFINED. |
| *ALL | All allocated job queues for all active subsystems on the system are returned. The Job queue name field must be set to the special value *ALLOCATED. |
| blanks | The active subsystem name field is ignored. Only the job queue name field is used. |
If the active subsystem field is used, the job queue name field must be set to the correct special value and the job queue library name field must be set to blanks.
Job queue name. The job queue about which to retrieve information. A simple job queue name, a generic job queue name, or a special value may be specified.
The following values require the active subsystem name field to be blank.
| simple name | A simple name of a job queue. |
| generic name | A generic name for job queues. |
| *ALL | All job queues are returned. |
When the active subsystem name field is set to a simple subsystem name, then one of the following special values must be used:
| *ALLOCATED | Only the job queues that have been allocated by the active subsystem are returned. |
| *DEFINED | The job queues that are defined to the active subsystem. This includes the job queues that have been allocated by the subsystem. |
When the active subsystem name field is set to *ALL, the following special value must be used:
| *ALLOCATED | Only the job queues that have been allocated by the active subsystem name are returned. |
Job queue library name. The library in which the job queue is located. A specific library name or a special value may be specified.
The following values apply only when the job queue name field is set to a simple job queue name, a generic job queue name, or the special value *ALL.
| simple name | A simple name of a library. |
| *ALL | All libraries on the system are searched. |
| *ALLUSR | All user defined libraries to which the user is authorized are searched. For information on the libraries included, see *ALLUSR in Generic library names. |
| *CURLIB | The job's current library is searched. |
| *LIBL | The library list for the job is searched. |
| *USRLIBL | The libraries in the user portion of the job's library list are searched. |
When the job queue name field is set to *ALLOCATED or *DEFINED the the job queue library field must be blanks.
Length of filter information. The length of the filter information. An error message is returned if the length of filter information is not set correctly.
Number of keys to sort on. The number of fields within the record structure on which to sort. If 0 is specified, the list is not sorted.
Reserved. Must be set to hexadecimal zeros.
Sort key field data type. Data type of field to sort. See Sort (QLGSORT) API for information on the list of data types available.
Sort key field length. The length of the field on which to sort.
Sort key field starting position. Within the record of information, the starting position of the field on which to sort.
Sort order. Whether the list should be sorted in ascending or descending order according to the key. See Sort (QLGSORT) API for information on the sort order special values.
Format of Receiver Variable
The following tables describe the order and format of the data returned in the receiver variable.
OJBQ0100 Format
For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Job queue name |
| 10 | A | CHAR(10) | Job queue library name |
| 20 | 14 | CHAR(1) | Job queue status |
| 21 | 15 | CHAR(10) | Subsystem name |
| 31 | 15 | CHAR(10) | Subsystem library name |
| 41 | 29 | CHAR(3) | Reserved |
| 44 | 2C | BINARY(4) | Number of jobs on job queue |
| 48 | 30 | BINARY(4) | Sequence number |
| 52 | 34 | BINARY(4) | Maximum active |
| 56 | 38 | BINARY(4) | Current active |
| 60 | 3C | CHAR(50) | Description |
| 110 | 6E | CHAR(10) | Job queue library auxiliary storage pool (ASP) name |
Field Descriptions
Current active. The number of jobs currently running in the active subsystem from this job queue. This field is -1 if the job queue is not allocated, is damaged, does not exist, or the job queue has not been allocated by the subsystem that was specified in the active subsystem field in the filter parameter.
Description. The text description for this job queue. This field will be blank if the job queue is defined to an active subsystem, but has not been created or the job queue is damaged.
Job queue library auxiliary storage pool (ASP) name. The name of the auxiliary storage pool (ASP) device name where storage is allocated for the library that contains the object. The following special values may be returned:
| *N | The name of the ASP device cannot be determined. |
| *SYSBAS | System ASP (ASP 1) or basic user ASPs (ASPs 2-32). |
Job queue library name. The name of the library in which the job queue is located.
Job queue name. The name of the job queue.
Job queue status. The current status of the job queue. The possible values are:
| 0 | The job queue is currently held. No jobs can become active from this job queue. |
| 1 | The job queue is released. Jobs can become active from this queue. |
| 2 | The job queue is damaged. |
| 3 | The job queue is defined to the active subsystem, but has not been created. No jobs can become active from this job queue until it is created. |
Maximum active. The maximum number of jobs that can be active in the subsystem from this job queue at one time. A -1 in this field indicates that the value is *NOMAX. This field is -2 if the job queue has not been defined to an active subsystem or the job queue is damaged.
Number of jobs on job queue. The total number of jobs currently waiting to run on this job queue. This field ise -1 if the job queue is defined to the active subsystem, but has not been created or the job queue is damaged.
Reserved. A reserved field.
Sequence number. The job queue entry sequence number. The subsystem uses this number to determine the order in which the job queues are processed. Jobs from the job queue with the lowest sequence number in the job queue are selected first. This field is -1 if the job queue has not been defined to an active subsystem or the job queue is damaged.
Subsystem name. The name of the subsystem to which this job queue is allocated. If the job queue has been allocated by a different subsystem than was specified in the filter parameter, the subsystem name will identify the subsystem to which the job queue is allocated. This field is blank if the job queue is not allocated, is damaged, or does not exist.
Subsystem library name. The library in which the subsystem description resides. This field will be blank if the job queue is not allocated, damaged or does not exist.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF1054 E | No subsystem &1 active. |
| 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. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9804 E | Object &2 in library &3 damaged. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9871 E | Error occurred while processing. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| GUI0002 E | &2 is not valid for length of receiver variable. |
| GUI0024 E | &1 is not valid for number of keys to sort on. |
| GUI0025 E | &1 is not valid for sort key field starting position. |
| GUI0026 E | &1 is not valid for sort key field length. |
| GUI0027 E | &1 is not valid for number of records to return. |
| GUI0119 E | Reserved field in sort information not valid. |
| GUI0120 E | Order field in sort information not valid. |
| GUI0150 E | Subsystem key must be specified. |
| GUI0152 E | &1 is not valid for length of filter information. |
API introduced: V5R1