| 1 | Process option | Input | Binary(4) |
| 2 | Option specific input information to print driver | Input | Char(*) |
| 3 | Length of option specific input information | Input | Binary(4) |
| 4 | Option specific output information from print driver | Output | Char(*) |
| 5 | Length of option specific output information | Input | Binary(4) |
This Print Driver exit program defines how a user-defined print driver exit program must be written in order to be used with the i5/OS open writer program. When a user has enabled a print driver exit for a particular device, a writer started to that device opens the writer as its main processing program
This open writer program handles the scheduling of spooled files to print, and relies on the Print Driver exit program to complete all device specific tasks.
A typical scenario is:
The print driver initializes its environment.
The writer calls the print driver with the process file (20) process option. The name of the spooled file is passed in the input information. After the file has been processed by the print driver, control returns to the writer.
The number of seconds (x) to wait is returned by the print driver in the idle time field of the output information from the print driver parameter. If a file is not available, the writer calls the print driver with the idle (30) process option.
None.
The action for the Print Driver exit program to take. This information is filled in by the writer. The first option should be initialize (10). This is done when the writer is started.
Possible values are:
| 10 (Initialize) | The print driver sets any initial information with this option. |
| 20 (Process file) | A spooled file is available to print. The spooled file name and other information is passed in the option specific input information to driver exit program. |
| 21 (Reprocess file) | The print driver was interrupted while being called by the process file option (20). The print driver determines the appropriate action by using the Extract Writer Status (QSPEXTWI) API. The print driver can be interrupted only if the allow interrupts field was specified as *YES (in the Option specific output information parameter) and a spooled file was deleted, held with OPTION(*IMMED), or restarted (CHGSPLFA RESTART()). |
| 30 (Idle) | The writer calls the print driver after x seconds to inform the print driver that there is not a ready file on the output queue. The print driver can take the opportunity to end existing connections. The idle timer (x) value is filled in by the print driver when the writer calls the print driver with the initialize (10) process option. |
| 40 (Writer held) | The process has been held. The print driver does cleanup to ensure the proper start of the writer when it is released. |
| 50 (Terminate) | The writer is ending. The print driver does cleanup. |
Information which is input to the Print Driver exit program from the open writer program. For the format and description of this information, see Option Specific Input Information to Print Driver.
The length of the option specific input information specified in the option specific input information to print driver parameter.
Information which is output from the Print Driver exit program to the open writer program. For the format and description of this information, see Option Specific Output Information from Print Driver.
The length of the option specific output information to return in the option specific output information from the print driver parameter.
The following table shows the structure for the option specific input
information parameter. For more details about the fields in the following
table, see Field Descriptions.
Structure of the Option Specific Input Information Parameter
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(16) | Writer handle |
| 16 | 10 | CHAR(10) | Writer name |
| 26 | 1A | CHAR(10) | Printer device name |
| 36 | 24 | CHAR(10) | Writer output queue name |
| 46 | 2E | CHAR(10) | Writer output queue library name |
| 56 | 38 | CHAR(10) | Writer message queue name |
| 66 | 42 | CHAR(10) | Writer message queue library name |
| 76 | 4C | CHAR(10) | Align file |
| 86 | 56 | CHAR(10) | Spooled file handle |
| 96 | 60 | CHAR(16) | Internal job identifier |
| 112 | 70 | CHAR(16) | Internal spooled file identifier |
| 128 | 80 | CHAR(26) | Qualified job name |
| 154 | 9A | CHAR(10) | Spooled file name |
| 164 | A4 | BINARY(4) | Spooled file number |
| 168 | A8 | BINARY(4) | Starting page number |
| 172 | AC | BINARY(4) | Drawer for separator pages |
| 176 | B0 | BINARY(4) | Number of job separators |
| 180 | B4 | BINARY(4) | Number of file separators |
| 184 | B8 | BINARY(4) | Termination type |
| 188 | BC | CHAR(10) | Current writer form type |
| 198 | C6 | CHAR(8) | Job system name |
| 206 | CE | CHAR(7) | Spooled file create date |
| 213 | D5 | CHAR(1) | Reserved |
| 214 | D6 | CHAR(6) | Spooled file create time |
| 220 | DC | CHAR(23) | Reserved |
Align file. Specifies how to control the forms alignment.
Possible values are:
| *WTR | The writer keeps track of the output that is printed and issues a forms alignment message whenever it determines that forms may need to be aligned. |
| *FILE | The forms alignment message is issued for every file that has *YES specified for the align page prompt. |
| *FIRST | The forms alignment message is issued only for the first file printed. |
| *SKIP | The forms alignment message is skipped for the next file. |
Current writer form type. The form type the writer is currently printing.
Drawer for separator pages. The paper drawer to be selected when printing the job and file separators.
Internal job identifier. The internal job identifier of the job that created the spooled file.
Internal spooled file identifier. The internal spooled file identifier of the spooled file being processed.
Job system name. The name of the system where the job that created the spooled file ran.
Number of file separators. The number of the file separators to be printed.
Number of job separators. The number of the job separators to be printed.
Printer device name. The name of the printer device.
Qualified job name. The qualified job name for the job that created the file.
Reserved. Reserved to maintain compatibility with the writer transform exit and the Host Print Transform (QWPZHPTR) API.
Spooled file create date. The date the spooled file was created on the system in the CYYMMDD format. See field Date file opened in API QUSRSPLA under field descriptions for more information on the date format.
Spooled file create time. The time the spooled file was created on the system in the HHMMSS format. See field Time file opened in API QUSRSPLA under field descriptions for more information on the time format.
Spooled file handle. The handle for the spooled file to be printed.
Spooled file name. The name of the spooled file being processed.
Spooled file number. The number of the spooled file being processed.
Starting page number. The number of the page to start printing.
Termination type. The type of termination for the writer.
Possible values are:
| 1 (normal) | The writer ended normally. |
| 2 (immediate) | The writer ended immediately. |
| 3 (abnormal) | The writer ended abnormally. |
Writer handle. The handle to the writer job.
Writer name. The name of the writer.
Writer message queue library name. The name of the library in which the writer message queue resides.
Writer message queue name. The name of the message queue to which the writer issues messages.
Writer output queue library name. The name of the library in which the output queue resides.
Writer output queue name. The name of the output queue from which the writer is processing spooled files.
Fields Defined for the Option Specific Input Information
Parameter presents, in the same order, all the fields previously described
in the Structure of the Option Specific Input Information
Parameter. Each entry indicates if a field is defined for a particular
process option as defined by the process option parameter. Possible values are
Y for yes, and N for no.
Fields Defined for the Option Specific Input Information Parameter
| Field | Initialize (10) | Process file (20) | Re- process (21) | Idle (30) | Writer held (40) | Terminate (50) | Description |
|---|---|---|---|---|---|---|---|
| Writer handle | Y | Y | Y | Y | Y | Y | For use with new writer APIs. |
| Writer name | Y | Y | Y | Y | Y | Y | Name specified on STRPRTWTR command. |
| Printer device name | Y | Y | Y | Y | Y | Y | The name of the printer the writer is started to. |
| Writer output queue name | Y | Y | Y | Y | Y | Y | The name of the output queue that the writer is processing. |
| Writer output library name | Y | Y | Y | Y | Y | Y | The library in which the writer output queue resides. |
| Writer message queue name | Y | Y | Y | Y | Y | Y | Name of the message queue for the started writer. |
| Writer message queue library name | Y | Y | Y | Y | Y | Y | Name of the library in which the message queue resides. |
| Align file | Y | Y | Y | Y | Y | Y | Value from STRPRTWTR command. |
| Spooled file handle | N | Y | Y | N | N | N | For use with new writer APIs. |
| Internal job identifier | N | Y | Y | N | N | N | For use with existing spool APIs. |
| Internal spooled file identifier | N | Y | Y | N | N | N | For use with existing Spool APIs. |
| Qualified job name | N | Y | Y | N | N | N | Job owning spooled file |
| Spooled file name | N | Y | Y | N | N | N | Name of spooled file being processed |
| Spooled file number | N | Y | Y | N | N | N | Number of spooled file being processed |
| Starting page number | N | Y | Y | N | N | N | Page at which to start printing |
| Drawer for separator pages | N | Y | Y | N | N | N | Paper drawer for separator pages |
| Number of job separators | N | Y | Y | N | N | N | Number of job separators to print |
| Number of file separators | N | Y | Y | N | N | N | Number of file separators to print |
| Termination type | N | N | N | N | N | Y | This is how the writer has been ended (normal, immediate, or abnormal for unrecoverable error). |
| Current writer form type | N | Y | Y | N | N | N | Form type writer is currently processing. |
| Job system name | N | Y | Y | N | N | N | Name of the system the job resides on. |
| Spooled file create date | N | Y | Y | N | N | N | Date the spooled file was created. |
| Reserved | N | N | N | N | N | N | Reserved for compatibility. |
| Spooled file create time | N | Y | Y | N | N | N | Time the spooled file was created. |
The following table shows the structure for the option specific output information parameter. For more details about the fields in the following table, see Field Descriptions.
Structure of the Option Specific Output Information Parameter
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Error code |
| 4 | 4 | BINARY(4) | Initial status |
| 8 | 8 | BINARY(4) | Idle timer |
| 12 | C | CHAR(1) | Allow interrupt |
| 13 | D | CHAR(3) | Reserved |
| 16 | 10 | CHAR(10) | LAN driver name |
Allow interrupt. Whether to allow the writer to interrupt the print driver. This determines whether Hold spooled file (HLDSPLF) with option *IMMED, Delete spooled file (DLTSPLF), or Change spooled file attributes (CHGSPLFA) changing the Restart printing (RESTART) parameter causes the print driver to be interrupted before it returns to the writer normally. If the print driver program allows interrupts, it is necessary that the print driver program is written such that it is able to resume processing following an interruption.
Possible values are:
| 0 | Do not allow interrupts. |
| 1 | Allow interrupts. |
Error code. The error code returned by the print driver after each call.
Possible values are:
| 0 | No error occurred. |
| 1 | Writer ending normally |
| 2 | Writer ending immediately |
| 10 | Processing of the file was interrupted (Note: This error code should be used when the driver program has detected a Hold Writer (HLDWTR) command with option *PAGEEND or *CNTRLD, and wishes to continue processing the spooled file after the writer is released.) |
Idle timer. The number of seconds to allow between spooled files. A value of 0 indicates that no calls are made to the print driver with the Idle (30) process option.
Initial status. The initial status for the spooled file selected by the writer.
Possible values are:
| 1 (pending) | The spooled file is being converted. |
| 2 (writing) | The spooled file is being selected by the writer. |
| 3 (sending) | The spooled file is being sent to a remote system |
LAN driver name. The name of the LAN driver to process the spooled files.
Reserved. An ignored field.
Fields Defined for the Option Specific Output Information
Parameter presents, in the same order, all the fields previously described
in the Structure of the Option Specific Output Information
Parameter. Each entry indicates if a field is used with a particular
process option as defined by the Process Option parameter. Possible values are
Y for yes, and N for no.
Fields Defined for the Option Specific Output Information Parameter
| Field | Initialize (10) | Process file (20) | Re-process (21) | Idle (30) | Writer held (40) | Terminate (50) | Description |
|---|---|---|---|---|---|---|---|
| Error code | Y | Y | Y | Y | Y | N | This indicates if the driver exit program has encountered an error. A value 0 indicates no error. A value of 1 causes the writer to wait for all current print requests to complete, and then call the print driver with an normal termination. A value of 2 causes the writer to immediately call the print driver with an immediate termination type. A value of 10 causes the writer to call the print driver with a reprocess file (21) process option for the currently active file. |
| Initial status | Y | N | N | N | N | N | Specifies the initial status of spooled files that are selected for processing by the writer. |
| Idle timer | Y | Y | Y | Y | N | N | Specifies the time to wait in seconds before calling the print driver with the Idle (30) process option. A value of 0 indicates that no calls are made with the Idle process option. |
| Allow interrupt | Y | N | N | N | N | N | Allows the writer to interrupt the print driver during a call from the writer to the print driver. |
| LAN driver name | Y | N | N | N | N | N | Specifies the name of the local area network (LAN) and the name of the printer driver it is started to. |
| Top | Print APIs | APIs by category |