Open List of Output Queues (QSPOLOTQ) 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 Output Queues (QSPOLOTQ) API generates a list of output queues on the system. The list can include all output queues on the system, all output queues for a specified library list, all output queues on an ASP device, all output queues with a name starting with the same characters, or a specific output queue. The filtered list can then be sorted depending on the value of the sort parameter. When requesting output queue information, if the signed-on user is not authorized to the library of the output queue, information for that output queue is not returned by this API. 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 output queue name, output queue library name, number of files on an output queue, number of writers started to an output queue, first writer started to the queue, output queue status, description, or ASP name takes more processing power and time.
Authorities and Locks
- Output Queue Library Authority
- *EXECUTE
- Output Queue Lock
- This API gets an *EXCLRD lock on the output queue.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable used to return the output 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 output queue information being returned. You can specify the following:
OOTQ0100 Contains the basic information about the output queue. For more information about the OOTQ0100 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 output 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) | Output queue name |
| 14 | E | CHAR(10) | Output queue library name |
| 24 | 18 | CHAR(10) | Auxiliary storage pool (ASP) device 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
Auxiliary storage pool (ASP) device name. The name of an ASP device in which storage is allocated for the library that contains the output queue. A specific ASP device name or a special value may be specified. If filtering on an output queue library value of *CURLIB, *LIBL, or *USRLIBL, the ASP device name must not be specified or must be the special value * or message CPF2173 will be issued.
| simple name | A simple name of an ASP device. The ASP device must be in the namespace for the current job or CPF337E will be issued. |
| * | The ASPs in the thread's library name space. |
| *SYSBAS | The system ASP (ASP 1) and defined basic user ASPs (ASPs 2-32). |
| *CURASPGRP | The ASPs in the current thread's ASP group. |
Output queue name. The output queue about which to retrieve information. A specific output queue name, a generic output queue name, or the special value *ALL may be specified.
| simple name | A simple name of an output queue. |
| generic name | A generic name for output queues. |
| *ALL | All output queues are returned. |
Output queue library name. The library in which the output queue is located. A specific library name or a special value may be specified.
| 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. |
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.
OOTQ0100 Format
For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Output queue name |
| 10 | A | CHAR(10) | Output queue library name |
| 20 | 14 | BINARY(4) | Number of spooled files on output queue |
| 24 | 18 | BINARY(4) | Number of writers started to output queue |
| 28 | 1C | CHAR(10) | Name of first writer to output queue |
| 38 | 26 | CHAR(1) | Output queue status |
| 39 | 27 | CHAR(3) | Reserved |
| 42 | 2A | CHAR(50) | Description |
| 92 | 5C | CHAR(10) | Output queue library auxiliary storage pool (ASP) name |
Field Descriptions
Description. The text description for this output queue. The following special value may be returned:
| *BLANK | There is no text description for the output queue. |
Name of first writer started to output queue. The first active writer producing output from the output queue.
Output 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). |
Output queue library name. The name of the library in which the output queue is located.
Output queue name. The name of the output queue.
Output queue status. The current status of the output queue. The possible values are:
| 0 | The output queue is currently held. No spooled files can be written from this output queue. |
| 1 | The output queue is released. Spooled files can be written from this queue. |
| 2 | The output queue is damaged. |
Number of spooled files on output queue. The total number of spooled files currently on this output queue. This field is -1 if the output queue is damaged.
Number of writers started to output queue. The total number of writers currently producing output from this output queue. This field is -1 if the output queue is damaged.
Reserved. A reserved field.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF2173 E | Value for ASPDEV not valid with special value for library. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF337E E | ASP device &1 not in current ASP group for thread. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C3B E | Value for &2 for API &1 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. |
| GUI0152 E | &1 is not valid for length of filter information. |
API introduced: V6R1 with PTF
[ Back to top | Print APIs | APIs by category ]