Convert Image (QIMGCVTI, QimgCvtImg) API

The Convert Image (OPM, QIMGCVTI; ILE, QimgCvtImg) API converts an image or print data stream from one format to another, and optionally prints the result. The input and output data streams can reside in a stream file, a spooled file, or main storage. The supported input data stream formats are Graphics Interchange Format (GIF), Tag Image File Format (TIFF), OS/2 and Windows Bitmap (BMP), and PostScript Level. The supported output data stream formats are Advanced Function Print (AFP), Hewlett-Packard Printer Control Language (PCL), and PostScript Level 1.

In addition to the input data stream formats listed above, the following input data stream formats may be supported through the use of a valid registered exit program: Hewlett-Packard Printer Control Language (PCL) and Portable Document Format (PDF). In addition to the output data stream formats listed above, the following output data stream format may be supported through the use of a valid registered exit program: PostScript (including Level 2 and above). By specifying UNKNOWN for the input data stream or the output data stream, the user may also, through the use of a valid registered exit program, transform data streams that are not listed here.

For more information, refer to the Printing topic.

Authorities and Locks

Image Configuration Authority

*USE

Image Configuration Lock

*SHRRD

Input Stream File Authority

*R

Input Stream File Open Sharing Mode

Share with readers

All Directory in Input Path Authority

*X

Input Spooled File Authority

See Input Spooled File Authorities.

Input Spooled File Lock

*LSRD

Font Stream File Authority

*R

Font Stream File Open Sharing Mode

Share with readers

All Directory in Font Path Authority

*X

Output Stream File Authority

*W

Output Stream File Open Sharing Mode

Share with neither readers nor writers

All Directory in Output Path Authority

*X

Lowest Directory in Output Path Authority

*XW

Printer Device Authority

*USE

Output Queue Authority

*USE

Printer File Authority

*USE

Printer File Lock

*SHRNUP

Input Spooled File Authorities

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

Control structure

INPUT; CHAR(*)

Information that controls the conversion process. This information does not pertain specifically to either the input or output image or print data streams. See Control Structure Format for information about the format.

Input image structure

INPUT;CHAR(*)

A description of the input image or print data stream. See Input Image Structure Format for information about the format.

Main storage input image

INPUT;CHAR(*)

When the format field of the input image structure is IMGI0300, this parameter contains the input image or print data stream.

When this parameter does not contain the input data stream, it must contain 4 bytes of hexadecimal zeros.

Output image structure

INPUT;CHAR(*)

A description of the output image or print data stream and where it is to be written. See Output Image Structure Format for information about the format.

Main storage output image

OUTPUT; CHAR(*)

When the format field of the output image structure is IMGO0300, this parameter is the destination of the converted image or print data stream.

Notes:

1. The space provided field of the output image structure specifies the available size of this storage area.
2. The output data stream length field of the feedback structure specifies the amount of storage used by the converted data stream.
3. If the space provided field is insufficient to contain the converted data stream, an error condition is returned, and no data stream is returned in this parameter.

Feedback structure

OUTPUT;CHAR(*)

Additional output information from the API, such as a spooled file identifier, size of main storage output, or a handle for future API calls for multiple page output. See Feedback Structure Format for information about the format.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Control Structure Format

The table below shows the organization of the control structure parameter. For detailed descriptions of each field, see Field Descriptions.

Field Descriptions

Cancel on error. Whether the conversion should be ended when a non catastrophic error condition is detected. When yes is specified, the severity level field may be used to control which errors end the conversion.

Possible values are:

Color reduction. Whether or not to reduce the output data stream's pixel information content. If color reduction is set to same, the pixel information content of the output data stream will be either that of the input data stream or the destination device, whichever is less. Setting color reduction to gray scale will reduce the output pixel information content to gray scale if it would have been color and will otherwise have no effect. Setting color reduction to black and white will force the output to black and white. See Color Reduction Field for more details.

Possible values are:

Feedback structure format. The format of the feedback structure. See Feedback Structure Format for a description of the feedback structure. This field must contain the value IMGF0100.

Format. The format of the control structure. This field must contain the value IMGC0100.

Handle for multipage output. This parameter is not passed to any transform program registered under exit point QIBM_QIMG_TRANSFORMS. The handle that was returned in the feedback structure of a prior call to this API that specified first for the operation field. See Feedback Structure Format and Multipage Output for more information.

The handle is required when append, last, or end is specified for the operation field. For all other values of operation, this field must be set to hexadecimal zeros.

Horizontal justify. The horizontal position of an image on the page if the image is smaller than the page.

Possible values are:

