| 1 | Process option | Input | Binary(4) |
| 2 | Option specific input information to transform exit | Input | Char(*) |
| 3 | Length of option specific input information to transform exit | Input | Binary(4) |
| 4 | Spooled file data buffer | Input | Char(*) |
| 5 | Length of spooled file data buffer | Input | Binary(4) |
| 6 | Option specific output information from transform exit | Output | Char(*) |
| 7 | Length of option specific output information from transform exit | Input | Binary(4) |
| 8 | Length of option specific output information available from transform exit | Output | Binary(4) |
| 9 | Transformed data buffer | Output | Char(*) |
| 10 | Length of transformed data buffer | Input | Binary(4) |
| 11 | Length of transformed data available | Output | Binary(4) |
The Writer Transform exit program describes the interface between a user-defined transform exit program (transform exit) and an i5/OS printer writer (writer).
Note: This exit interface can also be used for remote writers and on the Send TCP/IP Spooled File (SNDTCPSPLF or LPR) command.
A transform exit program can be enabled by an operator when a writer is started to an output queue. The writer handles the scheduling of spooled files to print, and relies on the transform exit program to complete transforming of the data necessary to print the file. The data is processed by the writer as DEVTYPE(*USERASCII).
For informational purposes, the example below is provided to show the interaction between the printer writer and the transform exit program.
This ties a specific output queue to a specific printer. In this case, the printer is capable of accepting the Printer Control Language (PCL) data stream.
The transform exit program creates its work spaces and returns to the writer a successful return code.
The writer calls the transform exit program with the process file (20) process option. The name and identifier of the spooled file are passed in the input information.
The transform exit program determines if it will transform the file, returns to the writer a successful return code and an indication whether it will transform the file.
The writer calls the transform exit program, passing the data to transform. The transform exit program transforms the data and passes it back to the writer. This step happens repeatedly, until the entire spooled file has been passed to the transform exit program.
The transform exit program returns to the writer any remaining data to be sent to the printer.
Steps starting with the process file option are repeated.
The writer calls the transform exit program with the terminate process option (50). The transform exit program cleans up any work spaces that it has created and returns to the writer.
The transform program should be capable of handling the case where the program could lose control while processing a spooled file.
Note: This could happen when the spooled file being processed is held using the Hold Spooled File (HLDSPLF) command, deleted using the Delete Spooled File (DLTSPLF) command, or a restart page specified using the Change Spooled File Attributes (CHGSPLA) command.
When this happens, the transform program will be called with the end file (40) process option. The transform program is expected to be able to continue processing normally.
None.
The action for the transform 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 transform exit program sets any initial information with this option. |
| 20 (Process file) | A spooled file is available to print. The spooled file name and other information are passed in the Option specific input information parameter to the transform exit program. The transform exit program decides whether to transform the data and sets the Transform file field in the output information structure. The transform exit may pass data to the writer. This data is treated as open time commands and is sent to the printer before the spooled file is printed. |
| 30 (Transform data) | The writer calls the transform exit program after reading one or more buffers of data from the spooled file. The data is in the Spooled file data buffer. This process is repeated for a spooled file until all data has been processed. Alignment data could also be returned. |
| 40 (End file) | The writer calls the transform exit to inform the
transform exit that all data for the spooled file has been passed. No data is
passed on this call. The transform exit may pass additional data to the writer
as an append to the end of the printed data.
This option is used even if the transform exit did not transform the spooled file. |
| 50 (Terminate) | The writer is ending. The transform exit will do cleanup. |
Information which is input to the transform exit program from the writer. For the format and description of this information, see Option Specific Input Information to Transform Exit Program.
The length of the option specific input information specified in the Option specific input information to transform exit program parameter.
The spooled file data to be transformed by the transform exit program.
The space is created and destroyed by the writer.
The length of the spooled file data specified in the Spooled file data buffer parameter.
Information which is output from the transform exit program to the writer. For the format and description of this information, see Option Specific Output Information From Transform Exit.
The size, in bytes, of the option specific output information buffer.
The length of the option specific output information available. If this length is less than or equal to the length of the option specific output information, all available information has been returned. If this length is greater than the length of the option specific output information, only data up to the length provided is returned in the option specific output information buffer.
Spooled file data which has been transformed by the transform exit program. The data in this buffer will be sent by the writer to the printer. It will not be validity checked or syntax checked by the writer. If the print data is not a valid data stream for the device, errors will be returned from the device. The data is processed by the writer as DEVTYPE(*USERASCII).
Alignment data, if requested, is also returned in the transformed data buffer. The lengths and offsets of the alignment information is returned in the option specific output information. For the format and description of this information, see Option Specific Output Information From Transform Exit.
The space is created and destroyed by the writer.
The size, in bytes, of the transformed data buffer.
The length of the transformed data that is available to be returned in the transformed data buffer. If this length is less than or equal to the length of the transform data buffer, all available information has been returned. If this length is greater than the length of the transformed data buffer, only data up to the length provided was returned in the transformed data buffer.
Parameters Used by the Printer Writer or Transform Exit
Program presents, in the same order, all the required parameters previously
described. Each entry indicates if a parameter is to be used by the writer or
transform exit program. Possible values are Y and N.
Parameters Used by the Printer Writer or Transform Exit Program
| Parameter | Initialize (10) | Process file (20) | Transform data (30) | End file (40) | Terminate (50) | Description |
|---|---|---|---|---|---|---|
| Process option | 10 | 20 | 30 | 40 | 50 | |
| Option specific input information to transform exit | Y | Y | Y | Y | Y | See description of this parameter. |
| Length of option specific input information | Y | Y | Y | Y | Y | Length of option specific input information |
| Spooled file data buffer | N | N | Y | N | N | Contains data only on spooled data to transform option. |
| Length of spooled file data buffer | N | N | Y | N | N | The length of spooled data buffer. |
| Option specific output information from transform exit | Y | Y | Y | Y | Y | See description of this parameter. |
| Length of option specific output information | Y | Y | Y | Y | Y | Length of option specific output information |
| Length of option specific output information available | Y | Y | Y | Y | Y | The number of bytes of option specific output information that is available. If this is greater than the length of the buffer, only information that can fit in the option specific output information buffer will be returned. |
| Transformed data buffer | N | Y | Y | Y | N | This buffer can contain data to send to the device before the transformed data (Start of file option) or after the transformed data (End of file option), as well as transformed data (Spooled data to transform option). |
| Length of transformed data buffer | N | Y | Y | Y | N | The size, in bytes, of the transformed data buffer. |
| Length of transformed data available | N | Y | Y | Y | N | The number of bytes of transformed data that is available. |
The following table shows the structure for the option specific information input parameter. For more details about the fields in the following table see, Field Descriptions.
| 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) | Reserved |
| 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 | CHAR(12) | Reserved |
| 180 | B4 | BINARY(4) | End file type |
| 184 | B8 | BINARY(4) | Termination type |
| 188 | BC | CHAR(10) | Current writer form type |
| 198 | C6 | CHAR(1) | Return alignment data |
| 199 | C7 | CHAR(5) | Reserved |
| 204 | CC | BINARY(4) | Number of complete pages |
| 208 | D0 | CHAR(10) | Workstation customizing object name |
| 218 | DA | CHAR(10) | Workstation customizing object library |
| 228 | E4 | CHAR(15) | Manufacturer type and model |
| 243 | F3 | CHAR(31) | Reserved |
| 274 | 112 | CHAR(8) | Job system name |
| 282 | 11A | CHAR(7) | Spooled file create date |
| 289 | 121 | CHAR(1) | Reserved |
| 290 | 122 | CHAR(6) | Spooled file create time |
Current writer form type. The form type the writer is currently printing.
This field is set to blanks when the transform exit program is called from the Send TCP/IP Spooled File (SNDTCPSPLF or LPR) command.
End file type. The type of ending for the file.
Possible values are:
| 1 (normal) | Processing of the file ends normally. |
| 2 (immediate) | Processing of the file ends immediately. |
| 3 (page end) | Processing of the file ends at the end of the current page. |
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.
Manufacturer type and model. The manufacturer, type and model for a printer using transform support.
Number of complete pages. The number of complete pages that are contained in the data to be transformed.
Printer device name. The name of the printer device.
Qualified job name. The qualified job name of the job that created the spooled file.
Reserved. This field is reserved.
Return alignment data. Whether the transform should return data to the caller which can be used for alignment purposes.
Possible values are:
| 0 | Do not return alignment information. |
| 1 | Return alignment information. |
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.
This field is set to blanks when the transform exit program is called from the Send TCP/IP Spooled File (SNDTCPSPLF or LPR) command.
Spooled file name. The name of the spooled file being processed.
Spooled file number. The number of the spooled file being processed.
Termination type. The type of termination by the writer:
| 1 (normal) | The writer ended normally. |
| 2 (immediate) | The writer ended immediately. |
| 3 (abnormal) | The writer ended abnormally. |
Workstation customizing object library. The library containing the workstation customizing object.
Workstation customizing object name (WSCST). The name of an object that consists of a table of attributes used to customize a given ASCII device.
Writer handle. The handle to the writer job.
This field is set to blanks when the transform exit program is called from the Send TCP/IP Spooled File (SNDTCPSPLF or LPR) command.
Writer message queue library name. The name of the library in which the writer message queue resides.
This field is set to blanks when the transform exit program is called from the Send TCP/IP Spooled File (SNDTCPSPLF or LPR) command.
Writer message queue name. The name of the message queue to which the writer issues messages.
This field is set to blanks when the transform exit program is called from the Send TCP/IP Spooled File (SNDTCPSPLF or LPR) command.
Writer name. The name of the writer.
This field is set to blanks when the transform exit program is called from the Send TCP/IP Spooled File (SNDTCPSPLF or LPR) command.
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 Used by the Option Specific Input Information
Parameter presents, in the same order, all the fields previously described
in the option specific input information table. Each entry indicates if a field
is defined for a particular option. Possible values are Y and N.
Fields Used by the Option Specific Input Information Parameter
| Field | Initialize (10) | Process file (20) | Transform data (30) | End file (40) | Terminate (50) | Description |
|---|---|---|---|---|---|---|
| Writer handle | Y | Y | Y | Y | Y | For use with writer APIs. |
| Writer name | Y | Y | Y | Y | Y | Name specified on STRPRTWTR command. |
| Printer device name | Y | Y | Y | Y | Y | Device name of the printer. |
| Writer output queue name | Y | Y | Y | Y | Y | The name of the output queue that the writer is processing. |
| Writer output queue library name | Y | Y | Y | Y | Y | The library in which the writer output queue resides. |
| Writer message queue name | Y | Y | Y | Y | Y | Name of the message queue for the started writer. |
| Writer message queue library name | Y | Y | Y | Y | Y | Name of the library in which the message queue resides. |
| Reserved | N | N | N | N | N | Reserved to preserve consistency with the print driver exit. |
| Spooled file handle | N | Y | Y | Y | N | For use with future APIs. |
| Internal job identifier | N | Y | Y | Y | N | For use with existing Spool APIs. |
| Internal spooled file identifier | N | Y | Y | Y | N | For use with existing Spool APIs. |
| Qualified job name | N | Y | Y | Y | N | Job owning spooled file |
| Spooled file name | N | Y | Y | Y | N | Name of spooled file being processed |
| Spooled file number | N | Y | Y | Y | N | Number of spooled file being processed. |
| Reserved | N | N | N | N | N | Reserved to preserve consistency with the print driver exit. |
| End file type | N | N | N | Y | N | Type of end for spooled file. |
| Termination type | N | N | N | N | Y | The type of termination by the writer. |
| Current writer form type | N | Y | Y | Y | N | Form type writer is currently processing. |
| Return alignment information | N | Y | Y | N | N | Returns alignment information along with transformed data. |
| Reserved | N | N | N | N | N | Reserved to preserve consistency with the print driver exit. |
| Number of complete pages | N | N | Y | N | N | Specifies the number of complete pages in the data to be transformed. |
| Workstation customizing object name | N | Y | N | N | N | The name of an object that consists of a table of attributes used to customize a given ASCII device. |
| Workstation customizing object library | N | Y | N | N | N | The library containing the workstation customization object. |
| Manufacturer type and model | N | Y | N | N | N | The manufacturer, type and model for a printer using transform support. |
| Reserved | N | N | N | N | N | Reserved to maintain compatibility with the Host Print Transform (QWPZHPTR) API. |
| Job system name | N | Y | Y | Y | N | Name of system job is located. |
| Spooled file create date | N | Y | Y | Y | N | Date the spooled file was created. |
| Reserved | N | N | N | N | N | Reserved to maintain compatibility with the Host Print Transform (QWPZHPTR) API. |
| Spooled file create time | N | Y | Y | Y | N | Time the spooled file was created. |
The following table shows the structure for the option specific information
output parameter. This structure is used to pass information from the transform
exit program to the writer. For more details about the fields in the following
table see, Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Return code |
| 4 | 4 | CHAR(1) | Transform file |
| 5 | 5 | CHAR(1) | Pass input data |
| 6 | 6 | CHAR(1) | Send single copy |
| 7 | 7 | CHAR(1) | Send open time commands |
| 8 | 8 | CHAR(1) | Done transforming file |
| 9 | 9 | CHAR(3) | Reserved |
| 12 | C | BINARY(4) | Offset to vertical positioning commands |
| 16 | 10 | BINARY(4) | Length of vertical positioning commands |
| 20 | 14 | BINARY(4) | Offset to print data |
| 24 | 18 | BINARY(4) | Length of print data |
| 28 | 1C | BINARY(4) | Offset to carriage return commands |
| 32 | 20 | BINARY(4) | Length of carriage return commands |
| 36 | 24 | BINARY(4) | Offset to form feed commands |
| 40 | 28 | BINARY(4) | Length of form feed commands |
| 44 | 2C | CHAR(*) | Carriage return commands |
| CHAR(*) | Form feed commands | ||
Carriage return commands. The carriage return commands contain the data stream commands which can be used to do end of line processing for alignment purposes.
Done transforming file. Indicates the transform exit program requires no further data to process the current file. This field is ignored when the pass input data field is set to 0.
Possible values are:
| 0 | Continue calling the transform exit program with the transform data (30) option. |
| 1 | The next call to the transform exit program will be with the end file (40) option. |
Form feed commands. The form feed commands contain the data stream commands which can be used to do end of page processing for alignment purposes.
Length of carriage return commands. The length, in bytes, of the carriage return commands. The carriage return commands are returned in the output specific information.
Length of form feed commands. The length, in bytes, of the form feed commands. The form feed commands are returned in the output specific information.
Length of print data. The length, in bytes, of the print data for the first line of data on the page. This includes any horizontal positioning which is done in the first line.
Length of vertical positioning commands. The length, in bytes, of the vertical positioning commands that are returned in the transformed data buffer.
Offset to carriage return commands. Offset to the carriage return commands in the output specific information. The carriage return commands contain the data stream commands which can be used to do end of line processing for alignment purposes.
Offset to form feed commands. Offset to the form feed commands in the output specific information. The form feed commands contain data stream commands which can be used to do end of page processing for alignment purposes.
Offset to print data. Offset to the first line of the print data for the page in the transformed data buffer. This first line can be printed for alignment purposes.
Offset to vertical positioning commands. Offset to the vertical positioning commands in the transformed data buffer.
Pass input data. Whether the writer passes the input data to the transform exit program.
Possible values are:
| 0 | The writer will pass the input data to the transform exit program. |
| 1 | The writer will not pass the input data to the transform exit program. |
Return code. The return code returned by the transform exit after each call.
Possible values are:
| 0 | No error occurred. |
| non zero | An error occurred. |
When the return code indicates that an error has occurred, the following is performed by the writer:
The next call to the transform exit program is the terminate process option.
The next call to the transform exit program is the end file process option.
The next call to the transform exit program is the end file process option.
The next call to the transform exit program is the terminate process
There are no additional calls to the transform exit program for this printer writer.
Send open time commands. Indicates if the open time commands returned by the transform exit program on the process file (20) call are sent before the spooled file prints.
This value is ignored when transform file is set to 0 or 1. In this case, the data returned on the process file (20) call will always be sent before the spooled file prints.
| 0 | The printer writer decides if the open time commands should be sent |
| 1 | Send the open time commands before this spooled file prints. The commands vary with the spooled file attributes. |
| 2 | Do not send any open time commands. |
Send single copy. Indicates if the transform exit program is called with process options 20, 30, and 40 for each copy requested.
| 0 | The transform exit program is called for each copy requested to print. |
| 1 | The transform exit program is called with the 20, 30, and 40 process option sequence only once for each spooled file. |
Transform file. Whether the spooled file data will be transformed.
| 0 | The spooled file data cannot be transformed. |
| 1 | The spooled file data will be transformed. |
| 2 | The spooled file data is in its final form. |
Fields Used by the Option Specific Output Information
Parameter presents, in the same order, all the fields in previously
described in the option specific output information table. Each entry indicates
if a field is used with a particular process option. Possible values are Y and
N.
Fields Used by the Option Specific Output Information Parameter
| Field | Initialize (10) | Process file (20) | Transform data (30) | End file (40) | Terminate (50) | Description |
|---|---|---|---|---|---|---|
| Return code | Y | Y | Y | Y | Y | Indicates if the transform exit program was successful in completing the specified option. |
| Transform file | N | Y | N | N | N | Allows the transform exit program to end the processing of a file, with either the Process File option. |
| Pass input data | N | Y | N | N | N | Allows the transform exit program to specify whether the writer will provide the input data or the transform exit program will read the data directly from the file. |
| Send single copy | N | Y | N | N | N | Allows the transform exit program to convert a file once, even if there are multiple copies requested. In the case of multiple copies requested, the transform exit program inserts the proper commands to print multiple copies. |
| Send open time commands | N | Y | N | N | N | Allows the transform exit program to specify if the system-generated initial (open time) commands are sent to the printer before the file prints. |
| Done transforming file | N | N | Y | N | N | For the spooled file currently being processed, it allows the transform exit program to stop the writer from calling the transform exit program with any additional process option 30 calls. |
| Reserved | N | N | N | N | N | Reserved to preserve consistency with the print driver exit. |
| Offset to vertical positioning commands | N | N | Y | N | N | The offset to the vertical positioning commands in the transformed data buffer. When alignment information has been requested, vertical positional commands are also returned in the transformed data buffer. |
| Length of vertical positioning commands | N | N | Y | N | N | The length of the vertical positioning commands that are returned the transformed data buffer. This can be used in alignment processing. |
| Offset to print data | N | N | Y | N | N | The offset to the print data for the first line of the page. This can be used for alignment processing. |
| Length of print data | N | N | Y | N | N | The length of print data for the first line of data for a page. This can be used for alignment processing. |
| Offset of carriage return commands | N | N | Y | N | N | Offset to the carriage return commands in the output specific information. The carriage return commands are data stream commands that can be used to do end of line processing for alignment purposes. |
| Length of carriage return commands | N | N | Y | N | N | The length of the carriage return commands. |
| Offset of form feed commands | N | N | Y | N | N | Offset to the form feed commands in the output specific information. The form feed commands are data stream commands that can be used to do end of page processing for alignment purposes. |
| Length of form feed commands | N | N | Y | N | N | The length of the form feed commands. |
| Carriage return commands | N | N | Y | N | N | The carriage return commands are data stream commands that can be used to do end of line processing for alignment purposes. |
| Form feed commands | N | N | Y | N | N | The form feed commands are data stream commands that can be used to do end of page processing for alignment purposes. |
| Top | Print APIs | APIs by category |