Would you like to generate Adobe PDF documents from your applications running on IBM i and store them in stream files in an IFS directory for use with client applications? IBM i 6.1 provides a new, simple way to do just that.

Get Started

Before you can generate PDF files with i 6.1, there are a few prerequisites. First, option 3 (which includes support for the IFS) and option 33 (which includes support for the Portable Application Solutions Environment or PASE) of the operating system must be installed. In addition, the IBM licensed program Transform Services for i5/OS, 5761-TS1, must have both the base option and option 1 installed. This product is free and ships as part of the bonus pack with i 6.1.

To get started generating PDF files, you need to make a couple of changes to the printer files that your applications use. To do so, use the Create Printer File (CRTPRTF), Change Printer File (CHGPRTF), or Override with Printer File (OVRPRTF) commands. The device type (DEVTYPE) parameter on these commands must be set to *AFPDS because only an Advanced Function Presentation data stream (AFPDS) can be converted to PDF with the new feature. AFPDS has the additional benefit of support for AFP resources, such as overlays, page segments, and even IFS resources (using the AFPRSC keyword in DDS) such as JPG, TIFF, and GIF files.

IBM has added two new parameters to the printer file commands, accommodating the creation of PDF files. The first new parameter is the to stream file (TOSTMF) parameter. TOSTMF lets you specify with either a directory or stream file name where you want the generated PDF to go in the IFS. If you specify a directory, it must exist when your application runs. If you specify a stream file name, that file must not exist.

The second new parameter is the workstation customization object (WSCST) parameter, which lets you specify what sort of transform you want, or whether you want any transform at all. If you specify *NONE, no transform is done and the AFPDS data stream generated is written to an IFS file. A client application that uses .afp files could then access the file directly. If a workstation customization object is specified, it must have an attribute of TRANSFORM or CTXFORM (new in i 6.1). If the attribute is type TRANSFORM, the host print transform function is called to convert the data before writing it to the stream file. This function can be useful if you want a TIF or some other data stream supported by host print transform to be written to an IFS file. If the attribute is type CTXFORM, the new AFP to PDF transform converted the data to PDF before writing it to the stream file. Three new workstation customization objects with attribute CTXFORM ship with i 6.1. One of these objects can be specified for the WSCST parameter, or you can specify WSCST(*PDF) to get the default workstation customization object for generating PDF files. The three new customization objects provide varying levels of font embedding in the generated PDF file. For more information about these new workstation customization objects and their effect on the PDF file generated, search the i 6.1 Information Center for "workstation customizing object (WSCST) parameter."

Consider the Results

After changing or overriding your application printer files, you're done. When you run your application, a stream file is created in the IFS rather than a spooled file in an output queue. If you specified a stream file name in the TOSTMF parameter, that file will now exist in the IFS. If you specified a directory, a file will have been created in that directory with the first characters being either the printer file name or the alternate spooled file name if one is specified on the printer file. The rest of the name is filled in by the operating system to ensure uniqueness. This behavior differs from that of the Infoprint Server product, which places its PDF files into the IFS and uses the job and user names to create a directory structure.

There are a couple of things to note about the PDF files generated using this feature. First, the text data in the document is preserved in standard encodings so that it is searchable. Different methods are used to preserve the text data for different languages. By default, single-byte character set (SBCS) languages are converted to Windows ANSI, which can be rendered with standard PDF fonts. The SBCS method works well for the Latin-1 languages used in the U.S., South America, and Western Europe. For double-byte character set (DBCS) languages, files reference the appropriate Adobe registered character collections and character identifier (CID) fonts. For all other languages, files must use TrueType fonts for the text (FONTNAME keyword in DDS). The *CODEPAGE or *IGCCODEPAGE parameter values can be specified for EBCDIC data or omitted for Unicode data. The TrueType font gets embedded in the PDF files with a ToUnicode CMap. If fidelity is more important than size, you can use this method for any language.

The page size of the PDF is derived from the printer file attributes without applying any Computer Output Reduction (COR), so make sure your printer file has the "correct" page size and doesn't rely on the COR function. If you can't specify the size, most client print drivers can still "scale-to-fit" printed output.

Look at an Example

Let's assume that you have an existing application consisting of a program (*PGM) object named MYAPP and a printer device file (*FILE) object named MYPRTF, where program MYAPP uses printer file MYPRTF to generate a spooled file that contains a report. Before calling MYAPP, simply issue the OVRPRTF command:

OVRPRTF   FILE(MYPRTF)  DEVTYPE(*AFPDS)
          TOSTMF('/myapp/mypdfs')  WSCST(*PDF)

Then call the MYAPP program. As Figure 1 shows, instead of generating a spooled file and placing it on an output queue, a PDF file is generated into a stream file in directory myapp/mypdfs. The name of the stream file is MYPRTFxxyyzz.pdf, where xxyyzz is determined by the operating system to ensure file name uniqueness. The file extension for the stream file is .pdf so that the file can be opened by a PDF file reader PC application that has access to the IFS directory.

Give It a Try

The i 6.1 operating system now supports generating PDF files directly from an application. It also offers support for generating AFPDS and host print transform supported data streams directly to an IFS file. Give it a try! This may be the solution you've been looking for to enable more client applications on your system. If you find that you want to do more with PDF files, consider Infoprint Server, a licensed program product (LPP) that you can try for a standard 70-day evaluation period (see "IBM Infoprint Server" below).

Kevin Vette (vette@us.ibm.com) is an advisory software engineer at IBM Rochester. He works on the spool component of i.

IBM Infoprint Server

IBM Infoprint Server, a licensed program product (LPP), provides a superset of the new PDF capability. In addition to generating PDF files, Infoprint Server provides extensive distribution functionality to intelligently route the resulting files via email, spool, or IFS in any combination. Infoprint Server also can convert any standard EBCDIC spooled file to PDF, split spooled files into logical segments or documents, and build indexes within PDF files as bookmarks. Many customers will have reason to use a combination of Infoprint Server and the PDF support in the i operating system.

—K.V.