Learn the color printing capabilities that are available "out of the box" on IBM i.

SNA Character Stream (SCS) printer files produce output that is as exciting as watching grass grow. Advanced Function Presentation (AFP) printer files are better, thanks to features provided by the BARCODE, BOX, COLOR, FONT, and other keywords. But did you know that AFP printer files also allow color elements to be printed on an HP-compatible color laser printer or included automatically in a PDF? This article will address the features the average shop can already utilize without buying anything special.

The reader should have an understanding of software development using IBM i printer files and general printer configuration knowledge. When discussing color printing, there are two distinct considerations: printing a spool file to an HP-compatible printer using the feature in IBM i known as Host Print Transform (a few features are available) and automatically converting a spool file to a PDF (quite a few features are available).

When using Host Print Transform (HPT), a developer can send color elements to a PCL (HP-compatible) color laser printer. This article will not discuss printing color to a high-end AFPDS- or IPDS-capable printer.

In order for everything to work correctly, please make sure your IBM i printer device or remote output queue for your color printer is configured with Host Print Transform set to *YES and is defined with a manufacturer type and model that is compatible with your color printer (see the references section below for more info on how to select the correct settings for your particular printer). Any spool files that use an advanced function presentation feature such as COLOR, BARCODE, etc. will require the printer file to be defined with a device type of *AFPDS (Advanced Function Presentation Data Stream). *IPDS printer files also support these features but this article will not cover *IPDS because it is not supported by Host Print Transform.

Also, this article will not discuss spool file-to-PDF conversions performed by the InfoPrint Server licensed program or other third-party conversion tools; rather, the scope will be restricted to the built-in PDF support that comes native with IBM i 6.1 and later. This feature is exciting because printer files can include references to JPG and TIFF image files that will display in a PDF.

Supported Features When Using *AFPDS Printer Files and Host Print Transform

It may surprise you that DDS printer files (as well as display files) support the COLOR keyword. The valid parameter values for COLOR include a whopping eight predefined colors as shown here!

In case you're wondering, these specific colors go way back to the days when color printers used color ribbons!

Within a printer file definition, the COLOR keyword can be used with literals (shown below) or data fields (not shown):

** COMPILE WITH DEVTYPE(*AFPDS) PAGESIZE(66 80)

A         R HDRR                     SKIPB(3)

A                                     2'IBM i Access'

A                                   +1'RunSQL Scripts'

A                                     COLOR(BLU)

A                                   +1'Tutorial'

A                                     2'The RunSQL Window looks like this:'

A                                     SPACEB(2)

In this DDS example, the text 'RunSQL Scripts' will print in blue, while the rest of the text is printed in black. COLOR can also be combined with other keywords, such as FONT. The following literal in the DDS code will print using the Century Schoolbook font in turquoise:

A        R FNTR

A                                 50 25'Page 1 of 5'

A                                     FONT(16951 (*POINTSIZE 12))

A                                     COLOR(TRQ)

If you're hoping to print spool files directly to a supported laser printer with a bare-bones IBM i OS, using these eight colors is as about as exciting as it gets. Here's a bit of bad news. There are other COLOR options beyond the default eight (for example, you can specify RGB values for a custom color), but from what I've found from experimentation and reports online, Host Print Transform will not render custom colors when printing to a printer.

However, if you have the Print Services Facility (PSF) licensed program installed, the BOX and LINE keywords can be used, and they support a color parameter. The following format will produce an image as shown in Figure 1 on paper (or in a PDF):

A         R BOXR                                      

A                                     BOX(1 1 3 3 *NARROW

A                                     (*COLOR RED))    

A                                     BOX(2 2 4 4 *NARROW

A                                     (*COLOR GRN))    

A                                     BOX(3 3 5 5 *NARROW

A                                     (*COLOR YLW))    

Figure 1: The format above will print these boxes in color.

Based on the supplied parameters, the red box's upper left corner is printed at one inch from the top margin and one inch from the left. The lower right corner is positioned at three inches down and three inches across so that the box size is a two inch square. The unit of measure for the coordinates and lengths is taken from the printer file's unit of measure (UOM) setting. The green and yellow boxes are built similar to the red box with different corner coordinates.

The BOX keyword offers a shading option. I'll save you the trouble of trying to use it, as it doesn't appear to work either (with direct printing or PDF). Online reports confirmed this conclusion. If someone has figured out how to do this, please post instructions in the forums section at the end of this article.

