Troubleshooting
Problem
This document explains a method to generate a PDF file instead of a spooled file by using Transform Services.
Resolving The Problem
Would you like to generate Adobe PDF documents from your applications running on IBM i 6.1 and higher, and store them in stream files in an IFS directory for use with client applications? Transform Services
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. 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.
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:
Give It a Try
The IBMi 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 IBMi 7.1 , 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:
as well as the following APAR and PTF cover letters:
APAR SE47834 OSP-PRT ENHANCEMENTS TO CPYSPLF COMMAND:
For More Information
For more information about Transform Services, please refer to the following documents:
Using Transform Services to create PDF files instead of Spooled Files
This video shows how to use Transform Services product to create PDF files instead of spooled files.
System Requirements:
Product 5770TS1, option *BASE for IBM Transform Services for i
Product 5770TS1, option 1 for Transforms - AFP to PDF Transform
Product 5770SS1, option 3 for Extended Base Directory Support
Product 5770SS1, option 33 for Portable App Solutions Environment
Product 5770TS1, option *BASE for IBM Transform Services for i
Product 5770TS1, option 1 for Transforms - AFP to PDF Transform
Product 5770SS1, option 3 for Extended Base Directory Support
Product 5770SS1, option 33 for Portable App Solutions Environment
| Warning: If Transform Services is not installed when attempting to use the product, message CPFCE01: Required product option not available, will be issued. Both product options, *BASE and 1, must be installed for all functions to work successfully. |
Install Media for Transform Services
Transform Services product 5770TS1 is available on the B_GROUPx_04 disc. For more information, refer to the Media labels and their contents topic in the IBM Knowledge Center:
These products should be available for download from the Entitled Systems Support (ESS) web page. If you do not see the product options on the site, contact the ESS support group for assistance.
Transform Services product 5770TS1 is available on the B_GROUPx_04 disc. For more information, refer to the Media labels and their contents topic in the IBM Knowledge Center:
These products should be available for download from the Entitled Systems Support (ESS) web page. If you do not see the product options on the site, contact the ESS support group for assistance.
Authority Requirements:
Transform Services uses several directories in /QOpenSys. Ensure *PUBLIC authority is *RX for:
'/QOpenSys/'
'/QOpenSys/QIBM/'
'/QOpenSys/QIBM/UserData/'
'/QOpenSys/QIBM/UserData/TransformServices/'
'/QOpenSys/QIBM/UserData/TransformServices/work/'
'/QOpenSys/QIBM/ProdData/'
'/QOpenSys/QIBM/ProdData/TransformServices/'
'/QOpenSys/QIBM/ProdData/TransformServices/afp2pdf/'
'/QOpenSys/QIBM/ProdData/TransformServices/bin/libctt.a'
'/QOpenSys/QIBM/ProdData/TransformServices/bin/'
'/QOpenSys/'
'/QOpenSys/QIBM/'
'/QOpenSys/QIBM/UserData/'
'/QOpenSys/QIBM/UserData/TransformServices/'
'/QOpenSys/QIBM/UserData/TransformServices/work/'
'/QOpenSys/QIBM/ProdData/'
'/QOpenSys/QIBM/ProdData/TransformServices/'
'/QOpenSys/QIBM/ProdData/TransformServices/afp2pdf/'
'/QOpenSys/QIBM/ProdData/TransformServices/bin/libctt.a'
'/QOpenSys/QIBM/ProdData/TransformServices/bin/'
The user creating the PDF, or *PUBLIC, must have at least *RX authority to the directory path in which the PDF will be created.
Use the Display Authority (DSPAUT) command to check the authority. Use the Change Authority (CHGAUT) command to make any necessary changes.
NOTE: The product and working directories for the product should not be saved or replicated while the product is being used. A save or replication can result in timeout scenarios and directory not available messages. To prevent the directories from being saved, use the Change Attribute (CHGATR) command. For example:
CHGATR OBJ('/QOpenSys/QIBM/UserData/TransformServices') ATR(*ALWSAV) VALUE(*NO) SUBTREE(*ALL)
CHGATR OBJ('/QOpenSys/QIBM/UserData/TransformServices/work') ATR(*ALWSAV) VALUE(*NO) SUBTREE(*ALL)
CHGATR OBJ('/QOpenSys/QIBM/UserData/TransformServices/work') ATR(*ALWSAV) VALUE(*NO) SUBTREE(*ALL)
Getting Started:
Create (CRTPRTF), change (CHGPRTF) or override (OVRPRTF) the printer file to include the necessary parameters. The necessary parameters are:
- Device Type (DEVTYPE): Must be set to *AFPDS
- To Stream File (TOSTMF): Specify the directory path and name of the PDF file. For example: /home/TestPDF.pdf
- The directory must exist.
- The user, or *PUBLIC, must have at least *RX authority to the directory.
- It is recommended that the PDF file extension, .pdf, be lower case so it is compatible with other operating systems.
- Using upper case file extension, .PDF, will still work, though the PDF file may not open, or automatically open, on all platforms. - Workstation Customizing Object (WSCST) and Library: This can be specified as *PDF. Other WSCST objects available in QSYS library are:
QCTXPDF (same as using WSCST as *PDF)
QCTXPDFMBD
QCTXPDFMB2
QCTXPDFWT
QCTXPDFWT2
QCTXPDF2
For more information about each, refer to document Language Support for Host Print Transform and Transform Services.
Consider the Results
After the application that creating, changing or overriding the printer file and the process or application runs to generate the file, there will not be a spooled file. Only a PDF file will exist in the directory path specified in the TOSTMF parameter.
After the application that creating, changing or overriding the printer file and the process or application runs to generate the file, there will not be a spooled file. Only a PDF file will exist in the directory path specified in the TOSTMF parameter.
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. 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.
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: 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 IBMi 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 IBMi 7.1 , 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:
as well as the following APAR and PTF cover letters:
APAR SE47834 OSP-PRT ENHANCEMENTS TO CPYSPLF COMMAND:
For More Information
For more information about Transform Services, please refer to the following documents:
- Options for Generating Adobe Acrobat PDF Format Files from an IBM i System
- Language Support for Host Print Transform and Transform Services
[{"Line of Business":{"code":"LOB57","label":"Power"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"a8m0z0000000CUJAA2","label":"Print->PDF Infoprint Server->Transform Services 5770TS1"}],"ARM Case Number":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"7.1.0;7.2.0;7.3.0;7.4.0;and future releases"}]
Historical Number
530456458
Was this topic helpful?
Document Information
Modified date:
03 November 2021
UID
nas8N1018568