AFP can add some pizzazz to your reports. It lets you do things such as print lines or boxes, use fonts, print graphics, and even print rotated text or barcodes on your reports. And adding any of these is as simple as adding keywords to your existing external printer file DDS. The best part is that you can print AFP printer files to an IPDS printer or any Hewlett-Packard Printer Control Language (PCL)-compatible printer set up to use the Host Print Transform (HPT) function. I’ll start by going over the configuration requirements for using AFP.

It’s a Hardware Issue

Or it could be a software issue, depending on how you go about it. To use AFP, you can use a printer that supports AFP—including any printer that has IPDS capabilities and is configured as AFP(*YES) on its device description. IBM makes several different printers that support IPDS, but you can also purchase SIMMs (single in-line memory modules) from third-party manufacturers such as i-data to add this functionality to your existing printers.

The cheaper alternative is to use HPT. This option requires no additional hardware and uses software to translate the AFP data stream into PCL. Most laser printers on the market today speak this printer language.

To use HPT, you simply need to make sure that the printer device description is defined with the parameter TRANSFORM (*YES) MFGTPMDL(your printer), where your printer is the special value that matches your printer manufacturer and model or is compatible with your printer. You will need to end the writer associated with the printer and vary off the printer device prior to making this change. Once you’ve completed the change, you can vary the device back on and restart the printer writer.

The drawback to using HPT is that a printer file that uses many AFP functions will take longer to generate on a PCL machine than it would to generate on a native AFP printer. If you are in an environment that requires you to print large volumes of printer files containing AFP keywords, you’ll probably want to consider purchasing an IPDS printer or SIMM. Otherwise, HPT is a great choice. In any case, with some small configuration changes, you will be ready to go in no time.

The Keys to AFP

A select set of DDS keywords gives you the ability to add AFP functions to your external printer file. Figure 1 (page 36) shows a list of these keywords and a description of the functions they perform. I’ll examine each of these and explain how they are used, starting with the keywords for creating graphics.

A Picture’s Worth a Thousand Words

OS/400 supplies a robust set of keywords for drawing anything from a simple line up to a complex graphic or form. For example, the BOX keyword will draw a box of a specified size. The keyword is used at record level and is specified in the format BOX(Start position down, Start position over, End position down, End position over, Line weight). The first two parameters define the upper-left corner of the box, while the next two parameters define the lower-right corner of the box.

With each of these parameters, as with any of the keywords I’ll be going over that define position or size, the values are specified in the unit of measure as defined on the UOM parameter on the Create Printer File (CRTPRTF) command. The Line weight parameter can contain either a numeric value ranging from .001” to 22.75” or one of three special values: *NARROW, which gives a line width of .008”; *MEDIUM, which results in a line width of .017”; or *WIDE, which defines a line width of .025”. You can define any of these parameters using a program-to-system field with a length of five characters and three decimal places. A program-to-system field is a hidden field used to transfer data from your program to a parameter on a DDS keyword. When you use a program-to-system field for the Line weight parameter, you cannot specify the special values. Assuming that the printer file was compiled with the UOM parameter set to *INCHES, the keyword BOX
(1.5, 1.5, 6.5, 6.5, *MEDIUM) would draw a 5” x 5” box starting 1.5” in from the top and left side of the page with a medium weight.

The LINE keyword is very similar to the BOX parameter. This keyword is specified in the format LINE (Start position down, Start position across, Line length, Line direction, Line weight, Line pad [optional]). The Start position parameters work in the same way they do for the BOX keyword. The next parameter, Line length, defines the absolute length of the line to be drawn. The Line direction parameter is specified as *HRZ for a horizontal line, or *VRT for a vertical line. You specify Line weight just as you did for the BOX parameter. The op-tional Line pad parameter specifies the part of the page toward which the line should be drawn. The options for Line pad are *TOP to draw the line from the start position toward the top of the page, *BOT to draw from the start position toward the bottom of the page, *LEFT to draw a line from the start position toward the left side of the page, or *RIGHT to draw a line from the start position toward the right side of the page. *TOP and *BOT are valid only when *VRT is specified for line direction, and *LEFT and *RIGHT are valid only when *HRZ is specified for line direction. If no value is specified, *BOT is used for vertical lines and *RIGHT is used for horizontal lines. You can use the Line weight and Line pad parameters together within an AFP printer file to generate a form to print with your document.

An easier way to achieve this result is to use an overlay. An overlay is basically an image that is drawn underneath the text when the page is output. One of the primary uses of overlays is to create a form for a document such as a purchase order or an invoice. (For a detailed description of how to create AFP overlays, see my article “May the (AFP Overlay) Forms Be with You” in the May 2000 issue of MC.)

You specify the OVERLAY keyword at record level. It defines the overlay you want to use on the current page. The OVERLAY keyword is coded in the format OVERLAY (Library name/Overlay name, Position down, Position across, *ROTATION degree of rotation). As with most of these keywords, you can specify all of the parameters with the OVERLAY keyword using either a constant value or a program-to-system field.

The Library name parameter and *ROTATION parameter are optional. The others are required. If no library is specified, the system searches for the overlay in the library list of the job creating the spool file. Use the Position down and Position across parameters to define the positioning of the upper-right corner of the overlay. Valid values for the *ROTATION parameter are 0, 90, 180, and 270 degrees. It’s important to note that overlays are not automatically rotated when the PAGRTT parameter is used on the CRTPRTF command.

When you use the OVERLAY keyword in a record format, any other fields defined within that same format must be positioned using the POSITION keyword, which uses the format POSITION(Position down, Position across). This keyword lets you specify the position on the page that a field is displayed using the unit of measure specified on the UOM parameter of the CRTPRTF command.

