IBM Support

Using Transform Services to Generate PDF Stream Files instead of Spooled Files

Technote (troubleshooting)


Problem(Abstract)

This document explains a method to generate printer output as a PDF file instead of a spooled file.

Resolving the problem

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 simple way to do just that.

Note: This document was last updated on 4 February 2015.

Using Transform Services to create PDF files instead of Spooled Files

This document shows how to use Transform Services product to create PDF files instead of spooled files.


.


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, 5761TS1 on V6R1M0 (R610) i5/OS or 5770TS1 on V7R1M0 (7.1) i5/OS, 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 and i 7.1.

Warning: If product 5761TS1, or product 5770TS1 on a V7R1M0 (7.1) i5/OS system, is not installed when attempting to use the new support by specifying the To stream file (TOSTMF) or Workstation customizing object (WSCST) parameter on a printer file the following message will be issued:

CPFCE01: Required product option not available.
Cause: The function requires that product 5761TS1 option 01 be available to use.
Recovery: Use the Check Product Option (CHKPRDOPT) command to verify that product 5761TS1 option 01 has been properly installed on the system.

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."

Install Media for Transform Services

6.1 Transform Services (product 5761TS1) is available on the B29xx_02 disc, and 7.1 Transform Services (product 5770TS1) is available on the B_GROUPx_04 disc. For more information, please refer to the Media labels and their contents topic in the IBM Knowledge Center:


These products are also listed as available for download from the Electronic Software Delivery web page. For more information, please refer to the Electronic Software Delivery - Support Products web page:

http://www-947.ibm.com/systems/support/software/delivery/en_US/supported_ibmiproducts.html


Consider the Results

After changing or overriding your application printer files, you are 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 does not rely on the COR function. If you can not specify the size, most client print drivers can still "scale-to-fit" printed output.

Look at an Example

Let us 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, issue the Override with Printer File ( OVRPRTF) command, for example:

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


Then call the MYAPP program. I nstead 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 MYPRTF xxyyzz.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.

Note: In the above example, the To stream file (TOSTMF) parameter is set to a directory in the IFS ('/myapp/mydpfs'). In this case, the system will create a stream file in that directory with a unique name derived from the printer file name". However, you can also specify the full PDF file name, as long as a stream file does not already exist with that name, or example:

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

Quick Test Using the Display Library List (DSPLIBL) Command

The following instructions can be used to run a quick test of Transform Services using the Display Library List (DSPLIBL) command and the QPRTLIBL printer file:

1 The directory for your PDF stream files must already exists. If the directory you intend to use does not already exist in the Integrated File System (IFS), then use the Create Directory (MD) command to create this directory. For example:

MD DIR('/PDFs')
2 Use the Override with Printer File (OVRPRTF) command to override the QPRTLIBL printer file. For example:

OVRPRTF FILE(QPRTLIBL) DEVTYPE(*AFPDS) TOSTMF('/PDFs/library_list.pdf')
        WSCST(*PDF) OVRSCOPE(*JOB)

Note that the Device type (DEVTYPE) parameter is set to *AFPDS and the Workstation Customizing Object (WSCST) parameter is set to *PDF. The Override scope (OVRSCOPE) parameter is also set to *JOB, to ensure that the override takes affect at all calls levels in the current interactive job.
3 Use the Display Library List (DSPLIBL) command with the Output (OUTPUT) parameter set to *PRINT to generate a PDF stream file using the overrides to the QPRTLIBL printer file. For example:

DSPLIBL OUTPUT(*PRINT)
4 Use the Work with Object Links (WRKLNK) command to verify that the PDF stream file has been created in the specified IFS directory. For example:

WRKLNK OBJ('/PDFs/*')

Note: You can also use an IBM i NetServer file share or System i Navigator to work with the specified IFS directory to copy the PDF file to a directory on your PC. If using an IBM i NetServer file share, you can use Adobe Reader or another PDF-capable application to open the PDF file directly from the IFS directory by double clicking on the PDF file. For more information on using an IBM i NetServer file share to access a directory in the IFS, please refer to the following document:

N1019414: Mapping a Drive to iSeries NetServer
5 Use the Delete Override (DLTOVR) command to delete the override from Step 2. For example:

DLTOVR FILE(QPRTLIBL) LVL(*JOB)

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. If you find that you want to do more with PDF files, consider Infoprint Server for System i (5722IP1), a licensed program product (LPP) that you can try for a standard 70-day evaluation period.

Using the CPYSPLF command to copy spooled files to PDF stream files in the IFS

Starting in 7.1 i5/OS, the Copy Spooled File ( CPYSPLF) command can be used to copy spooled files to a stream file in the Integrated File System (IFS). The spooled files can optionally be converted using a workstation customizing object, which allows the spooled file to be converted to other formats. To convert the spooled files to Portable Document Format (PDF), you must download and apply 7.1 PTF SI43471 or a superseding PTF and you must also install licensed program 5770TS1, *BASE and Option 1, "IBM Transform Services for i" and "Transforms - AFP to PDF Transform".

For more information, please refer to the following document:

N1011580: New CPYSPLF function to copy SPLFs to Stream Files in the IFS

as well as the following APAR and PTF cover letters:

APAR SE47834 OSP-PRT ENHANCEMENTS TO CPYSPLF COMMAND:
7.1 PTF SI43471:

For More Information

For more information about Transform Services, please refer to the following documents:

N1019457: Options for Generating Adobe Acrobat PDF Format Files from an IBM i System Database 'DCF Technotes (IBM i)', View 'Products', Document 'Options for Generating Adobe Acrobat PDF Format Files from an IBM i System'
N1013755: Language Support for Host Print Transform and Transform Services



Keywords: 5761SS1 5761-SS1 5761TS1 5761-TS1 R610 R611 V6R1 V6R1M0 V6R1M1 6.1 6.1.1 5770SS1 5770-SS1 5770TS1 5770-TS1 R710 R711 V7R1 V7R1M0 7.1


Cross reference information
Segment Product Component Platform Version Edition
Operating System IBM i 7.2
Operating System IBM i 7.1
Operating System IBM i 6.1
Operating System IBM i 7.3

Historical Number

530456458

Document information

More support for: IBM i
Print

Software version: 6.1, 6.1.0, 6.1.1, 7.1, 7.1.0, 7.2, 7.2.0, 7.3, 7.3.0

Operating system(s): IBM i

Reference #: N1018568

Modified date: 09 April 2018