Note: When opening a printer file for output to a PDF (I'll get to this a bit later), the PSF licensed program features are not required to use the LINE and BOX keywords.

I successfully tested these features by printing a spool file with these color elements to a Xerox Workcentre 6400X from an IBM i 7.1 box (although earlier releases should be supported as well). I used an i Access printer emulation session (a *LAN-attached printer or remote output queue would work as well). In the device description, Host Print Transform was set to *YES, and the manufacturing type and model, for this printer type, can be set to either *HPCOLORLJ or *LEXMARKC750. IBM lists most supported color laser printers as compatible with either of these two settings.

Xerox also offers its own workstation customizing objects (i.e., similar in function to a Windows printer driver) with its free XTOOLS product, but I stuck with the generic IBM-supplied manufacturer type and model for this article. If you have a manufacturer-specific WSCST, I recommend you use it! Incidentally, the color brown was indistinguishable from red when printing to the Xerox printer using *HPCOLORLJ.

I should note that I tried to print color using an HP inkjet printer and the *HPCOLORLJ manufacturer type and model. Using an HP OfficeJet 8500A, I was able to get some text (and text only) to appear in color. However, there was something wrong; the last page of the spool file would not spit out with a form feed. Thereafter, some fixes were loaded onto the IBM I, and I found I could no longer print to the inkjet. From what I can tell on IBM's site, color laser printers and color inkjet printers each support a different subset of PCL. While you may be able to get basic color text to print, using inkjets for color printing doesn't appear to be supported. As you might imagine, you can print a color spool file to a non-color printer without issue.

Keep in mind that specialized printing can be a tricky thing and may not work right the first time, so double-check your configuration and keep trying. Over the years, I've worked with a wide variety of IBM i-connected printers, ranging from small receipt printers to large copiers. With some configuration or programming, they're able to staple, hole punch, print in color, and in the case of the receipt printer, even open an attached cash drawer!

Supported Features When Using *AFPDS Printer Files and PDF Conversion

Moving along to generating PDFs, if your shop creates a PDF from a spool file, then you have additional features available: using custom colors and embedding JPG and TIFF images.

Since IBM i 6.1, the ability to generate a PDF from a spool file has been super easy (and requires no extra software). One of the simplest ways to accomplish this is to use the OVRPRTF command and specify the TO_STMF (to stream file) and WSCST parameters. Here is an example (with the SCOPE keyword being optional):

OVRPRTF MY_PRTF TO_STMF('/tmp/Report.pdf') WSCST(*PDF) SCOPE(*JOB)

When a program opens and populates printer file MY_PRTF, IBM i will automatically create and populate a PDF and place it on the IFS with the supplied path and file name. If the PDF file already exists, the operation will fail with message ID CPF4208 ("File not opened"). It's the developer's job to make sure that the PDF file name is unique or that a pre-existing file is removed before opening the printer file (while the PDF conversion override is in effect).

For an example using a custom color, the record format below will draw a four-inch vertical line with the upper left corner at one inch from the top and six inches from the left margin. The width of the line is 1/10^th of an inch. Instead of supplying one of the eight predefined colors, the *RGB option can be used to supply a custom color. Shown here, the custom color "silver" is specified in RGB format:

A         R LINER

A                                     LINE(1 6 4 *VRT .1 *LEFT

A                                     (*COLOR *RGB 75 75 75))

Don't confuse this unique RGB format with the standard RGB values used in Web development. Normally, each color component (red, green, blue) is specified using values 0 through 255. However, when using COLOR *RGB in DDS, you specify a percentage from 0 to 100.

To come up with the color "silver," I looked online and found that its normal RGB component values are R:192, G:192, and B:192 (based on the 0-255 scale for each color component). To convert these values to a percentage (with 255 representing 100% "strength"), I just divided 192 by 255 to get a percentage value of 75 for each component. There are many tools and online websites that will let you pick a color and give you the standard RGB values. When using *RGB in DDS, just divide each of these numbers by 255 to get the required percentage value. The BOX and LINE keywords also support this custom color support using *RGB.

As for pictures, the AFP resource (AFPRSC) keyword can render a JPG or TIFF image. This example assumes the printer file's unit of measure is in inches.

A         R IMGR

A                                     AFPRSC('RunSQL.jpg' -

A                                     *JFIF 1.5 .5         -

A                                     (*PATH '/tmp')       -

A                                      (*MAPOPT *ST)       -

A                                     (*SIZE 6 3))

There are quite a few parameters, most of which can be with either a literal or a data field (so the image name, for example, can be supplied dynamically by a program). The above example has the following parameters supplied:

• Resource name—Name of the image file (in this case, RunSQL.jpg)
• Object Type—Type of image; use *JFIF for a JPG and *TIFF for a TIFF file
• Position Down—Start position from top of page (expressed in the printer file's unit of measure)
• Position Across—Start position from the left of the page (expressed in printer file's UOM)
• Path—Image path on the IFS (in this case, the image is in the /tmp folder)
• Mapping Option—See the AFPRSC documentation for the available options. In this case, the specified *ST value is "scale to fit."
• Size—The horizontal and vertical dimensions used to render the image (expressed in the printer file's UOM). This is useful when used with "scale to fit" because the system will automatically resize the image. If you're printing a catalog with images, you can automatically resize an image to a consistent full-size or "thumbnail"-size image.

In summary, the above AFPRSC format will print IFS image /tmp/RunSQL.jpg with its upper left corner 1.5 inches down from the top margin and .5 inches from the left of the page. The image will be scaled to fit into a six-inch-wide by three-inch-high rectangle.

Combined with some of the other elements shown previously, the resulting document with color text and RunSQL.jpg image look like Figure 2 when rendered as a PDF:

Figure 2: Pretty snazzy for the product of a green-screen printer file!

When using AFPRSC, observe the following:

• The AFPRSC image data is not embedded in the spool file but is rendered at run time by the PDF converter. As for printing these images to a color printer using Host Print Transform, it doesn't work. The problem appears to be that the HPT component that converts AFP to PCL doesn't support many features in the realm of color. Fortunately, the PDF conversion process does.
• I have not been able to get a color picture to render in the Windows-based AFP Image Viewer. This is just an FYI for those who may try to view a spool file using this tool.
• As of i7.1, a maximum of 10 AFPRSC images may be specified on a single page. Otherwise, you will get the following error: CPD6F90 Maximum number of AFPRSC objects to print exceeded.
• I tested a few older JPG images (created in the early '90s) with AFPRSC, but they would not render. I don't know enough about image formats to know why this occurred, although I found that resaving the images with a current tool fixed the problem.
• Even though my examples show constant values, these values can also be data fields with values supplied by an RPG or COBOL program.
• For those who would like to natively print a PDF with these features, once you have a PDF document, it is possible to convert it back to PCL or PostScript using a tool like GhostScript running in the PASE environment. Once you have raw PCL or PostScript data, you can place it in a UserAscii spool file and send it to a printer. However, it may be cheaper to buy the right printer rather than smooth out all of the development complexities of working around the limitations of Host Print Transform. I have not tried this; I just think it can be accomplished with blood, sweat, and tears.

To recap, when working with printer files and color, here are the available features depending on the output (printer or PDF):

Printing to a color laser printer using Host Print Transform includes:

• Eight basic colors for text using the COLOR keyword
• Colored boxes and lines using BOX and LINE keywords (only if PSF is installed)

Generating a PDF (requires IBM i 6.1) additionally supports these features:

• Custom colors using the COLOR keyword
• Colored boxes and lines (PSF not required)
• JPG and TIFF Images (maximum of 10 per page)

Color is a great addition to any report. It can be used to highlight hyperlinks in blue, print negative balances in red, or show positive performance indicators in green. Further, when creating PDF documents from spool files, custom colors and standard PC images can be embedded. If you have color printers on your network, why not take advantage of them?

Resources

COLOR (Color) keyword in printer files

BOX (Box) keyword in printer files

LINE (Line) Keyword in printer files

AFPRSC (AFP Resource) keyword in printer files

With 6.1, PDF Capability Is "Pretty Darn Fast"!

What You Need to Know to Convert Spooled Files to PDF (and More)!

HOST PRINT TRANSFORM RESTRICTIONS

Information on Printers from Various Manufacturers—Use this link as a starting point to see if your color printer has a supported manufacturer type and model setting.

Also Read

Partner TechTip: End the Scourge of Ugly Forms!

Partner TechTip: The Pursuit of a Paperless Process

It's Just Another Day, But Do You Know What Your Reports Are Doing?