Note: This field has no effect for PostScript input data streams. It also may not work as expected if the input image is larger than the page.

Keep color. Whether all coloring in the source data stream must be kept. If the conversion would result in loss of the number of colors or number of gray scale shades, it is ended with an error condition and no converted data stream is produced.

Possible values are:

Note: This field has no effect for PostScript input data streams.

Keep quality. This parameter is not passed to any transform program registered under exit point QIBM_QIMG_TRANSFORMS. Whether image or print resolution must be kept. If the conversion would result in loss of resolution, it is ended with an error condition and no converted data stream is produced.

Possible values are:

Note: This field has no effect for PostScript input data streams or for any other data streams which do not contain resolution information.

Length. The length of the control structure. This length must be 52 when the end option is specified for the operation field. In all other cases, this length must be 100, or an error is returned.

Operation. Whether or not a conversion is done, and if so, when the conversion is to take place.

Possible values are:

The calculate option selects the immediate or delayed option, based on the destination of the converted data stream.

The delayed option is only valid when output is spooled. See format IMGO0200 in Output Image Structure Format for output specifications.

When no conversion is specified for operation and output is spooled to a PCL or PostScript printer, the input data stream is passed through to the printer. The caller must ensure that the input image or print data stream is compatible with the destination printer. Otherwise, results are unpredictable.

When first, append, or last is specified, the input is converted before control is returned to the API caller.

Refer to Multipage Output for more details about the first, append, last, and end options.

Multipage conversion is not supported when transforming to an exit program.

Resize. This parameter is not passed to any transform program registered under exit point QIBM_QIMG_TRANSFORMS. Controls resizing of the output print or image data stream relative to the page size. Resize does not change the aspect ratio of the image unless the stretch field is set to 1 (yes).

Possible values are:

Note: Resize works by changing the resolution in the output data stream and relies on the printer's ability to support that resolution. Consequently, resize will not work on all printers. Resize has no effect for PostScript input data streams.

Reverse. 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:

Note: This can also be done by changing the photometric interpretation of pixels for the input or output data stream, either using image configurations or the photometric interpretation fields that describe the input and output data streams.

Severity level. The severity level of error required to end the conversion or print request when yes is specified for the cancel on error field. Valid values are 0 through 99.

Space provided for feedback structure. The length of the storage that is provided for the Feedback Structure Format. The length must be either 0, 108, or 130.

Stretch. This parameter is not passed to any transform program registered under exit point QIBM_QIMG_TRANSFORMS. Whether, when resizing the image, to stretch the image to fit the output size exactly, or to preserve the image aspect ratio. If no, the image aspect ratio will not be changed. If yes, the horizontal and vertical dimensions of the image will be scaled independently and the aspect ratio may change if the image is resized.

Possible values are:

Note: This field has no effect for PCL or Advanced Function Printing data stream (AFPDS) output or for PostScript input data streams. It only takes effect if the image is resized; therefore this field has no effect when the resize field contains 1 or 2 and possibly for other resize values.

Vertical justify. The vertical position of an image on the page if the image is smaller than the page.

Possible values are:

Note: This field has no effect for PostScript input data streams. It also may not work as expected if the input image is larger than the page.

Input Image Structure Format

The input image structure describes the input image or print data stream.

The different formats specify the location of the input image or print data stream to be converted: file, spooled file, or main storage. The formats contain many common fields that specify attributes of the input image or print data stream:

• Data stream format
• Photometric interpretation
• Resolution units
• Horizontal resolution
• Vertical resolution

IMGI0100 Format

Use this format for input from a stream file.

IMGI0200 Format

Use this format for input from a spooled file.

This format contains fields used in combination to uniquely identify the input spooled file:

• Qualified job name
• Internal job identifier
• Internal spooled file identifier
• Spooled file name
• Spooled file number
• Job system name
• Spooled file create date
• Spooled file create time

Refer to the Open Spooled File API for information about the valid combinations of these fields.

IMGI0300 Format

Use this format for input from main storage. See the main storage input image parameter.

Field Descriptions

Data stream format. Format of the input print or image data stream. Possible values are:

Format. The format of the input image structure, determined by the location of the input data stream.

The following formats are defined:

Horizontal resolution. This parameter is not passed to any transform program registered under exit point QIBM_QIMG_TRANSFORMS.

The number of horizontal pixels per resolution unit, or the following special value:

Input object type. For format IMGI0100, the type of the input object name.

Input object name. For format IMGI0100, the input object name. For stream file object type, this is the full name of the input stream file, including path.