Page segments are similar to overlays with two exceptions. First and foremost, page segments are defined using the PAGSEG keyword, which has the format PAGSEG(Library name/Page segment name, Position down, Position across, *SIZE Width/height, *ROTATION degree of rotation). The second difference is the *SIZE option, which lets you limit the height and width that a page segment takes up on the printed page. You use the other parameters in the same way you used them with the OVERLAY keyword. The *SIZE parameter is optional and is specified as *SIZE followed by the width and height. You must specify both width and height when you use the parameter.

Finally, the GDF keyword lets you include data from a graphic data file within your printer file. This keyword is specified at record level and is used in the format GDF(Library name/File name, File member, Top position, Right position, Graphic height, Graphic width, Graphic rotation). All parameters with the exception of the Library name parameter are required, and you can specify any of the parameters as either constants or program-to- system fields. The positioning parameters work as they do with the other keywords I’ve discussed. The height and width parameters define the size of the graphic on the page. The graphic will be scaled to the size specified; each parameter accepts values from 0” to
22.75”. You can use the rotation parameter to rotate the graphic on the page; you must specify the parameter in valid 90-degree intervals from 0 to 270. In addition, the graphic data file must follow the IBM Graphic Object Content Architecture (GOCA) standards. To find out about creating a graphic data file, see the Graphics Object Content Architecture Reference (SC41-6804).

Did I Say a Thousand Words?

Now that I’ve drawn a nice picture, I’ll add some words. In addition to the keywords that let you draw pictures on the page, you can use AFP keywords to define the look of the text on the page. You can use the CDEFNT keyword to set the coded font you want to use for printing a given constant or field. This keyword is valid at field or record level. When defined at record level, this coded font is in effect for all fields and constants in the record. The format for this keyword is CDEFNT(Library name/Coded font name, *POINTSIZE points [optional]). The Library name parameter is optional and, if not defined, defaults to *LIBL. The Coded font name parameter defines the character set and the code page for the selected coded font. The optional *POINTSIZE parameter lets you define the point size of the selected font.

Similarly, the FNTCHRSET keyword lets you select the font and point size; however, FNTCHRSET defines the character set and code page as two separate parameters. This keyword is coded FNTCHRSET(Library name/Character set, Library name/Code page, *POINTSIZE points [optional]). Again, the Library name parameters are optional and default to *LIBL. The *POINTSIZE optional parameter is specified the same way it was with the CDEFNT keyword. You can specify this keyword at field or record level.

The FONT keyword lets you specify a font by the numeric font identifier. Figure 2 (page 36) shows a partial list of numeric font values. You can find a complete list in the OS/400 CL Reference V4R4 (SC41-5722-03) under the FONT parameter of the CRTPRTF command. You can use a font value of *VECTOR to generate an outline or VECTOR font when the printer file is intended for an IBM 4234 IPDS printer. The vector font can be scaled as large or small as is required. The optional *POINTSIZE parameter is also available on this keyword. You can use the keyword TXTRTT at field level to rotate the text of a given field to the specified angle in 90-degree increments between 0 and 270 degrees. Specify this keyword by coding TXTRTT(rotation degrees).

Controlling the Page

Now I’ll show you some keywords you can use to set up the page. The page control keywords let you define the way that the printer handles the page on output.

Included in these keywords is DUPLEX. This record-level keyword specifies whether or not to print on both sides of the page. Use this keyword by specifying DUPLEX(duplex value), where duplex value is either *NO for no duplexing, *YES to print duplex with the top edge of each side printing at the same end of the page, or *TUMBLE to print duplex with the top edge of each side printing at opposite ends of the page.

In addition to the DUPLEX keyword is the FORCE keyword. To make the printer feed a new page when using duplex printing, you would use the FORCE keyword. This keyword has no parameters and is specified at record level.

Last is the ENDPAGE keyword. This keyword makes the printer eject the current page after printing the data in the record containing the keyword.

Drawing Your Own Conclusions

As you can see, the use of a few simple DDS keywords to your external printer file can completely modernize the printed output. AFP allows you to add everything from simple lines or font changes to complex graphics and barcodes. To help you get started, I’ve placed source code for a printer file and an RPG program on the Midrange Computing Web site at www.midrangecomputing.com/mc.

AFP lets you easily add flashy features to your programs. Now you know your AFP; next time won’t you print with me?

REFERENCES AND RELATED MATERIALS

• AS/400 DDS Reference Information (SC41-5712-04)
• Graphics Object Content Architecture Reference (SC41-6804)
• “May the (AFP Overlay) Forms Be with You,” Mike Faust, Midrange Computing, May 2000

• OS/400 CL Reference V4R4 (SC41-5722-03)
• OS/400 Printer Device Programming V4R4 (SC41-5713-03)

Mike Faust is a senior consultant/analyst for Retail Technologies Corporation in Orlando, Florida. Mike is also the author of the books Active Server Pages Primer, The iSeries and AS/400 Programmer's Guide to Cool Things, JavaScript for the Business Developer, and SQL Built-in Functions and Stored Procedures. You can contact Mike at This email address is being protected from spambots. You need JavaScript enabled to view it..

---

MC Press books written by Mike Faust available now on the MC Press Bookstore.

		Active Server Pages Primer Learn how to make the most of ASP while creating a fully functional ASP "shopping cart" application. List Price $79.00 Now On Sale
		JavaScript for the Business Developer Learn how JavaScript can help you create dynamic business applications with Web browser interfaces. List Price $44.95 Now On Sale
		SQL Built-in Functions and Stored Procedures Unleash the full power of SQL with these highly useful tools. List Price $49.95 Now On Sale