Tue, Jun
2 New Articles

TechTip: Using Color in Printer Files on a Budget

  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

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



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))    

   031513SansoterraFigure 1                    

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




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/10th 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 nameName of the image file (in this case, RunSQL.jpg)
  • Object TypeType of image; use *JFIF for a JPG and *TIFF for a TIFF file
  • Position DownStart position from top of page (expressed in the printer file's unit of measure)
  • Position AcrossStart position from the left of the page (expressed in printer file's UOM)
  • PathImage path on the IFS (in this case, the image is in the /tmp folder)
  • Mapping OptionSee the AFPRSC documentation for the available options. In this case, the specified *ST value is "scale to fit."
  • SizeThe 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:

031513SansoterraFigure 2

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?


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)!


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


Michael Sansoterra is a DBA for Broadway Systems in Grand Rapids, Michigan. He can be contacted at This email address is being protected from spambots. You need JavaScript enabled to view it..



Support MC Press Online

$0.00 Raised:

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: