Open List of Job Queues (QSPOLJBQ) API

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 Format of open list information.

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.

Format of Sort Information

For more details about the fields in the following table, see Field Descriptions.

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.

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.

When the active subsystem name field is set to a simple subsystem name, then one of the following special values must be used:

When the active subsystem name field is set to *ALL, the following special value must be used:

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.

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 the 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 the 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.

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 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:

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