Open List of Printers (QGYRPRTL) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | List information | Output | Char(80) |
| 4 | Number of records to return | Input | Binary(4) |
| 5 | Filter information | Input | Char(*) |
| 6 | Format name | Input | Char(8) |
| 7 | Error Code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Open List of Printers (QGYRPRTL) API generates a list of printers on the system and information about the printers. The list can include all printers on the system, a specific list of printers, or the printers for a single output queue. The list will be sorted by printer name.
Note: The QTEMP library and the system portion of the library list could be different between the main job and the server job when the list is being built asynchronously. If this is a problem, then request that the list be built synchronously.
For more information, see Process Open List APIs.
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.
- List information
- OUTPUT; CHAR(80)
The variable used to return status information about the list of printers that were opened. For a description of the layout of this parameter, see Open list information format.
- Number of records to return
- INPUT; BINARY(4)
The number of records in the list to put into the receiver variable after the filtering and sorting is done.
If the value zero is specified, only the list information is returned and no actual list entries are returned.
- Filter information
- INPUT; CHAR(*)
The information in this parameter is used to determine which printers to include in the list. Printers can be filtered based on printer name, output queue name, or both. See Format of Filter Information for a description of the layout of this parameter.
- Format name
- INPUT; CHAR(8)
The format of the printer information being returned.
You must specify one of the following:
PRTL0100 The basic information about the printer. PRTL0200 All the information in format PRTL0100 plus additional information about the output queue and the writer for the printer, and information about the spooled file currently being printed.
- 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 Receiver Variable
The following tables describe the order and format of the data that is returned in the receiver variable.
Format PRTL0100
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Device name |
| 10 | A | CHAR(50) | Text description |
| 60 | 3C | BINARY(4) | Overall status |
Format PRTL0200
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Device name |
| 10 | A | CHAR(50) | Text description |
| 60 | 3C | BINARY(4) | Overall status |
| 64 | 40 | BINARY(4) | Device status |
| 68 | 44 | CHAR(10) | Output queue name |
| 78 | 4E | CHAR(10) | Output queue library |
| 88 | 58 | CHAR(1) | Output queue status |
| 89 | 59 | CHAR(10) | Writer name |
| 99 | 63 | CHAR(1) | Writer status |
| 100 | 64 | CHAR(1) | Writer started |
| 101 | 65 | CHAR(10) | Form type |
| 111 | 6F | CHAR(10) | Current file name |
| 121 | 79 | CHAR(10) | Current file user |
| 131 | 83 | CHAR(10) | Current file user-specified data |
| 141 | 8D | CHAR(1) | Network directory publishing status |
Field Descriptions
Current file name. The name of the spooled file currently being processed by the writer. This field is blank when no file is printing.
Current file user. The name of the user who owns the spooled file currently being processed by the writer. This field is blank when no file is printing.
Current file user-specified data. The user-specified data that describes the file currently being processed by the writer.
Device name. The name of the printer device.
Device status. The status of the printer device using two fields:
Note: Not all of the following values apply to printer devices.
| Status Numeric Code (decimal) |
Overall Status |
|---|---|
| 0 | VARIED OFF |
| 5 | AS/36 DISABLED |
| 10 | VARY OFF PENDING |
| 20 | VARY ON PENDING |
| 30 | VARIED ON |
| 40 | CONNECT PENDING |
| 50 | SIGNON DISPLAY |
| 60 | ACTIVE |
| 62 | AS/36 ENABLED |
| 63 | ACTIVE READER |
| 66 | ACTIVE WRITER |
| 70 | HELD |
| 75 | POWERED OFF |
| 80 | RCYPND |
| 90 | RCYCNL |
| 95 | SYSTEM REQUEST |
| 100 | FAILED |
| 103 | FAILED READER |
| 106 | FAILED WRITER |
| 110 | DIAGNOSTIC MODE |
| 111 | DAMAGED |
| 112 | LOCKED |
| 113 | UNKNOWN |
Form type. The type of form being used to print the spooled file.
Possible values are:
| *ALL | The writer is started with the option to print
all spooled files of any form type. |
| *FORMS | The writer is started with the option to print
all the spooled files with the same form type before using a different form
type. |
| *STD | The writer is started with the option to print
all the spooled files with a form type of *STD. |
| Form type name | The writer is started with the option to print all the spooled files with the form type you specified. |
Network directory publishing stastus. Whether the printer is published in the network directory. Possible values are:
| 0 | Printer is not published |
| 1 | Printer is published |
Output queue library name. The name of the library that contains the output queue from which spooled files are selected for printing.
Output queue name. The name of the output queue from which spooled files are being selected for printing.
Output queue status. The status of the output queue from which spooled files are being selected for printing.
Possible values are:
| H | The output queue is held. |
| R | The output queue is released. |
Overall status. The overall status of the logical printer. Possible values are:
| 1 | Unavailable |
| 2 | Powered off or not yet available |
| 3 | Stopped |
| 4 | Message waiting |
| 5 | Held |
| 6 | Stop (pending) |
| 7 | Hold (pending) |
| 8 | Waiting for printer |
| 9 | Waiting to start |
| 10 | Printing |
| 11 | Waiting for printer output |
| 12 | Connect pending |
| 13 | Powered off |
| 14 | Unusable |
| 15 | Being serviced |
| 999 | Unknown |
Text description. The text description of the printer device.
Writer name. The name of the writer for this printer.
Writer started. Indication of whether or not a writer is started for this printer. Possible values are:
| 0 | No writer is started |
| 1 | Writer is started |
Writer status. The status of the writer for this printer. Possible values are:
| X'01' | Started |
| X'02' | Ended |
| X'03' | On job queue |
| X'04' | Held |
| X'05' | Message waiting |
Format of Filter Information
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of printer names |
| Offsets vary. These fields repeat, in the order listed, for each printer to filter on. | CHAR(10) | Printer name | |
| CHAR(2) | Reserved | ||
| Offset varies. | BINARY(4) | Number of output queues | |
| Offsets vary. These fields repeat, in the order listed, for each output queue to filter on. | CHAR(10) | Output queue | |
| CHAR(10) | Output queue library | ||
When no filter is to be done, the filter specification must be two BINARY(4) values set to zero.
Field Descriptions
Number of output queues. The total number of output queue names in the output queue name array.
| 0 | Does not filter by output queue |
| 1-1000 | Filters the specified number of output queue names |
Number of printer names. The total number of printer device names in the printer names array.
| 0 | Does not filter by printer name |
| 1-1000 | Filters the specified number of printer names |
Output queue. The name of an output queue to be included in the list.
Output queue library. The name of the library that contains the output queue.
Printer name. The name of a printer to be included in the list.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| 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. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| GUI0027 E | &1 is not valid for number of records to return. |
| GUI0108 E | Filter information is not valid. Reason code &1. |
API introduced: V3R6
[ Back to top | Print APIs | APIs by category ]