Host Print Transform (QWPZHPTR, QwpzHostPrintTransform) API
Required Parameter Group:
| 1 | Process option | Input | Binary(4) |
| 2 | Option specific input information | Input | Char(*) |
| 3 | Length of option specific input information | 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 buffer | Output | Char(*) |
| 7 | Length of option specific output information buffer | Input | Binary(4) |
| 8 | Length of option specific output information available | 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) |
| 12 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Service Program: QWPZHPT1
Threadsafe: No
The Host Print Transform (OPM, QWPZHPTR; ILE, QwpzHostPrintTransform) API provides an interface to the host print transform (HPT) function. The host print transform transforms SCS or AFP™ data to ASCII data.
USERASCII spooled files will be converted in the same manner as data streams supplied to the Convert Image (QIMGCVTI, QimgCvtImg) API. If the input data stream is not supported, data is returned as if it were in its final form.
For informational purposes, two sample flows are given to show the interaction between the caller and the Host Print Transform API. The first sample flow illustrates the use of the API to transform a spooled file to an ASCII datastream in order to print the file on a printer using a printer device or workstation customization object of type TRANSFORM.
- The Host Print Transform API is called with the initialize (10) process
option.
The Host Print Transform API sets any initial information and returns to the caller.
- The first eligible spooled file is selected for processing.
The Host Print Transform API is called with the process file (20) process option. The name and identifier of the spooled file is passed in the input information.
The Host Print Transform API determines if it will transform the spooled file and returns to the caller an indication whether it will transform the spooled file. The end file (40) process option must be used before another process file (20) process option is allowed.
- The Host Print Transform API is called with the transform data (30) process
option and the data to be transformed.
You can use the Get Spooled File Data (QSPGETSP) API to get the data.
The Host Print Transform API transforms the data and passes back the transformed data to the caller. This step happens repeatedly until the entire spooled file has been passed to the Host Print Transform API. Alignment data also could be returned with this option.
- The Host Print Transform API also can be called with the maintain state
(34) process option or the transform pages (36) process option.
The maintain state process option maintains information about the transforming of the spooled file data, but does not return the transformed data.
The transform pages process option provides additional data at the start and end of each page.
These process options can be intermixed with the transform data process option; however, it is recommended that transitions occur at complete page boundaries.
- The Host Print Transform API is called with the end file (40) process
option.
The Host Print Transform API returns to the caller any remaining data to be sent to the printer.
- The caller selects the next eligible spooled file to be transformed.
Steps starting with the process file (20) process option are repeated.
- All transforming completed.
The Host Print Transform API is called with the terminate (50) process option. The Host Print Transform API cleans up any work spaces that it has created and returns to the caller.
The second sample flow illustrates the use of the API to transform a spooled file to a PDF using a workstation customization object of type CTXFORM.
- The Host Print Transform API is called with the initialize (10) process
option.
The Host Print Transform API sets any initial information and returns to the caller.
- The first eligible spooled file is selected for processing.
The Host Print Transform API is called with the process file (20) process option. The name and identifier of the spooled file is passed in the input information. A workstation customization object of type *CTXFORM is passed in.
The Host Print Transform API checks to see that the iCTT transform service is available and determines if it will transform the spooled file. It returns to the caller an indication whether it will transform the spooled file. It also passes back an indication that it will read the spooled file directly and the caller should not pass it any data. The end file (40) process option must be used before another process file (20) process option is allowed.
- The Host Print Transform API is called with the transform data (30) process
option.
The Host Print Transform API reads the spooled file data, transforms the data, and passes back the transformed data to the caller. If the buffer used by the caller will not hold all of the transformed data, the Host Print Transform API will indicate to the caller that it is not done transforming the file. The caller must call the API again with another transform data (30) process option. This step happens repeatedly until the entire transformed file has been passed back to the caller at which point the Host Print Transform API will indicate that it is done transforming the file.
- The Host Print Transform API is called with the end file (40) process
option.
The Host Print Transform API returns to the caller any remaining data to be sent to the printer.
- The caller selects the next eligible spooled file to be transformed.
Steps starting with the process file (20) process option are repeated.
- All transforming completed.
The Host Print Transform API is called with the terminate (50) process option. The Host Print Transform API cleans up any work spaces that it has created and returns to the caller.
Authorities and Locks
- Device Description Authority
- *USE
- Device Description Lock
- *EXCLRD
- Workstation Customization Object Authority
- *USE
- Workstation Customization Object Library Authority
- *EXECUTE
- Input Spooled File Authority (Needed when Host Print Transform API reads spooled file)
- See Input Spooled File Authorities.
Input Spooled File Authorities
If the Host Print Transform API must read the spooled file such as when transforming to PDF, the requester is authorized to the input spooled file if one or more of the following conditions are met:
- The requester is the owner of the spooled file.
- The requester has *READ authority to the queue on which the spooled file resides, and the queue is specified as DSPDTA(*YES).
- The requester has *SPLCTL authority.
- The requester has *JOBCTL authority, and the queue on which the spooled file resides is specified as OPRCTL(*YES).
- The requester has ownership of the queue on which the spooled file resides, and the queue is specified as AUTCHK(*OWNER).
- The requester has read, add, and delete authorities to the queue on which the spooled file resides, and the queue is specified as AUTCHK(*DTAAUT).
Required Parameter Group
- Process option
- INPUT; BINARY(4)
The action for the host print transform to take. The first option should be initialize (10).
Possible values are:
10 (Initialize) The Host Print Transform API sets any initial information with this option. 20 (Process file) A spooled file is available to be transformed. The spooled file name and other information is passed in the option specific input information parameter to the Host Print Transform API. The Host Print Transform API decides whether to transform the data and sets the transform file field in the output information structure. The API also determines whether or not it will read the spooled file and sets the pass input data field in the output information structure. Open time commands (initial formatting commands for the file) are returned in the transformed data buffer for SCS data streams when the caller is to pass in the data. 30 (Transform data) The Host Print Transform API is called to transform the spooled file. If the caller is told to pass the input data: - The data to be transformed is passed in the spooled file data buffer parameter.
- The transformed data is returned in the transformed data buffer.
- This process is repeated until all the input data has been processed.
- If requested, alignment data is also returned. When alignment data is requested, offsets and lengths for the alignment data are returned in the option specific output information buffer parameter.
- No data is passed to the API.
- As much data as will fit in the transformed buffer is returned.
- This process is repeated until all output data has been returned.
- Alignment data is not returned.
34 (Maintain state) The Host Print Transform API is called when data is available to be transformed, but the transformed data is not returned to the caller. This option is used to maintain the host print transform's state for later processing of a specific page. Note: This option is valid only for SCS and AFPDS data when the caller is passing the data to the API. 36 (Transform pages) The Host Print Transform API is called when data is available to be transformed. The data to be processed is passed in the spooled file data buffer parameter. This option is used to provide additional data at the beginning and end of each page. The transformed data is returned in the transformed data buffer. Note: This option is valid only for SCS and AFPDS data when the caller is passing the data to the API. 40 (End file) The Host Print Transform API is informed that all data has been processed. No data is passed on this call. The Host Print Transform API may return additional data to the caller as an append to the end of the printed data. This option is used even if the Host Print Transform API did not transform any data.
50 (Terminate) All processing is complete. The Host Print Transform API performs cleanup in any user spaces it used. Option 50 may be used after any other process option.
- Option specific input information
- INPUT; CHAR(*)
Information that is provided to the Host Print Transform API. For the format and description of this information, see Option Specific Input Information.
- Length of option specific input information
- INPUT; BINARY(4)
The length of the option specific input information specified in the option specific input information parameter. This length must be either 243 bytes, 273 bytes, or 296 bytes.
- Spooled file data buffer
- INPUT; CHAR(*)
The spooled file data to be transformed.
- Length of spooled file data buffer
- INPUT; BINARY(4)
The length of the spooled file data specified in the spooled file data buffer parameter.
- Option specific output information buffer
- OUTPUT; CHAR(*)
Information that is returned from the Host Print Transform API to the caller. For the format and description of this information, see Option Specific Output Information.
- Length of option specific output information buffer
- INPUT; BINARY(4)
The size, in bytes, of the option specific output information buffer.
- Length of option specific output information available
- OUTPUT; BINARY(4)
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 buffer parameter, all available information has been returned. If this length is greater than the length of the option specific output information buffer parameter, only data up to the length provided is returned in the option specific output information buffer.
- Transformed data buffer
- OUTPUT; CHAR(*)
Spooled file data that has been transformed by the Host Print Transform API. The data in this buffer can be sent to a printer. Alignment data, if requested, is also returned in the transformed data buffer. The lengths and offsets of the alignment information are returned in the option specific output information buffer parameter. For the format and description of this information, see Option Specific Output Information.
This buffer must be large enough to contain all of the transformed data. As a general rule, this buffer should be twice the size of the length of the spooled file data buffer.
- Length of transformed data buffer
- INPUT; BINARY(4)
The size, in bytes, of the transformed data buffer.
- Length of transformed data available
- OUTPUT; BINARY(4)
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. The remaining data is lost. An error message, CPF6DF9, is also returned.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
The following table presents, in the same order, all the parameters previously described. Each entry indicates whether a parameter will be used by the Host Print Transform API. Y indicates yes and N indicates no.
| Parameter | Initialize (10) | Process File (20) | Transform Data (30,34,36) | End File (40) | Terminate (50) | Description |
|---|---|---|---|---|---|---|
| Process option | 10 | 20 | 30,34,36 | 40 | 50 | Process option |
| Option specific input information | N | Y | Y | N | N | See description of this parameter. |
| Length of option specific input information | N | Y | Y | N | N | 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 the spooled file data buffer. |
| Option specific output information buffer | N | Y | Y | Y | N | See description of this parameter. |
| Length of option specific output information buffer | N | Y | Y | Y | N | See description of this parameter. |
| Length of option specific output information available | N | Y | Y | Y | N | 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 | Y | 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). Alignment information is also returned in this buffer, if requested. |
| Length of transformed data buffer | N | Y | Y | Y | Y | The size, in bytes, of the transformed data buffer. |
| Length of transformed data available | N | Y | Y | Y | Y | The number of bytes of transformed data that is available. |
| Error code | Y | Y | Y | Y | Y | Error reporting. |
Option Specific Input Information
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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(16) | Reserved |
| 16 | 10 | CHAR(10) | Reserved |
| 26 | 1A | CHAR(10) | Printer device name |
| 36 | 24 | CHAR(20) | Reserved |
| 56 | 38 | CHAR(20) | Reserved |
| 76 | 4C | CHAR(10) | Reserved |
| 86 | 56 | CHAR(10) | Reserved |
| 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) | Reserved |
| 184 | B8 | BINARY(4) | Reserved |
| 188 | BC | CHAR(10) | Reserved |
| 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(10) | Paper source 1 |
| 253 | FD | CHAR(10) | Paper source 2 |
| 263 | 107 | CHAR(10) | Envelope source |
| 273 | 111 | CHAR(1) | 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 |
Field Descriptions
Envelope source. The size of the envelope installed in the envelope source. This field is used only when the value for the printer device name field is *NONE. This field is not used when transforming to PDF. If this field is not specified or the value is not valid, the special value of *MFRTYPMDL is used.
Possible values are:
| *NONE | There is no envelope source. |
| *MFRTYPMDL | The envelope size suggested by the manufacturer type and model is used. |
| *MONARCH | The envelope is monarch-size (3.875 x 7.5 inches). |
| *NUMBER9 | The envelope is size number 9 (3.875 x 8.875 inches). |
| *NUMBER10 | The envelope is size number 10 (4.125 x 9.5 inches). |
| *B5 | The envelope is size B5 (176 mm x 250 mm). |
| *C5 | The envelope is size C5 (162 mm x 229 mm). |
| *DL | The envelope is size DL (110 mm x 220 mm). |
Note: This field is not validity checked when a name is specified in the printer device name field.
Internal job identifier. The internal job identifier of the job that owns the spooled file. The identifier is not valid following an initial program load (IPL). If you attempt to use it after an IPL, an exception occurs. This field must be blank if a name is given for the qualified job name.
Internal spooled file identifier. The internal spooled file identifier of the spooled file being processed. The identifier is not valid following an initial program load (IPL) or if the spooled file has been moved between auxiliary storage pools (ASPs). If you attempt to use an invalid internal spooled file identifier, an exception occurs. This field must be blank if a name is given for the spooled file name.
Job system name. The name of the system where the job that created the spooled file ran or blank when the spooled file name is *INT. This field is considered after the job name, user name, job number, spooled file name, and spooled file number field requirements have been met.
The possible values are:
| *ONLY | There is one job with the specified job name, user name, job number, spooled file name, spooled file number, spooled file create date, and spooled file create time. |
| *CURRENT | The job on the current system with the specified job name, user name, job number, spooled file name, spooled file number, spooled file create date, and spooled file create time is used. |
| *ANY | The job system name is not considered when selecting a spooled file. Use this value when you want the Spooled file create date and Spooled file create time parameters to take precedence over the job system name when selecting a spooled file. |
| system-name | The name of the system the job that created the spooled file ran on. |
When the Length of option specific input information parameter is less than 296 bytes, the API assumes blanks when the spooled file name is *INT. When spooled file name is not *INT,the API assumes *ONLY.
Manufacturer type and model. The manufacturer, type, and model for a printer using transform support. This field must be blank when a printer device name is specified.
| *WSCST | The workstation customizing object is used to obtain the manufacturer type and model. |
| type and model | The manufacturer type and model. For a list of valid manufacturer types and models, see the MFRTYPMDL parameter on the Create Device Description (Printer) (CRTDEVPRT) command in the Control language topic collection. |
| blank | The manufacturer type and model is retrieved from the printer device. |
Note: This field is only checked for the first process file (20) option received for a session. If this value is to change for a subsequent process file (20) option, a terminate option (50) and an initialize option (10) must be done before the process file (20).
Number of complete pages. The number of complete pages that are contained in the spooled file data input buffer.
Paper source 1. The size of the paper installed in paper source 1. This field is used only when the value for the printer device name field is *NONE. This field is not used when transforming to PDF. If this field is not specified or the value is not valid, the special value of *MFRTYPMDL is used.
Possible values are:
| *NONE | There is no paper source 1 or the paper is manually fed into the printer. |
| *MFRTYPMDL | The paper size suggested by the manufacturer type and model is used. |
| *LETTER | The paper for this source is letter-size (8.5 x 11 inches). |
| *LEGAL | The paper for this source is legal-size (8.5 x 14 inches). |
| *EXECUTIVE | The paper for this source is executive-size (7.25 x 10.5 inches). |
| *LEDGER | The paper for this source is ledger-size (8.5 x 17 inches). |
| *A3 | The paper for this source is size A3 (297 mm x 420 mm). |
| *A4 | The paper for this source is size A4 (210 mm x 297 mm). |
| *A5 | The paper for this source is size A5 (148 mm x 210 mm). |
| *B4 | The paper for this source is size B4 (257 mm x 364 mm). |
| *B5 | The paper for this source is size B5 (182 mm x 257 mm). |
| *CONT80 | The paper for this source is 8.0 inches wide and a continuous form. |
| *CONT132 | The paper for this source is 13.2 inches wide and a continuous form. |
Note: This field is not validity checked when a name is specified in the printer device name field.
Paper source 2. The size of the paper installed in paper source 2. This field is used only when the value for the printer device name field is *NONE. This field is not used when transforming to PDF. If this field is not specified or the value is not valid, the special value of *MFRTYPMDL is used.
Possible values are:
| *NONE | There is no paper source 2. |
| *MFRTYPMDL | The paper size suggested by the manufacturer type and model is used. |
| *LETTER | The paper for this source is letter-size (8.5 x 11 inches). |
| *LEGAL | The paper for this source is legal-size (8.5 x 14 inches). |
| *EXECUTIVE | The paper for this source is executive-size (7.25 x 10.5 inches). |
| *LEDGER | The paper for this source is ledger-size (11 x 17 inches). |
| *A3 | The paper for this source is size A3 (297 mm x 420 mm). |
| *A4 | The paper for this source is size A4 (210 mm x 297 mm). |
| *A5 | The paper for this source is size A5 (148 mm x 210 mm). |
| *B4 | The paper for this source is size B4 (257 mm x 364 mm). |
| *B5 | The paper for this source is size B5 (182 mm x 257 mm). |
| *CONT80 | The paper for this source is 8.0 inches wide and a continuous form. |
| *CONT132 | The paper for this source is 13.2 inches wide and a continuous form. |
Note: This field is not validity checked when a name is specified in the printer device name field.
Printer device name. The name of the printer device.
Possible values are:
| *NONE | There is no printer device associated with the transform. Necessary information will be used from the workstation customizing object, the manufacturer type and model, various spooled file attributes, and the paper sources. |
| name | The name of the printer device. |
Note: When a device name is specified for this field, the manufacturer type and model must be blank and the work station customizing object name must be *NONE.
Note: This field is only checked for the first process file (20) option received for a session. If this value is to change for a subsequent process file (20) option, a terminate option (50) and an initialize option (10) must be done before the process file (20).
Qualified job name. The qualified job name of the job that owns the spooled file.
The qualified job name has three parts:
| job name | CHAR(10). A specific job name, or one of the following special
values:
|
||||
| user name | CHAR(10). A specific user profile name, or blanks when the job name is * or *INT. | ||||
| job number | CHAR(6). A specific job number, or blanks when the job name is * or *INT. |
Reserved. An ignored field.
Return alignment data. Whether the transform should return data to the caller that can be used for alignment purposes.
| 0 | Do not return alignment information. |
| 1 | Return alignment information. |
Spooled file create date. The date, based on local job time, that the spooled file was created on the system or blank when the spooled file name is *INT. This parameter is considered after the job name, user name, job number, spooled file name, spooled file number, and job system name parameter requirements have been met. The date must be in the CYYMMDD format or one of the following special values:
| *ONLY | There is only one spooled file with the specified job name, user name, job number, spooled file name, spooled file number, and job system name. |
| *LAST | The spooled file with the latest date and time which also has the specified job name, user name, job number, spooled file name, spooled file number, and job system name is used. |
| date | The date the spooled file was created on the system in the format CYYMMDD. See field Date file opened in API QUSRSPLA under field descriptions for more information about the date format. |
When the Length of option specific input information parameter is less than 296 bytes, the API assumes blanks when the spooled file name is *INT. When spooled file name is not *INT, the API assumes *ONLY.
Spooled file create time. The time, in local job time, that the spooled file was created on the system. This field must be set to blanks when special values *LAST or *ONLY are used for field Spooled file create date. This field must be set if the spooled file create date has a date specified. This field is considered after the job name, user name, job number, spooled file name, spooled file number, job system name, and spooled file create date field requirements have been met.
The time must be in the HHMMSS format or one of the following special values:
| *ONLY | There is only one spooled file with the specified job name, user name, job number, spooled file name, spooled file number, job system name, and spooled file create date. |
| *LAST | The spooled file with the latest time which also has the specified job name, user name, job number, spooled file name, spooled file number, job system name, and spooled file create date is used. |
| time | The time the spooled file was created on the system in the format HHMMSS. See field Time file opened in API QUSRSPLA under field descriptions for more information about the time format. |
| blanks | This field must be set to blanks if the spooled file create date field is set to *LAST or *ONLY. |
When the Length of option specific input information parameter is less than 296 bytes, the API assumes blanks for this field.
Spooled file name. The name of the spooled file being processed.
You can use this special value for the name:
| *INT | The internal spooled file identifier is used to locate the spooled file. |
Spooled file number. The number of the spooled file being processed. The valid range is 1 through 999999.
The following special values are supported for this field:
| 0 | Only one spooled file from the job has the specified file name. Therefore, the number of the spooled file is not necessary. |
| -1 | This uses the highest-numbered spooled file with the specified spooled file name. |
| -2 | The spooled file number is not used to determine which spooled file to process. Use this value when you want the Job system name field or the Spooled file create date and Spooled file create time fields to take precedence over the spooled file number when selecting a spooled file. |
Note: This field must contain a valid value even if the value for the spooled file name field is *INT.
A value is required because the API performs validity checking on all fields.
Workstation customizing object library. The library containing the workstation customizing object.
Note: This field is only checked for the first process file (20) option received for a session. If this value is to change for a subsequent process file (20) option, a terminate option (50) and an initialize option (10) must be done before the process file (20).
Workstation customizing object name (WSCST). The name of an object that consists of a table of attributes used to customize a given ASCII device. This field must be *NONE when a printer device name is specified.
Possible values are:
| *NONE | There is no workstation customizing object. The workstation customizing object is obtained from the printer device. |
| name | The name of the workstation customizing object, which has been created by the Create Work Station Customizing Object (CRTWSCST) command. |
Note: This field is only checked for the first process file (20) option received for a session. If this value is to change for a subsequent process file (20) option, a terminate option (50) and an initialize option (10) must be done before the process file (20).
The following table presents, in the same order, all the fields previously described in the option specific input information table. Each entry indicates whether a field will be defined for a particular option. Y indicates yes and N indicates no.
| Field | Initialize (10) | Process File (20) | Transform Data (30,34,36) | End File (40) | Terminate (50) | Description |
|---|---|---|---|---|---|---|
| Reserved | N | N | N | N | N | Reserved. |
| Reserved | N | N | N | N | N | Reserved. |
| Printer device name | N | Y | N | N | N | Device name of the printer. |
| Reserved | N | N | N | N | N | Reserved. |
| Reserved | N | N | N | N | N | Reserved. |
| Reserved | N | N | N | N | N | Reserved. |
| Reserved | N | N | N | N | N | Reserved. |
| Internal job identifier | N | Y | N | N | N | For use with existing spooled file APIs. |
| Internal spooled file identifier | N | Y | N | N | N | For use with existing spooled file APIs. |
| Qualified job name | N | Y | N | N | N | Job owning spooled file. |
| Spooled file name | N | Y | N | N | N | Name of spooled file being processed. |
| Spooled file number | N | Y | N | N | N | Number of spooled file being processed. |
| Reserved | N | N | N | N | N | Reserved. |
| Reserved | N | N | N | N | N | Reserved. |
| Reserved | N | N | N | N | N | Reserved |
| Reserved | N | N | N | N | N | Reserved. |
| Return alignment information | N | Y | Y | N | N | Return alignment information along with transformed data. |
| Reserved | N | N | N | N | N | Reserved. |
| Number of complete pages | N | N | Y | N | N | The number of complete pages in the data to be transformed. |
| Workstation customizing object name | N | Y | N | N | N | The name of the object that consists of a table of attributes used to customize an ASCII device. |
| Workstation customizing object library | N | Y | N | N | N | The name of the library containing the workstation customizing object. |
| Manufacturer type and model | N | Y | N | N | N | The manufacturer, type, and model of the ASCII device using the host print transform function. |
| Paper source 1 | N | Y | N | N | N | The size of the paper in paper source 1. |
| Paper source 2 | N | Y | N | N | N | The size of the paper in paper source 2. |
| Envelope source | N | Y | N | N | N | The size of the envelope in the envelope source. |
Option Specific Output Information
The following table shows the structure for the option specific output information buffer. This structure is used to pass information from the Host Print Transform API to the caller. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Reserved |
| 4 | 4 | CHAR(1) | Transform file |
| 5 | 5 | CHAR(1) | Pass input data |
| 6 | 6 | CHAR(2) | Reserved |
| 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 |
| CHAR(*) | Carriage return commands | ||
| CHAR(*) | Form feed commands | ||
Field Descriptions
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 host print transform requires no further data to process the current file. This field should be ignored when the pass input data field is set to 0.
| 0 | Continue calling the host print transform with the transform data (30) option. |
| 1 | The next call to the host print transform will be with the end file (40) option. |
Form feed commands. The form feed commands contain 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 that 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 that 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 that 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 caller passes the input data to the host print transform .
Possible values are:
| 0 | The caller will pass the input data to the host print transform . |
| 1 | The caller will not pass the input data to the host print transform . The host print transform will read the data directly from the file. |
Reserved. An ignored field.
Transform file. Whether the spooled file data will be transformed.
| 0 | The spooled file data cannot be transformed. |
At least one of the following conditions exists:
|
|
| 1 | The spooled file data will be transformed. |
| 2 | The spooled file data is already in its final form. |
The following table presents, in the same order, all the fields previously described in the option specific output information table. Each entry indicates whether a field will be used with a particular option. Y indicates yes and N indicates no.
The length and offset fields describe the format of the transformed data buffer when alignment data has been requested.
| Field | Initialize (10) | Process File (20) | Transform Data (30,34,36) | End File (40) | Terminate (50) | Description |
|---|---|---|---|---|---|---|
| Reserved | N | N | N | N | N | Reserved |
| Transform file | N | Y | N | N | N | Informs the caller that the Host Print Transform API can be called with either the process file process option, or the transform data process option. |
| Pass input data | N | Y | N | N | N | Allows the host print transform to specify whether the caller will provide the input data or the host print transform will read the data directly from the file. |
| Reserved | N | N | N | N | N | Reserved |
| Done transforming file | N | N | Y | N | N | For the spooled file currently being processed, it allows the host print transform to stop the caller from calling the host print transform with any additional process option 30 calls. |
| Reserved | N | N | N | N | N | Reserved |
| 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 is 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 in 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 to 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 for alignment. |
| Form feed commands | N | N | Y | N | N | The form feed commands for alignment. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF2625 E | Not able to allocate object &1. |
| CPF2634 E | Not authorized to object &1. |
| CPF2702 E | Device description &1 not found. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3C33 E | Spooled file number &1 is not valid. |
| CPF3C40 E | Spooled file &4 not found. |
| CPF3C41 E | More than one spooled file with same name. |
| CPF3C42 E | User name or job number is not blank. |
| CPF3C43 E | Internal job identifier is not valid. |
| CPF3C44 E | Internal spooled file identifier is not valid. |
| CPF3C58 E | Job name specified is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF33C9 E | Spooled file name parameter cannot be blank. |
| CPF3309 E | No files named &1 are active. |
| CPF3330 E | Necessary resource not available. |
| CPF333B E | Job system name is not valid. |
| CPF333C E | Spooled file create date is not valid. |
| CPF333D E | Spooled file create time is not valid. |
| CPF333E E | Spooled file create time is not blank. |
| CPF333F E | Job system name is not blank. |
| CPF3342 E | Job &5/&4/&3 not found. |
| CPF3343 E | Duplicate job names found. |
| CPF3344 E | File &1 number &2 no longer in the system. |
| CPF335B E | Spooled file create date is not blank. |
| CPF3492 E | Not authorized to spooled file. |
| CPF6DF2 E | AFP data stream in user space &1 not valid. |
| CPF6DF4 E | Object &2 in library &3 contains unrecognizable data. |
| CPF6DF5 E | Value &1 not valid for process option parameter. |
| CPF6DF6 E | Value &1 not valid for return alignment field. |
| CPF6DF7 E | Option specific input information field values not valid. |
| CPF6DF8 E | Data cannot be transformed. |
| CPF6DF9 E | Transformed data buffer too small. |
| CPF6DFB E | Error occurred while transforming data. |
| CPF6DFF E | Number of complete pages value &1 not valid. |
| CPF8105 E | Device description &4 damaged. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9804 E | Object &2 in library &3 damaged. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPFCE01 E | Required product option not available. |
| CPFCE02 E | Unable to access the required transform service. |
| CPFCE03 E | A data stream error was detected. |
| CPFCE05 E | Transformation task cancelled due to a print fidelity error. |
| CPFCE06 E | Error occurred while transforming print data. |
| CPFCE07 E | The transform service job terminated due to a critical error. |
| CPFCE08 E | SCS data stream is not valid. |
| CPFCE09 E | SCS data stream is not valid. |
API Introduced: V3R7
| Top | Print APIs | APIs by category |