Internal job identifier. For format IMGI0200, the internal job identifier for the job that owns the spooled file. This field is used only when the job name component of the qualified job name field is *INT, and the other two components contain all blanks. For more information, see the List Job (QUSLJOB) API in the Work Management part.

Internal spooled file identifier. For structure format IMGI0200, the internal spooled file identifier. This field is used only when the spooled file name is *INT. For more information, see the List Spooled Files (QUSLSPL) API.

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.

The possible values are:

When the Length field is less than 146 bytes, the API assumes blanks when the spooled file name is *INT. When spooled file name is not *INT, the API assumes *ONLY.

Length. The length of this structure, which varies depending on the format specified.

When the convert field in the control structure specifies the end option, the length must be 4.

For format IMGI0100, the length must be 68 plus the length of the input object name.

For format IMGI0200, the length must be 124 or 146.

For format IMGI0300, the length must be 56.

Length of input data stream. For format IMGI0300, the length of the input data stream in main storage.

Length of input object name. For format IMGI0100, the length of the input object name.

Offset to input object name. For format IMGI0100, the offset in bytes from the start of the Input Image Structure to the input object name. This value must be 68.

Photometric interpretation. This parameter is not passed to any transform program registered under exit point QIBM_QIMG_TRANSFORMS. The interpretation of the pixel data contained in the input image or print data stream.

Possible values are:

Qualified job name. For format IMGI0200, the qualified job name for the job that owns the spooled file.

The qualified job name has three parts:

Reserved. Space reserved for future use. This field must be set to hexadecimal zero(s).

Resolution units. This parameter is not passed to any transform program registered under exit point QIBM_QIMG_TRANSFORMS. The units of measure for the horizontal and vertical resolution fields.

Possible values are:

Spooled file create date. The date the spooled file was created on the system or blank when the spooled file name is *INT. This field is considered after the job name, user name, job number, spooled file name, spooled file number, and job system name field requirements have been met.

The date must be in the CYYMMDD format or one of the following special values:

When the Length field is less than 146 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 the spooled file was created on the system or blank when the spooled file name is *INT. This field must be set to blanks when special values *LAST or *ONLY are used for field Spooled file create date. This field must have a value set if a date is specified for field Spooled file create date. 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:

When the Length field is less than 146 bytes, the API assumes blanks for this field.

Spooled file name. For format IMGI0200, the spooled file name. The special value *INT means that the internal spooled file identifier is used.

Spooled file number. For format IMGI0200, the spooled file number. When the spooled file name is given (that is, not *INT), this uniquely identifies the spooled file if the job has multiple spooled files with the same name.

The following special values are allowed:

Vertical resolution. This parameter is not passed to any transform program registered under exit point QIBM_QIMG_TRANSFORMS.

The number of vertical pixels per resolution unit, or the following special value:

Output Image Structure Format

The output image structure describes the output image or print data stream.

The different formats specify the destination of the converted image or print data stream: file, spooled file, or main storage. The formats contain many common fields that specify attributes of the output image or print data stream:

• Data stream format
• Photometric interpretation
• Resolution units
• Horizontal and vertical resolutions
• Size units
• Horizontal and vertical sizes
• Compression type and quality
• Paper size
• User paper size units
• Horizontal and vertical user paper sizes
• Paper orientation
• Left, right, top, and bottom unprintable borders

These attribute values override any corresponding values present in the destination image configuration object, if specified.

For multipage considerations regarding some fields in this structure, see Multipage Output.

IMGO0100 Format

Use this format to store output in a stream file.

IMGO0200 Format

Use this format to store output in a spooled file.

IMGO0300 Format

Use this format to store output in main storage. See main storage output image parameter.

Note: This format is not allowed for multipage output. Refer to Multipage Output for details.

Field Descriptions

Bits per sample. This parameter is not passed to any transform program registered under exit point QIBM_QIMG_TRANSFORMS. The number of bits per image sample.

The following values are allowed:

Bottom unprintable border. The number of pixels of unprintable area on the bottom border, or the following special value:

Compression quality. This field is not used and must be set to 0.

Compression type. The algorithm used to compress the output image or print data stream.

Possible values are:

Copies. For format IMGO0200, the number of copies to produce when the spooled file is printed. The valid values for the number of copies are 1 through 255, or the special value:

Data stream format. The format of the output data stream.

Destination image configuration. The value for the image configuration object that contains fields describing the output device and data stream. The string must be filled with blanks. See Values of Destination Image Configuration for a complete list of available image configuration objects.

Field values from this image configuration will be substituted for the values of other fields in this structure, whenever the special value *IMGCFG is used for a field.

The following special values are also allowed:

