Retrieve Writer Information (QSPRWTRI) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Printer name | Input | Char(10) |
| 5 | Error Code | I/O | Char(*) |
Optional Parameter:
| 6 | Writer name | Input | Char(10) |
Default Public Authority: *USE
Threadsafe: No
The Retrieve Writer Information (QSPRWTRI) API retrieves writer information associated with the specified printer or writer. The information retrieved is similar to what can be seen when running the Work with Writer (WRKWTR) command for a particular writer.
Additionally, this API can retrieve information about pending changes to a particular writer. The fields that could contain possible pending changes are:
- Next file separators
- Next form type
- Next message option
- Next output queue library name
- Next output queue name
- Next separator drawer
Changes to these fields result when the Change Writer (CHGWTR) command has been used. The value specified in the Changes take effect field determines when the pending changes take place.
Authorities and Locks
- Output Queue Lock
- *EXCLRD
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 the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable. If the length is larger than the size of the receiver variable, the results are not predictable. The minimum length is 8 bytes.
- Format name
- INPUT; CHAR(8)
The content and format of the writer information to be returned.
The following format name can be used:
WTRI0100 Writer information
- Printer name
- INPUT; CHAR(10)
The name of the printer for which writer information is to be returned. The following special value is supported for this parameter:
*WRITER Use the writer name specified on the writer name parameter to return writer information.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Optional Parameter
- Writer name
- INPUT; CHAR(10)
The name of the writer for which writer information is to be returned. The value of this parameter must be set to blanks if the printer name parameter is not set to *WRITER.
WTRI0100 Format
The following information is returned for the WTRI0100 format. See Field Descriptions for more information.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | Started by user |
| 18 | 12 | CHAR(1) | Writing status |
| 19 | 13 | CHAR(1) | Waiting for message status |
| 20 | 14 | CHAR(1) | Held status |
| 21 | 15 | CHAR(1) | End pending status |
| 22 | 16 | CHAR(1) | Hold pending status |
| 23 | 17 | CHAR(1) | Between files status |
| 24 | 18 | CHAR(1) | Between copies status |
| 25 | 19 | CHAR(1) | Waiting for data status |
| 26 | 1A | CHAR(1) | Waiting for device status |
| 27 | 1B | CHAR(1) | On job queue status |
| 28 | 1C | CHAR(1) | Type of writer |
| 29 | 1D | CHAR(3) | Reserved |
| 32 | 20 | CHAR(10) | Writer job name |
| 42 | 2A | CHAR(10) | Writer job user name |
| 52 | 34 | CHAR(6) | Writer job number |
| 58 | 3A | CHAR(10) | Printer device type |
| 68 | 44 | BINARY(4) | Number of separators |
| 72 | 48 | BINARY(4) | Drawer for separators |
| 76 | 4C | CHAR(10) | Align forms |
| 86 | 56 | CHAR(10) | Output queue name |
| 96 | 60 | CHAR(10) | Output queue library name |
| 106 | 6A | CHAR(1) | Output queue status |
| 107 | 6B | CHAR(1) | Reserved |
| 108 | 6C | CHAR(10) | Form type |
| 118 | 76 | CHAR(10) | Message option |
| 128 | 80 | CHAR(10) | Automatically end writer |
| 138 | 8A | CHAR(10) | Allow direct printing |
| 148 | 94 | CHAR(10) | Message queue name |
| 158 | 9E | CHAR(10) | Message queue library name |
| 168 | A8 | CHAR(2) | Reserved |
| 170 | AA | CHAR(10) | Changes take effect |
| 180 | B4 | CHAR(10) | Next output queue name |
| 190 | BE | CHAR(10) | Next output queue library name |
| 200 | C8 | CHAR(10) | Next form type |
| 210 | D2 | CHAR(10) | Next message option |
| 220 | DC | BINARY(4) | Next file separators |
| 224 | E0 | BINARY(4) | Next separator drawer |
| 228 | E4 | CHAR(10) | Spooled file name |
| 238 | EE | CHAR(10) | Job name |
| 248 | F8 | CHAR(10) | User name |
| 258 | 102 | CHAR(6) | Job number |
| 264 | 108 | BINARY(4) | Spooled file number |
| 268 | 10C | BINARY(4) | Page being written |
| 272 | 110 | BINARY(4) | Total pages |
| 276 | 114 | BINARY(4) | Copies left to produce |
| 280 | 118 | BINARY(4) | Total copies |
| 284 | 11C | CHAR(4) | Message key |
| 288 | 120 | CHAR(1) | Initialize printer |
| 289 | 121 | CHAR(10) | Printer device name |
| 299 | 12B | CHAR(8) | Job system name |
| 307 | 133 | CHAR(7) | Spooled file create date |
| 314 | 13A | CHAR(6) | Spooled file create time |
Field Descriptions
Align forms. The time at which the forms alignment message will be sent.
Possible values are:
| *WTR | The writer determines when the message is sent. |
| *FILE | Control of the page alignment is specified by each file. |
| *FIRST | The forms alignment message is only issued for the first spooled file printed. |
Allow direct printing. Whether the printer writer allows the printer to be allocated to a job that prints directly to a printer. This field is set to blanks for remote writers.
| *NO | Direct printing is not allowed |
| *YES | Direct printing is allowed. |
Automatically end writer. When to end the writer if it is to end automatically.
| *NORDYF | When no files are ready to print on the output queue from which the writer is selecting files to be printed. |
| *FILEEND | When the current spooled file has been printed. |
| *NO | The writer will not end, but it will wait for more spooled files. |
Between copies status. Whether the writer is between copies of a multiple copy spooled file. This field is set to blanks for remote writers. The possible values are Y (yes) or N (no).
Between files status. Whether the writer is between spooled files. The possible values are Y (yes) or N (no).
Bytes available. Total format data length.
Bytes returned. The length of the data returned.
Changes take effect. The time at which the pending changes to the writer take effect.
Possible values are:
| *NORDYF | When all the current eligible files are printed. |
| *FILEEND | When the current spooled file is done printing. |
| blank | No pending changes to the writer. |
Copies left to produce. The number of copies left to be printed. This field is set to 0 when no file is printing.
Drawer for separators. Identifies the drawer from which the job and file separator pages are to be taken.
Possible values are:
| -1 | *FILE: The separator page prints from the same drawer that the file is printed from. If you specify a drawer different from the file that contains colored or different type paper, the page separator is more identifiable. |
| -2 | *DEVD: The separator pages will print from the separator drawer specified in the printer device description. |
| 1 | The first drawer. |
| 2 | The second drawer. |
| 3 | The third drawer. |
End pending status. Whether an End Writer (ENDWTR) command has been issued for this writer.
Possible values are:
| N | No ENDWTR command was issued. |
| I | *IMMED: The writer ends as soon as its output buffers are empty. |
| C | *CNTRLD: The writer ends after the current copy of the spooled file has been printed. |
| P | *PAGEEND: The writer ends at the end of the page. |
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. |
Held status. Whether the writer is held. The possible values are Y (yes) or N (no).
Hold pending status. Whether a Hold Writer (HLDWTR) command has been issued for this writer.
Possible values are:
| N | No HLDWTR command was issued. |
| I | *IMMED: The writer is held as soon as its output buffers are empty. |
| C | *CNTRLD: The writer is held after the current copy of the file has been printed. |
| P | *PAGEEND: The writer is held at the end of the page. |
Initialize printer. How often to initialize the printer device. This field is set to blanks for remote writers.
Possible values are:
| 0 | The writer initializes the printer device when necessary. |
| 1 | The writer initializes the printer device only before the first spooled file is printed and after device error recovery. |
| 2 | The writer initializes the printer device before every spooled file is printed. |
Job name. The name of the job that owns the spooled file currently being processed by the writer. This field is blank when no spooled file is printing.
Job number. The number of the job that owns the spooled file currently being processed by the writer. This field is blank when no spooled file is printing.
Job system name. The name of the system where the job that created the spooled file, currently being processed by the writer, ran. This field is blank when no spooled file is printing.
Message key. A key to the message that the writer is waiting for. This field is blank when the writer is not waiting for a reply to an inquiry message.
Message option. Message option for sending a message to the message queue when this form is finished.
Possible values are:
| *MSG | A message is sent to the message queue. |
| *NOMSG | No message is sent to the message queue. |
| *INFOMSG | An informational message is sent to the message queue. |
| *INQMSG | An inquiry message is sent to the message queue. |
Message queue library name. The name of the library that contains the message queue.
Message queue name. The name of the message queue that this writer uses for operational messages.
Next file separators. The next number of separator pages to be printed when the change to the writer takes place.
Possible values are:
| -1 | *FILE: The number of separator pages is specified by each file. |
| -10 | No pending change to the writer. |
| number of separators | The number of separator pages to be printed. |
Next form type. The name of the next form type to be printed.
Possible values are:
| *ALL | The writer is changed with the option to print all spooled files of any form type. |
| *FORMS | The writer is changed with the option to print all the spooled files with the same form type before using a different form type. |
| *STD | The writer is changed with the option to print all the spooled files with a form type of *STD. |
| form type name | The writer is changed with the option to print all the spooled files with the form type name you specified. |
| blank | No change has been made to this writer. |
Next message option. The message option for sending a message to the message queue when the next form type is finished.
Possible values are:
| *MSG | A message is sent to the message queue. |
| *NOMSG | No message is sent to the message queue. |
| *INFOMSG | An informational message is sent to the message queue. |
| *INQMSG | An inquiry message is sent to the message queue. |
| blank | No change pending. |
Next output queue library name. The name of the library that contains the next output queue. This field is blank if no changes have been made to the writer.
Next output queue name. The name of the next output queue to be processed. This field is blank if no changes have been made to the writer.
Next separator drawer. This value indicates the drawer from which to take the separator pages if there is a change to the writer.
Possible values are:
| -1 | *FILE: Separator pages print from the same drawer that the spooled file prints from. If you specify a drawer different from the spooled file that contains colored or different type paper, the page separator is more identifiable. |
| -2 | *DEVD: Separator pages print from the separator drawer specified in the printer device description. |
| -10 | No pending change to the writer. |
| 1 | The first drawer. |
| 2 | The second drawer. |
| 3 | The third drawer. |
Number of separators. The number of separator pages to be printed.
Possible values are:
| -1 | *FILE: The number of separator pages is specified by each file. |
| Number of separators | The number of separator pages to be printed. |
On job queue status. Whether the writer is on a job queue and, therefore, is not currently running. The possible values are Y (yes) or N (no).
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. |
Page being written. The page number in the spooled file that is currently being processed by the writer. The page number shown may be lower or higher than the actual page number being printed because of buffering done by the system. This field is set to 0 when no spooled file is printing.
Printer device name. The name of the printer device for which writer information is being returned. This field is set to blanks for remote writers.
Printer device type. The type of the printer being used to print the spooled file. This field is set to blanks for remote writers.
Valid values are:
| *SCS | SNA (Systems Network Architecture) character stream |
| *IPDS | Intelligent Printer Data Stream™ |
Reserved. An ignored field.
Spooled file create date. The date, based on local job time, that the spooled file was created on the system. The date is in the CYYMMDD format as follows:
| C | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| YY | Year |
| MM | Month |
| DD | Day |
This field is blank when no spooled file is printing.
Spooled file create time. The time, in local job time, that the spooled file was created on the system. The time is in the HHMMSS format where:
| HH | Hour |
| MM | Minutes |
| SS | Seconds |
This field is blank when no spooled file is printing.
Spooled file name. The name of the spooled file currently being processed by the writer. This field is blank when no spooled file is printing.
Spooled file number. The number of the spooled file currently being processed by the writer. This field is set to 0 when no spooled file is printing.
Started by user. The name of the user that started the writer.
Total copies. The total number of copies to be printed.
Total pages. The total number of pages in the spooled file.
Possible values are:
| number | The number of pages in the spooled file. |
| 0 | No spooled file is printing. |
Type of writer. The type of writer for which writer information is being returned.
Valid values are:
| 0 | Printer writer |
| 1 | Remote writer |
User name. 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.
Waiting for data status. Whether the writer has written all the data currently in the spooled file and is waiting for more data.
Possible values are:
| N | The writer is not waiting for more data. |
| Y | The writer has written all the data currently in the spooled file and is waiting for more data. This condition occurs when the writer is producing an open spooled file with SCHEDULE(*IMMED) specified. |
Waiting for device status. Whether the writer is waiting to get the device from a job that is printing directly to the printer. This field is set to blanks for remote writers.
| N | The writer is not waiting for the device. |
| Y | The writer is waiting for the device |
Waiting for message status. Whether the writer is waiting for a reply to an inquiry message. The possible values are Y (yes) or N (no).
Writer job name. The job name of the printer writer.
Writer job number. The job number of the printer writer.
Writer job user name. The name of the system user.
Writing status. Whether the printer writer is in writing status. The
Possible values are:
| Y | The writer is in writing status. |
| N | The writer is not in writing status. |
| S | The writer is writing the file separators. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| 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. |
| CPF33C8 E | No writer information returned for printer &1. |
| CPF3313 E | Writer &1 not active nor on job queue. |
| CPF3330 E | Necessary resource not available. |
| CPF33BB E | Writer name is not valid. |
| CPF33BC E | No writer information returned for writer &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R3
[ Back to top | Print APIs | APIs by category ]