| 1 | Transform values | Input | Char(*) |
| 2 | Process values | I/O | Char(*) |
| 3 | Input data stream | Input | Char(*) |
| 4 | Output data stream | Output | Char(*) |
The Image Print Transform (IPT) exit point can be used to transform user ASCII data streams for the following reasons:
An exit program that takes the requested data stream format as input and produces the requested output data stream format must be registered to this exit point by using the Add Exit Program (QUSADDEP, QusAddExitProgram) API or the ADDEXITPGM command.
Image Print Transform (IPT) tries to determine the input data stream format and the output data stream format. Once the two data stream formats have been determined, the Retrieve Exit Information (QUSRTVEI, QusRetrieveExitInformation) API is called to determine if any exit programs have been registered that support the specified input and output data stream format combination. The following input and output data stream combinations are used in the exit program data field of the selection criteria for the API:
| Input | Output |
|---|---|
| BMP | AFPDS |
| BMP | PCL |
| BMP | PS |
| GIF | AFPDS |
| GIF | PCL |
| GIF | PS |
| PCL | AFPDS |
| PCL | PS |
| AFPDS | |
| PCL | |
| PS | |
| PS | AFPDS |
| PS | PCL |
| TIF | AFPDS |
| TIF | PCL |
| TIF | PS |
| UNKNOWN | UNKNOWN |
Note: If the input or output data stream format is unrecognized, "UNKNOWN UNKNOWN" is used in the exit program data field of the selection criteria for the Retrieve Exit Information (QUSRTVEI, QusRetrieveExitInformation) API. IPT will query up to the first ten registered exit programs using the "UNKNOWN UNKNOWN" value in the data field in an attempt to find an exit program that can successfully transform the input data stream format to the requested output data stream format. If, after querying up to ten exit programs, an exit program is not found that can handle the transform, IPT returns to the caller, stating it cannot transform the image.
IPT queries the exit point to determine if one matches both the requested input and output data stream formats. If one or more is found, IPT then queries only the first exit program listed in the Retrieve Exit Information (QUSRTVEI, QusRetrieveExitInformation) API response to see if it can handle the requested transform, using a value of 20 (process file) in the process option field of the process values parameter. If the exit program can handle the transform, it is called again with the actual transform request. If there is no exit program registered with the specified input and output data stream formats (that is, something other than "UNKNOWN UNKNOWN" in the data field area), or if there are no registered exit programs that can handle the requested transform, IPT then queries the first ten exit programs registered using "UNKNOWN UNKNOWN" in the data field area and handles it as described above. If there are no exit programs found that can handle the transform, IPT handles the request as normal, by either transforming it if it is able to or notifying the caller that the data cannot be converted.
See the Add Exit Program (QUSADDEP, QusAddExitProgram) API or the Add Exit Program (ADDEXITPGM) command for more information.
None.
Conversion information that is input to the exit program from Image Print Transform. For the format and description of this information, see Transform Values to Exit Program.
Process information that is input to the exit program from Image Print Transform. In addition, there is process information passed back from the exit program. For the format and description of this information, see Process Values to Exit Program.
The data stream to be transformed by the exit program. The input data stream is broken into manageable sized buffers and sent to the exit program one at a time.
The data stream that has been transformed by the exit program. If the data stream is larger than the buffer sent, the exit program sends it back in a buffer at a time and IPT puts it back together.
The following table shows the format of the XFRM0100 structure for the transform values parameter. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(8) | Structure version |
| 8 | 8 | BINARY(4) | Structure length |
| 12 | C | BINARY(4) | Input file format |
| 16 | 10 | BINARY(4) | Output file format |
| 20 | 14 | BINARY(4) | Invert image |
| 24 | 18 | BINARY(4) | Input decompression value |
| 28 | 1C | BINARY(4) | Output compression value |
| 32 | 20 | BINARY(4) | Output horizontal resolution |
| 36 | 24 | BINARY(4) | Output vertical resolution |
| 40 | 28 | BINARY(4) | Convert color to gray |
| 44 | 2C | BINARY(4) | Convert gray to black and white |
| 48 | 30 | BINARY(4) | Output page orientation |
| 52 | 34 | BINARY(4) | Horizontal justification from left border |
| 56 | 38 | BINARY(4) | Vertical justification from top border |
| 60 | 3C | BINARY(4) | Bits per pixel |
| 64 | 40 | BINARY(4) | Output page size |
| 68 | 44 | PACKED(15,5) | Paper width |
| 76 | 4C | PACKED(15,5) | Paper length |
| 84 | 54 | BINARY(4) | Left unprintable area |
| 88 | 58 | BINARY(4) | Right unprintable area |
| 92 | 5C | BINARY(4) | Top unprintable area |
| 96 | 60 | BINARY(4) | Bottom unprintable area |
| 100 | 64 | CHAR(12) | Reserved |
| 112 | 70 | CHAR(10) | Spooled file job name |
| 122 | 7A | CHAR(10) | Spooled file user name |
| 132 | 84 | CHAR(6) | Spooled file job number |
| 138 | 8A | CHAR(10) | Spooled file name |
| 148 | 94 | BINARY(4) | Spooled file number |
| 152 | 98 | CHAR(8) | Job system name |
| 160 | A0 | CHAR(7) | Spooled file create date |
| 167 | A7 | CHAR(1) | Reserved |
| 168 | A8 | CHAR(6) | Spooled file create time |
| 174 | AE | CHAR(2) | Reserved |
| 176 | B0 | CHAR(10) | Writer message queue name |
| 186 | BA | CHAR(10) | Writer message queue library name |
| 196 | C4 | CHAR(16) | Internal spooled file identifier |
| 212 | D4 | CHAR(16) | Internal job identifier |
| 228 | E4 | CHAR(28) | Reserved |
Bits per pixel. Number of bits per pixel to be used in the output image.
Possible values are:
| 1 | Black and white output |
| 8 | Grayscale output |
| 24 | Color output |
Bottom unprintable area. The number of pixels of unprintable area on the bottom border.
Convert color to gray. Whether to reduce the output data stream's pixel information content from color to gray. If this field is set to No, the pixel information content of the output data stream will be that of the input data stream. Setting this to Yes reduces the output pixel information content to gray scale if it would have been color and will otherwise have no effect.
| 0 | No |
| 1 | Yes |
Convert gray to black and white. Whether to reduce the output data stream's pixel information content from gray to black and white. If this field is set to No, the pixel information content of the output data stream will be that of the input data stream. Setting this to Yes forces the output to black and white.
Possible values are:
| 0 | No |
| 1 | Yes |
Horizontal justification from left border. Distance in pixels from left border to justify the image.
Input decompression value. Compression algorithm used on input data stream.
Possible values are:
| 1 | None |
| 3 | CCITT Group 3 Fax |
| 4 | CCITT Group 4 Fax |
| 5 | LZW |
| 6 | JPEG |
| 7 | Packbits |
| 8 | IBM MMR (modified-modified read) |
| 10 | BMP-RLE |
Input file format. Format of the input print or image data stream. Possible values are:
| 1 | TIFF (Tag Image File Format) |
| 2 | BMP (Bitmap) |
| 6 | GIF (Graphics Interchange Format) |
| 20 | AFPDS |
| 22 | PCL |
| 23 | PostScript |
| 25 | |
| 99 | Unknown |
Internal job identifier. The internal job identifier of the job that created the spooled file. This field will be set to blanks when the input stream is not a spooled file.
Internal spooled file identifier. The internal spooled file identifier of the spooled file being processed. This field will be set to blanks when the input stream is not a spooled file.
Invert image. If yes, black becomes white and white becomes black. This parameter has no effect for color output. It also has no effect for color images output as gray on a Printer Control Language (PCL) color printer.
Possible values are:
| 0 | No |
| 1 | Yes |
Job system name. The name of the system where the job that created this spooled file ran. This field will be set to blanks when the input stream is not a spooled file.
Left unprintable area. The number of pixels of unprintable area on the left border.
Output compression value. The algorithm used to compress the output image or print data stream. Possible values are:
| 1 | No compression |
| 4 | CCITT Group 4 Fax |
| 7 | PackBits |
| 8 | IBM MMR (modified-modified read) |
Output file format. The format of the output data stream. Possible values are:
| 20 | AFPDS (Advanced Function Printing data stream) |
| 22 | PCL (Printer Control Language) |
| 23 | PostScript |
| 99 | Unknown |
Output page orientation. How the output is oriented on paper. Possible values follow:
| 0 | Portrait. For image input files, the top of each output page is placed on the narrowest dimension of the paper. For PostScript input data streams, the orientation specified in the input data stream is used. |
| 90 | Landscape. For image input files, the top of each output page is placed on the widest dimension of the paper. For PostScript input data streams, the output is rotated 90 degrees from the orientation specified in the input data stream. |
| 180 | Portrait, rotated 180 degrees. For PostScript input data streams, the output is rotated 180 degrees from the orientation specified in the input data stream. |
| 270 | Landscape, rotated 180 degrees. For PostScript input data streams, the output is rotated 270 degrees from the orientation specified in the input data stream. |
Output page size. The paper size to be used for the output image or print data stream. See the table following the values for dimensions of each size value. Possible values are:
| 1 | Executive |
| 2 | Letter |
| 3 | Legal |
| 6 | Ledger |
| 13 | A5 |
| 26 | A4 |
| 27 | A3 |
| 45 | B5 |
| 46 | B4 |
| 50 | CONT80 |
| 51 | CONT132 |
| 80 | Monarch envelope |
| 81 | COMM10 envelope |
| 89 | COMM9 envelope |
| 90 | DL envelope |
| 91 | C5 envelope |
| 100 | B5 envelope |
| Name | Millimeters | Inches |
|---|---|---|
| Paper: | ||
| Letter | 215.9 x 279.4 | 8.5 x 11 |
| Legal | 215.9 x 335.6 | 8.5 x 14 |
| Ledger | 279.4 x 431.8 | 11 x 17 |
| Executive | 184.2 x 266.7 | 7.25 x 10.5 |
| A3 | 297 x 420 | 11.7 x 16.54 |
| A4 | 210 x 297 | 8.27 x 11.7 |
| A5 | 148 x 210 | 5.83 x 8.27 |
| B4 | 257 x 364 | 10.1 x 14.33 |
| B5 | 182 x 257 | 7.17 x 10.1 |
| CONT80 | 203.2 x 279.4 | 8 x 11 |
| CONT132 | 335.3 x 279.4 | 13.2 x 11 |
| Envelope: | ||
| Monarch | 98.4 x 190.5 | 3.875 x 7.5 |
| Commercial 9 | 98.4 x 225.4 | 3.875 x 8.875 |
| Commercial 10 | 104.8 x 241.3 | 4.125 x 9.5 |
| DL | 110 x 220 | 4.33 x 8.66 |
| B5 | 176 x 250 | 6.93 x 9.84 |
| C5 | 162 x 229 | 6.38 x 9.02 |
Output horizontal resolution. The number of horizontal pixels per inch.
Output vertical resolution. The number of vertical pixels per inch.
Paper length. Length of paper to use; units in inches.
Paper width. Width of paper to use; units in inches.
Right unprintable area. The number of pixels of unprintable area on the right border.
Reserved. The field is reserved.
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. This field will be set to blanks when the input stream is not a spooled file.
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. This field will be set to blanks when the input stream is not a spooled file.
Spooled file job name. The name of the job that the file being processed was spooled under. This field will be set to blanks when the input stream is not a spooled file.
Spooled file job number. The job number that the file being processed was spooled under. This field will be set to blanks when the input stream is not a spooled file.
Spooled file name. The name of the spooled file being processed. This field will be set to blanks when the input stream is not a spooled file.
Spooled file number. The number of the spooled file being processed. This field will be set to zero when the input stream is not a spooled file.
Spooled file user name. The user profile that the file being processed was spooled under. This field will be set to blanks when the input stream is not a spooled file.
Structure length. The length of the structure. Currently, this is set to decimal 256.
Structure version. The format identifier of the transform parameter structure. Currently, this is set to "XPRM0100".
Top unprintable area. The number of pixels of unprintable area on the top border.
Vertical justification from top border. Distance in pixels from top border to justify the image.
Writer message queue library name. The name of the library in which the writer message queue resides. This field will be set to blanks when no writer message queue is associated with the file or buffer.
Writer message queue name. The name of the message queue to which the writer issues messages. This field will be set to *NONE when no writer message queue is associated with the file or buffer.
The following table shows the structure for the process values parameter. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(8) | Structure version |
| 8 | 8 | BINARY(4) | Structure length |
| 12 | C | BINARY(4) | Process option |
| 16 | 10 | BINARY(4) | Input data stream length |
| 20 | 14 | BINARY(4) | Output data stream length |
| 24 | 18 | BINARY(4) | Length of returned data |
| 28 | 1C | CHAR(1) | Transform ability |
| 29 | 1D | CHAR(3) | Reserved |
| 32 | 20 | BINARY(4) | Finished transform |
Finished transform. (OUTPUT) Signals when transform of the input data stream has completed. Possible values are:
| 0 | No |
| 1 | Yes |
Input data stream length. (INPUT) Length of data being sent to transform. The maximum value is 16700000. If the total is larger than this maximum, it will be sent a buffer at a time.
Length of returned data. (OUTPUT) Length of transformed data returned by the exit program. If this field is larger than the output buffer length, it must be returned as separate buffers in the correct order. This is accomplished by setting the finished transform field to No for all output data streams returned except the last one, which must have the finished transform field set to Yes. If a terminating error occurs in the process of transforming, the exit program may set the length to a negative value, and the process will be halted.
Output data stream length. (OUTPUT) Length of buffer for transformed output data stream.
Process option. (INPUT) The action for the exit program to take. The first option is process (20). Possible values are:
| 20 (Process file) | A data stream is available to be transformed. The transform and process parameter structures and other information is passed. The exit program decides whether to transform the data and sets the transform ability field in the process parameter structure and returns. |
| 30 (Transform data) | The exit program is called if the transform ability field is set to 1 (can transform). The data to be transformed is passed in the input data stream parameter. The transformed data is returned in the output data stream parameter. The exit program is called repetitively with process option 30 to retrieve multiple output data steams until the exit program indicates it is done with this input data stream by setting the finished transform to Yes. This process is repeated until all the data required in the input data stream has been passed to the exit program. At that time, the exit program is called with a Process option 40. |
| 40 (End file) | This option informs the exit program that it has received all the data from the input data stream. No data is passed on this call. The exit program returns additional transformed data through the output data stream buffer until the exit program indicates it is complete by setting the finished transform to Yes. |
| 50 (Terminate) | The exit program will be notified that processing on this data stream has stopped and the exit program should terminate. Option 50 may be used after any other process option. |
Reserved. Space reserved for future use.
Structure length. (INPUT) The length of the structure. Currently, this is set to decimal 36.
Structure version. (INPUT) The format identifier of the transform parameter structure. Currently, this is set to "IPRM0100".
Transform ability. (OUTPUT) Used by the exit program, when running during process option 20, to notify Image Print Transform whether the exit program can transform the data stream.
Possible values are:
| 0 | Unable to transform |
| 1 | Able to transform |
| Top | Print APIs | APIs by category |