Format. The format identifier of the output image structure, determined by the type of output.

The following formats are defined:

Horizontal resolution. The number of horizontal pixels per resolution unit, or the following special value:

Horizontal size. This parameter is not passed to any transform program registered under exit point QIBM_QIMG_TRANSFORMS. The size of the image in the horizontal direction, in size units. This is used to determine the size of the output image. If the stretch field in the control structure parameter is no, the aspect ratio is maintained such that the image fits within the specified size. That is, if the vertical direction determines the scale factor, the actual horizontal size may be smaller than specified. If the size units field is -2 (paper size), this field must be zero.

The following special value is allowed:

Horizontal user paper size. The size of the paper in the horizontal direction, in user paper size units. This field must be set to zero unless the value of the paper size field is -1 (user paper size).

Left unprintable border. The number of pixels of unprintable area on the left border, or the following special value:

Length. The length of the structure, which varies depending on the format specified.

When the operation field in the control structure format specifies the end option, this field must be set to 4.

For format IMGO0100, the length must be 144 plus the length of the output object name.

For format IMGO0200, the length must be 200.

For format IMGO0300, the length must be 132.

Length of output object name. For format IMGO0100, the length of the output object name.

Offset to output object name. For format IMGO0100, the offset in bytes from the start of the output image structure to the input object name. This value must be 144.

Output device. For format IMGO0200, the name of the output device. This field is used to get the default device characteristics if a destination image configuration is not given. If the output queue is configured with a remote location, any device attributes will be retrieved on the output queue.

The following special values are allowed:

Output object name. For format IMGO0100, the output object name. For stream file object type, this is the full name of the output stream file, including path.

Output object type. For format IMGO0100, the type of the output object name.

The possible value follows:

Output queue. For format IMGO0200, the name of the output queue. The first 10 characters contain the output queue and the second 10 characters contain the name of the library in which the output queue resides. For AFPDS output, only valid device output queues are allowed.

The following special values are allowed:

Output queue library name. The name of the library that contains the output queue.

The following special values are supported for the library name:

Paper orientation. How the output is oriented on paper.

Possible values follow:

Paper 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:

Photometric interpretation. This parameter is not passed to any transform program registered under exit point QIBM_QIMG_TRANSFORMS. The interpretation of the pixel data that is contained in the output image or print data stream.

Possible values are:

Printer file. For format IMGO0200, the name of a printer file.

An IBM supplied printer file, such as QSYSPRT in library QSYS, may be used if desired.

Printer file library name. The name of the library that contains the printer file.

The following special values are supported for the library name:

Request spooled feedback. For format IMGO0200, whether spooled file identification feedback is requested. See Feedback Structure Format for details about the information returned. The information is returned only when it is requested using this field.

Possible values are:

Reserved. Space reserved for future use. This field must be set to hexadecimal zero(s).

Resolution units. This parameter is not passed to any transform program registered under exit point QIBM_QIMG_TRANSFORMS. The units of measure of the horizontal and vertical resolution fields.

Possible values follow:

Right unprintable border. The number of pixels of unprintable area on the right border, or the following special value:

Save. For format IMGO0200, whether the spooled file will be saved on the output queue after printing.

Possible values are:

Size units. This parameter is not passed to any transform program registered under exit point QIBM_QIMG_TRANSFORMS. The units of measure of the horizontal and vertical size fields.

Possible values are:

Space provided. For format IMGO0300, the number of bytes of main storage provided for the output data stream in the main storage output image parameter. If the converted data stream will not fit within the space provided, an error condition is returned.

Top unprintable border. The number of pixels of unprintable area on the top border, or the following special value:

User data. For format IMGO0200, up to 10 characters of information to be displayed on the WRKSPLF screen.

The following special value is allowed:

User paper size units. This parameter is not passed to any transform program registered under exit point QIBM_QIMG_TRANSFORMS. The units of measure of the horizontal and vertical user paper size fields. This field must be zero unless the value of the paper size field is -1 (user paper size).

Possible values are:

Vertical resolution. The number of vertical pixels per resolution unit, or the following special value:

Vertical size. This parameter is not passed to any transform program registered under exit point QIBM_QIMG_TRANSFORMS. The size of the image in the vertical direction, in size units. This is used to determine the size of the output image. If the stretch field in the control structure parameter is no, the aspect ratio is maintained such that the image fits within the specified size. That is, if the horizontal direction determines the scale factor, the actual vertical size may be smaller than specified. If the size units field is -2 (paper size), this field must be zero.

The following special value is allowed:

Vertical user paper size. The size of the paper in the vertical direction, in user paper size units. This field must be set to zero unless the value of paper size is -1 (user paper size).

Feedback Structure Format

The feedback structure returns additional output information from the API, such as a spooled file identifier, size of main storage output, or a handle for future API calls for multipage output.

This structure contains output data that is returned for any of the following conditions:

• The operation field in the control structure specifies first.

  The handle for multipage output is returned. This returned handle is required as input in the control structure on subsequent API calls where append, last, or end is specified for the operation field.

• The request spooled feedback field in the output image structure specifies yes.

  Spooled file information is returned, if requested, when a spooled file is created by the conversion.

• The output image structure format parameter uses format IMGO0300.

  The length of the output data stream is returned. This is the length of the data stream stored in the main storage output image parameter.

Field Descriptions

Handle for multipage output. When first is specified for the operation field in the control structure format, this field is returned. For all other values of the operation field, this field is set to hexadecimal zeros.

Internal job identifier. When spooled feedback is requested, the internal identifier of the job that is creating the spooled file (the job in which this API is called).

Internal spooled file identifier. When spooled feedback is requested, the internal identifier of the created spooled file.

Job name. When spooled feedback is requested, the name of the job that owns the spooled file (the job in which this API is called).

Job number. When spooled feedback is requested, the number of the job that owns the spooled file (the job in which this API is called).

Job system name. The name of the system where the job that created the spooled file ran (the job in which this API is called).

Job user name. When spooled feedback is requested, the user name of the job that generated the spooled file (the job in which this API is called).

Output data stream length. When the format field in the output image structure is IMGO0300, this field contains the length of the output data stream in main storage. This is the length of the data stream that is stored in the main storage output image.

Spooled file create date. When spooled feedback is requested, 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 on the date format.

Spooled file create time. When spooled feedback is requested, 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 on the time format.

Spooled file name. When spooled feedback is requested, the name of the created spooled file.

Spooled file number. When spooled feedback is requested, the number of the created spooled file.

Multipage Output

For the operation field in the control structure, the first, append, last, and end options are related. These are used to iteratively call the API with multiple input data streams, while producing a single output data stream. The output data stream format, specified on the first call, must be AFPDS (Advanced Function Printing data stream), PostScript, or PCL (Printer Control Language). Calls that use these options must all be done in the same job, and must follow a prescribed sequence:

1. A single first call
2. Any number of append calls
3. A single last or end call

After a first call, only append, last, or end calls are allowed until the sequence is finished by a last or end call. For example, an immediate call following a first call is not allowed.

The end option is like the last option in that it ends the sequence of calls. However, no input data stream processing is done when end is specified; therefore, no new pages are added to the output data stream.

Parameter rules are defined for multipage output, which are summarized in the Parameters for Multipage Output table below. In particular:

1. When the first option is specified, a handle is returned in the feedback structure. This handle must be specified in the control structure on all subsequent API calls that specify the append, last, and end options.
2. When the append or last options are specified, the following field values in the output image structure are ignored. These fields are as follows:
   • Length
   • Format
   • Destination image configuration
   • Data stream format
   • Paper size
   • User paper size units
   • Horizontal user paper size
   • Vertical user paper size
   • Output object type (format IMGO0100)
   • Length of output object name (format IMGO0100)
   • Output object name (format IMGO0100)
   • Output device (format IMGO0200)
   • Output queue (format IMGO0200)
   • Printer file (format IMGO0200)
   • User data (format IMGO0200)
   • Copies (format IMGO0200)
   • Save (format IMGO0200)
   • Request spooled feedback (format IMGO0200)

   If one of these field values changes, the value from the first call is used.

3. When the end option is specified, the length field in both the input image structure and the output image structure must be set to 4, and the length field in the control structure must be set to 52. Again, this is because no other information is accepted in these parameters.

Parameters for Multipage Output

Legend:

Color Reduction Field

The color reduction field of the control structure determines the characteristics of the output data stream according to the following table. In this table, the input image type is the type of the actual input image file. The output image type is the type of the data that is printed or stored in a file. The destination image type is the type of output file that is described in the output image structure, determined by the two fields, photometric interpretation and bits per sample. A -- (dash) means that the value does not affect the result for that combination.

Values of Destination Image Configuration

The following special values are allowed for the destination image configuration field of parameter 4. Each special value is described in terms of the data streams supported, the maximum resolution in dots per inch (dpi), and whether the printer has color or supports compression.

Printers supporting PCL data streams

Printers supporting PostScript data streams

Printers supporting IPDS data streams

Printers supporting PCL and PostScript data streams

The recommended image configuration objects are listed below for some common printers.

Error Messages